This document describes the TypeSchema specification. TypeSchema is a JSON format to model data structures. It abstracts OOP concepts into a simple and deterministic JSON format which can be turned into code for many different target languages. The main use case of TypeSchema is to describe a data model, it is not designed to validate JSON structures. A data model described in TypeSchema can be used as single source of truth which can be reused in many different environments.
Every TypeSchema has a Root definition. The Root must contain at least the
definitions
keyword i.e.:
{ "definitions": { "TypeA": { ... }, "TypeB": { ... } } }
The definitions
keyword contains simply a map containing Struct,
Map and Reference types.
Optional it is possible to include a $ref
keyword which points to the default type.
Optional it is possible to import other documents through the $import
keyword. It contains a map
where the key is the namespace and the value points to a remote document. The value is a URN and the supported
schemes i.e. file
, http
, https
etc. are out of bound of this specification.
{
"$import": {
"MyNamespace": "file:///my_schema.json"
}
}
Inside a reference it is then possible to reuse all types under the namespace which are defined at the remote document i.e.:
{
"$ref": "MyNamespace:MyType"
}
At TypeSchema every type can be determined based on the used keywords. The following list describes every type and how to use them.
Represents a struct type. A struct type contains a fix set of defined properties. A struct type must have a
type
and properties
keyword. The type must be object
.
{
"type": "object",
"properties": {
"PropertyA": { ... },
"PropertyB": { ... }
}
}
All allowed properties are described at TypeHub.
Represents a map type. A map type contains variable key value entries of a specific type. A map type must have a
type
and additionalProperties
keyword. The type must be object
.
{
"type": "object",
"additionalProperties": { ... }
}
All allowed properties are described at TypeHub.
Represents an array type. An array type contains an ordered list of a specific type. An array type must have a
type
and items
keyword. The type must be array
.
{
"type": "array",
"items": { ... }
}
All allowed properties are described at TypeHub.
Represents a boolean type. A boolean type must have a type
keyword and the type must be
boolean
.
{
"type": "boolean"
}
All allowed properties are described at TypeHub.
Represents a number type (contains also integer). A number type must have a type
keyword and the type
must be number
or integer
.
{
"type": "number"
}
All allowed properties are described at TypeHub.
Represents a string type. A string type must have a type
keyword and the type must
be string
.
{
"type": "string"
}
All allowed properties are described at TypeHub.
Represents an intersection type. An intersection type must have an allOf
keyword.
{
"allOf": [{ ... }, { ... }]
}
All allowed properties are described at TypeHub.
Represents a union type. A union type must have an oneOf
keyword.
{
"oneOf": [{ ... }, { ... }]
}
All allowed properties are described at TypeHub.
Represents a reference type. A reference type points to a specific type at the definitions map. A reference type
must have a $ref
keyword.
{
"$ref": "MyType"
}
All allowed properties are described at TypeHub.
Represents a generic type. A generic type represents a type which can be replaced if you reference a specific type.
A generic type must have a $generic
keyword.
{
"$generic": "T"
}
All allowed properties are described at TypeHub.
I.e. if we reference a specific type and this type contains a generic type then we can define which type should be inserted at the generic type.
{
"$ref": "MyType",
"$template": {
"T": "AnotherType"
}
}
The following image shows how the types can be nested.