JSON Schema

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: https://logabit.atlassian.net/wiki/spaces/PA/pages/2546335745.

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: https://logabit.atlassian.net/wiki/spaces/PA/pages/2548433217.

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: .

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:

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:

There are several built-in formats available in the JSON Schema specification. Some example:

  • date-time, time, date, duration

  • email

  • hostname

  • ipv4, ipv6

  • uuid

  • uri

For a full list of built-in format types, see:

Schema Validation Rules

Below you can find some common validation rules in JSON Schema.

Length

Valid: hi

Regular expression

Valid: 555-1212

Date and Time

Valid: 2018-11-13T20:20:39+00:00

Time

Valid: 20:20:39+00:00

Date

Valid: 2018-11-13

Email

Valid: my@email.de

Hostname

Valid: google.com

Uri

Valid: https://google.com

Required fields