JSON micro schema

December 2, 2019 ยท View on GitHub

Minimal JSON schema validation format.

Motivation

Although JSON Schema is old and mature project it looks too complex for simple JSON validation purpose. This spec is a very simple format for the most common cases.

Contents

Principles

  • All keywords started with $.
  • Built-in validators cover most common cases.
  • Custom validators can be easily added.
  • No code-generation.

Example

Schema:

{
  "productId": {
    "$type": "number",
    "$required": true
  },
  "productName": {
    "$type": "string",
    "$required": true,
    "$maxLength": 255
  },
  "tags": [{
    "$type": "string"
  }]
}

Valid object:

{
  "productId": 1,
  "productName": "iphone 11",
  "tags": [ "mobile", "phone" ]
}

Invalid object:

{
  "productId": "1",
  "productName": null,
  "tags": [ 42 ]
}

Validation errors:

[
  {
    "validator": "$type",
    "path": "productId",
    "expectedType": "number",
    "actualType": "string"
  },
  {
    "validator": "$required",
    "path": "productName"
  },
  {
    "validator": "$type",
    "path": "tags.0",
    "expectedType": "string",
    "actualType": "number"
  }
]

Validators

$type

  • string Validates type of value. Can be one of:
    • "string"
    • "number"
    • "boolean"
    • "array"

Example of schema:

{
  "productName": {
    "$type": "string"
  }
}

Valid object:

{
  "productName": "iphone 11"
}

Invalid object:

{
  "productName": 42
}

Validation error:

{
  "validator": "$type",
  "path": "productName",
  "expectedType": "string",
  "actualType": "number"
}

$required

  • boolean Validates that property exists and not null|undefined.

Example of schema:

{
  "productName": {
    "$required": true
  }
}

Valid object:

{
  "productName": "iphone 11"
}

Invalid object:

{
  "productName": null
}

Validation error:

{
  "validator": "$required",
  "path": "productName"
}

$maxLength

  • number Validates that property has length less or equal provided value. Applied to string or array.

Example of schema:

{
  "productName": {
    "$type": "string",
    "$maxLength": 10
  }
}

Valid object:

{
  "productName": "iphone 11"
}

Invalid object:

{
  "productName": "very long product name"
}

Validation error:

{
  "validator": "$maxLength",
  "path": "productName",
  "maxLength": 10,
  "length": 22
}

$minLength

  • number Validates that property has length more or equal provided value. Applied to string or array.

Example of schema:

{
  "productName": {
    "$type": "string",
    "$minLength": 2
  }
}

Valid object:

{
  "productName": "iphone 11"
}

Invalid object:

{
  "productName": "a"
}

Validation error:

{
  "validator": "$minLength",
  "path": "productName",
  "minLength": 2,
  "length": 1
}

$values

  • array Validates that property has one of provided values.

Example of schema:

{
  "productName": {
    "$type": "string",
    "$values": ["iphone", "android"]
  }
}

Valid object:

{
  "productName": "iphone"
}

Invalid object:

{
  "productName": "ipad"
}

Validation error:

{
  "validator": "$values",
  "path": "productName",
  "values": ["iphone", "android"],
  "value": "ipad"
}

$unknownKeys

  • boolean Allows object to have keys not declared in schema.

Example of schema:

{
  "product": {
    "$unknownKeys": false,
    "name": {
      "$type": "string"
    }
  }
}

Valid object:

{
  "product": {
     "name": "iphone"
  }
}

Invalid object:

{
  "product": {
     "name": "iphone",
     "model": "iphone 11"
  }
}

Validation error:

{
  "validator": "$unknownKeys",
  "path": "product.model"
}

$item

  • object Declares schema for array items. Applied only to $type: "array".

Example of schema:

{
  "tags": {
    "$type": "array",
    "$item": {
      "$type": "string"
    }
  }
}

Valid object:

{
  "tags": [ "mobile", "phone" ]
}

Invalid object:

{
  "tags": [ 42 ]
}

Validation error:

{
  "validator": "$type",
  "path": "tags.0",
  "expectedType": "string",
  "actualType": "number"
}

$defaults

  • object Declares schema that will be merged to current and all nested schemas.

Example of schema:

{
  "$defaults": {
    "$required": true
  },
  "productId": {
    "$type": "number"
  },
  "productName": {
    "$type": "string"
  }
}

Valid object:

{
  "productId": 1,
  "productName": "iphone 11"
}

Invalid object:

{
  "foo": "bar"
}

Validation errors:

[
  {
    "validator": "$required",
    "path": "productId"
  },
  {
    "validator": "$required",
    "path": "productName"
  }
]

Shortcuts

Primitives

You can declare any prop as just a value:

{
  "productType": "phone"
}

It is automatically expanded to the following schema:

{
  "productType": {
    "$type": "string",
    "$required": true,
    "$values": ["phone"]
  }
}

Arrays

Arrays can be declared in two ways:

  1. full syntax using $item validator: 
    {
  "tags": {
    "$type": "array",
    "$item": {
      "$type": "string"
    }
  }
}
  2. shortcut syntax using [] with single element: 
    {
  "tags": [{
    "$type": "string"
  }]
}

Both variants are identical.

Custom validators

You can declare any custom validators for your needs. The only rule is that it should start with $ and don't conflict with built-in validators. Example of custom $myRegexpValidator:

{
  "productId": {
    "$type": "string",
    "$myRegexpValidator": "[a-z0-9]+"
  }
}

Technical implementation of custom validator depends on library and programming language you are using.

Implementations

JavaScript

License

MIT @ Vitaliy Potapov