What is a JSON Schema?
- PIPEFORCE
What is JSON Schema?
Any valid JSON document has a specific structure of JSON fields and/or JSON arrays.
In case to make sure that a JSON document complies with an expected structure, you can define rules for such a JSON. Such rules can define for example:
The name of fields
The datatype of values
The nesting structure
The number of child items
… and more.
The combination of such rules is called a JSON Schema. It is a formalized, worldwide defactor-standard to describe such rules. It is similar to XML Schema, DTD or Database Schemas.
See here for details about the official JSON schema specification: https://json-schema.org/
For example, let's define a simple JSON document that contains person data:
{
"firstName": "Sam",
"lastName": "Meyer",
"age": 48,
"gender": "male"
}And now let's define a JSON Schema in order to formalize the rules for this person JSON document:
{
"type": "object",
"properties": {
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
},
"age": {
"type": "number"
},
"gender": {
"type": "string",
"enum": ["male", "female", "neutral"]
}
}
}You can see, the JSON Schema defines four fields of different types: The firstName, lastName, age and gender of a person. So whenever a person JSON document is validated using this JSON Schema now, it must comply with exactly these rules. For example: In case such a person JSON document contains the attribute value age as string instead of a number, JSON Schema validation will fail.
Usage inside PIPEFORCE
In PIPEFORCE, a JSON Schema can be used mainly for these purposes:
To define the widgets of a form in a Form Schema → Any Form Schema is a valid JSON Schema.
To define the schema for list columns in a List Schema → Any List Schema is a valid JSON Schema.
To define the schema of custom JSON documents and validate them whenever required using the command
json.validate.
In order to get a full documentation of the JSON Schema specification, you should go to the official website at: https://json-schema.org.
Form Schema
A Form Schema is a JSON Schema which defines the validation, type and structure rules of widgets inside a PIPEFORCE Form. For more details see: Form Schema & Widgets (Model).
List Schema
A List Schema is a JSON Schema which defines the columns of a table (list) of a PIPEFORCE List. For more details see: Lists.
Define and validate a JSON object
You can also use a JSON Schema in order to specify the structure of a given JSON document (object). PIPEFORCE provides built-in toolings for storage, resolving and validation using JSON Schemas.
For more details see: Validating Properties.
Schema attribute type
The type attribute inside a JSON schema defines the required data type of a JSON attribute. Possible values are:
Using these types you can specify the required data type of a field value inside a JSON document. For details, see the official documentation of these types: https://json-schema.org/understanding-json-schema/reference/type.html
Example:
{
"type": "object",
"properties": {
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
},
"age": {
"type": "number"
},
"gender": {
"type": "string",
"enum": ["male", "female", "neutral"]
}
}
}Schema attribute format
The format attribute can be used for more precise semantic specification of string types. For example you can define whether a string must be a valid email address or URL for example.
Here is an example which uses the format attribute in order to define an email field:
{
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email"
}
}
}There are several built-in formats available in the JSON Schema specification. Some example:
date-time,time,date,durationemailhostnameipv4,ipv6uuiduri
For a full list of built-in format types, see: https://json-schema.org/understanding-json-schema/reference/string.html#format
Schema Validation Rules
Below you can find some common validation rules in JSON Schema.
Length
{
"type": "string",
"minLength": 2,
"maxLength": 3
}
Valid: hi
Regular expression
{
"type": "string",
"pattern": "^(\\([0-9]{3}\\))?[0-9]{3}-[0-9]{4}$"
}
Valid: 555-1212
Date and Time
{
"type": "string",
"format": "date-time"
}
Valid: 2018-11-13T20:20:39+00:00
Time
{
"type": "string",
"format": "time"
}
Valid: 20:20:39+00:00
Date
{
"type": "string",
"format": "date"
}
Valid: 2018-11-13
Email
{
"type": "string",
"format": "email"
}
Valid: my@email.de
Hostname
{
"type": "string",
"format": "hostname"
}
Valid: google.com
Uri
{
"type": "string",
"format": "uri"
}
Valid: https://google.com
Required fields
{
"type": "object",
"properties": {
"name": { "type": "string" },
"email": { "type": "string" },
"address": { "type": "string" },
"telephone": { "type": "string" }
},
"required": ["name", "email"]
}