YAML/JSON Schema Validator

Schema validation utility for YAML/JSON files against a pre defined schema

Table of Contents

• Description
• Usage
• Options
• Schema properties
• Schema File Examples
  • YAML Schema
  • JSON Schema
• Command Line Interface
  • Command Usage
  • Command Options
  • Command Alias

Description:

Validate is a utility used to check the structure of a yaml/json file against a predefined schema. The schema is expected to be a JSON or YAML file with a structure that defines type of each property. The object properties can be nested to as many levels as you like.

Usage

It's method validateSchema can be imported and used as below:

const validateSchema = require('yaml-schema-validator')

// validate a json OR yml file
validateSchema('path/to/target-file.yml', {
  schemaPath: '/path/to/required/schema.yml' // can also be schema.json
})

The method automatically detects if file format is JSON or YAML and process it accordingly.

Similarly, method can also be used to validate plain JS objects:

// validate an object
let person = { name: { first: 'Tom', last: 'Xoman' }, age: 45 }
vaidateSchema(person, {
  schemaPath: '/path/to/schema.yml' // can also be schema.json
})

// validate against a JS schema object
const requiredSchema = {
  name: {
    first: { type: String, required: true },
    last: { type: String, required: true }
  },
  age: { type : Number }
}
schemaErrors = validateSchema(person, { schema: requiredSchema })

Compare two objects' schema

If you don't have a schema object built, but you just want to compare if structure of two objects is same, then you can use schemaObj option to pass the expected object:

let person = { name: { first: 'Tom', last: 'Xoman' }, age: 'something' }
let idealPerson = { name: { first: 'Tom', last: 'Xoman' }, age: 45 }
vaidateSchema(person, {    // compares the structure of person object against
  schemaObj: idealPerson   // anotherPerson object.
})

Schema validator validates the target file against the passed schema and lists down the mismatches in the structure:

It returns an array of errors showing the mismatches:

[{path: 'person.id', message: 'person.id must be a String'}]

Custom validators

Custom validators can be defined by passing an object with named validators to .use:

// custom validation function checking value for a regex
const checkHexColor = val => {
  return /^#[0-9a-fA-F]$/.test(val)
}

const car = new Schema({
  color: {
    type: String,
    use: { checkHexColor }
  }
})

Custom error messages

Define a custom error message for the validator:

car.message({
  checkHexColor: path => `${path} must be a valid hex color.`
})

Options

options parameter passed as the second argument in the validate schema method.

validateSchema(targetObject, options);

It has following configurable options available:

• schema: javascript object having the schema structure (eg: {name: { type: String, required: true })
• schemaPath: path to the json/yaml file having the schema
• schemaObj: Used when you directly want to compare the target with a structure of another object. Pass the expected object in this option to verify the target object is having the similar structure
• logLevel: specify the level of logging while validating schem. Possible values ['none', 'error', 'warn', 'verbose'] . By default the logLevel is set to error

Schema properties

• type: field that can be boolean | string | number to define type of value of that property
• required: field can be set to true if the property is required in target file
• length : feild can be used for string values to check minimum and max length of string. example length: { min: 3, max: 32 }
• use : an object of custom validation methods to be checked for a particular field. Each function in use object should take value param as input and return a boolean.

Schema File Examples

YAML Schema

---
person:
  name:
    first_name:
      type: string
  age:
    type: number
    required: true
  employeed:
    type: boolean
  hobbies:
  - type: string

JSON Schema

{
  "person": {
    "names": {
      "first_name": { "type": "string", "length": { "min": 3, "max": 32 } },
      "last_name": { "type": "string" }
    },
    "id": { "type": "string" },
    "age": { "type": "number", "required": true },
    "employeed": { "type": "boolean" },
    "hobbies": [{"type": "string"}],
    "attributes": [{ "foo": { "type": "string" } }]
  }
}

Command Line Interface

This package also can be used as a command line utility.

Command Usage

• Basic syntax: schema [command] [options]
• In root folder of your project, use command: schema validate -f path/to/dummy.yml -s path/to/schema.yml
• for help about the options use command: schema validate -h

Command Options

• -f, --filePath : [Required param] path to the target file for validating
• -s, --schema [schemaPath] : path to an external schema file. If not passed the schema is fetched from /examples/schema.json which is the defeault schema location.
• -o, --schema-obj [schemaObj] : stringified JSON object whose structure you want the target object to be compared with.
• -t, --target [targetObj] : stringified JSON object whose structure is to be verified
• -j, --json : Passed if target file is in JSON format
• -e, --exit-on-err : Exit process with nonzero status on errors or warnings

Command Alias

• You can also make alias for the command in your package.json. Just add the script key:

"scripts": {
  "sc": "schema"
},

and then try sc validate -f path/to/dummy.yml -s path/to/schema.yml