JSON micro schema

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
• Example
• Validators
  • $type
  • $required
  • $maxLength
  • $minLength
  • $values
  • $unknownKeys
  • $item
  • $defaults
• Shortcuts
  • Primitives
  • Arrays
• Custom validators
• Implementations
  • JavaScript
• License

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

• @vitalets/micro-schema

License

MIT @ Vitaliy Potapov