Home

Awesome

YAML/JSON Schema Validator

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

LICENSE VERSION DOWNLOADS VULNERABILITY ISSUES

Table of Contents

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:


schema-validator-listing-errors


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 properties

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

Command Options

Command Alias

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

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