schema

{
  "id"  : 123, // {min: 1}
  "name": "Tom"
}

Pay attention to the main feature of the JSight Schema language. The basis for a data schema is an example of valid data. Additional data requirements are specified in C-like comments. This approach greatly simplifies the data schema and makes it intuitively clear. Practice shows that such schema is very simple to create, read and edit.

For details, see the JSight Schema Language Specification, in the section “EXAMPLE”.

{
    "type": "object",
    "required": [
        "id",
        "name"
    ],
    "properties": {
        "id": {
            "type": "integer",
            "minimum": 1
        },
        "name": {
            "type": "string"
        }
    },
    "examples": [{
        "id": 123,
        "name": "Tom"
    }]
}

{
  "productId": 1,
  "productName": "An ice sculpture",
  "price": 12.50,    // {min: 0, exclusiveMinimum: true}
  "tags": [          // {minItems: 1, optional: true}
    "cold", 
    "ice"
  ],
  "dimensions": {    // {optional: true}
    "length": 7.0,
    "width": 12.0,
    "height": 9.5
  }
}

The JSight Schema language is especially useful when describing nested objects and arrays, which are very common in real life. You simply give an example of a valid array or object, and add small clarifying comments.

It is much more complicated in JSON Schema and other languages.

For details, see the JSight Schema Language Specification, sections:

• EXAMPLE requirements for object PROPERTIES,
• EXAMPLE requirements for array ELEMENTS.

{
  "type": "object",
  "properties": {
    "productId": {
      "type": "integer"
    },
    "productName": {
      "type": "string"
    },
    "price": {
      "type": "number",
      "exclusiveMinimum": 0
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1
    },
    "dimensions": {
      "type": "object",
      "properties": {
        "length": {
          "type": "number"
        },
        "width": {
          "type": "number"
        },
        "height": {
          "type": "number"
        }
      },
      "required": [ "length", "width", "height" ]
    }
  },
  "required": ["productId","productName","price"],
  "examples": [{
    "productId": 1,
    "productName": "An ice sculpture",
    "price": 12.50,
    "tags": [ "cold", "ice" ],
    "dimensions": {
      "length": 7.0,
      "width": 12.0,
      "height": 9.5
    }
  }]
}

This example was created based on the official Getting Started instructions of the JSON-Schema standard.

{ // A product from Acme's catalog.
  "productId": 1,                    // The unique id.
  "productName": "An ice sculpture", // Name of the product.
  
  "price": 12.50, /* {
                       min: 0, 
                       exclusiveMinimum: true
                     } 
                     - The price. */

  "tags": [   /* {minItems: 1, optional: true}    
                 - Tags for the product. */
    "cold", 
    "ice"
  ],
  "dimensions": { // {optional: true} - The dimensions.
    "length": 7.0,
    "width": 12.0,
    "height": 9.5
  }
}

Here is the same schema as in the previous example, only property descriptions have been added.

Property descriptions are written in C-like comments. If there are rules in the comments, then the property descriptions are separated by a hyphen.

For details, see the JSight Schema Language Specification, section “Text notes to RULES”.

{
  "type": "object",
  "description": "A product from Acme's catalog.",
  "properties": {
    "productId": {
      "description": "The unique id.",
      "type": "integer"
    },
    "productName": {
      "description": "Name of the product.",
      "type": "string"
    },
    "price": {
      "description": "The price.",
      "type": "number",
      "exclusiveMinimum": 0
    },
    "tags": {
      "description": "Tags for the product.",
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1
    },
    "dimensions": {
      "description": "The dimensions.",
      "type": "object",
      "properties": {
        "length": {
          "type": "number"
        },
        "width": {
          "type": "number"
        },
        "height": {
          "type": "number"
        }
      },
      "required": ["length", "width", "height"]
    }
  },
  "required": ["productId","productName","price"],
  "examples": [{
    "productId": 1,
    "productName": "An ice sculpture",
    "price": 12.50,
    "tags": [ "cold", "ice" ],
    "dimensions": {
      "length": 7.0,
      "width": 12.0,
      "height": 9.5
    }
  }]
}

{
  "id"        : 123,
  "name"      : "Tom",
  "email"     : "tom@cats.com",              // {type: "email"   }
  "website"   : "http://tom.cats.com",       // {type: "uri"     }
  "birthday"  : "2006-01-02",                // {type: "date"    }
  "registered": "2021-01-02T07:23:12+03:00", // {type: "datetime"}
  "uuid": "550e8400-e29b-41d4-a716-446655440000" // {type: "uuid"}
}

JSight Schema supports several additional built-in data types that are required for actual work.

Read more about built-in data types in the JSight Schema Language Specification, section “RULE "type"”.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "examples": [123]
    },
    "name": {
      "type": "string",
      "examples": ["Tom"]
    },
    "email": {
      "type": "string",
      "format": "email",
      "examples": ["tom@cats.com"]
    },
    "website": {
      "type": "string",
      "format": "uri",
      "examples": ["http://tom.cats.com"]
    },
    "birthday": {
      "type": "string",
      "format": "date",
      "examples": ["2006-01-02"]
    },
    "registered": {
      "type": "string",
      "format": "date-time",
      "examples": ["2021-01-02T07:23:12+03:00"]
    },
    "uuid": {
      "type": "string",
      "format": "uuid",
      "examples": [
        "550e8400-e29b-41d4-a716-446655440000"
      ]
    }
  },
  "required": [
    "id",
    "name",
    "email",
    "website",
    "birthday",
    "registered",
    "uuid"
  ]
}