Specification


Table of Contents


Introduction

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.


Root

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.


Import

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"
}

Types

At TypeSchema every type can be determined based on the used keywords. The following list describes every type and how to use them.


Struct

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 the Appendix.


Map

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 the Appendix.


Array

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 the Appendix.


Boolean

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 the Appendix.


Number

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 the Appendix.


String

Represents a string type. A string type must have a type keyword and the type must be number or integer.

{
    "type": "string"
}

All allowed properties are described at the Appendix.


Intersection

Represents an intersection type. An intersection type must have an allOf keyword.

{
    "allOf": [{ ... }, { ... }]
}

All allowed properties are described at the Appendix.


Union

Represents a union type. A union type must have an oneOf keyword.

{
    "oneOf": [{ ... }, { ... }]
}

All allowed properties are described at the Appendix.


Reference

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 the Appendix.


Generic

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 the Appendix.

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"
    }
}

Structure

The following image shows how the types can be nested.

TypeSchema structure

Generator

This chapter provides some guidelines for generators how to process a TypeSchema.


Appendix

The single source of truth of TypeSchema is the TypeSchema meta schema which describes itself. You can find the current TypeSchema at our repository. The following section contains a HTML representation which we automatically generate from this meta schema.

CommonType

Represents a base type. Every type extends from this common type and shares the defined properties
{
  "description": String,
  "type": String,
  "nullable": Boolean,
  "deprecated": Boolean,
  "readonly": Boolean,
}
FieldDescription
descriptionString
General description of this type, should not contain any new lines.
typeString
Type of the property
Enum
  • "object"
  • "array"
  • "boolean"
  • "integer"
  • "number"
  • "string"
  • "any"
nullableBoolean
Indicates whether it is possible to use a null value
deprecatedBoolean
Indicates whether this type is deprecated
readonlyBoolean
Indicates whether this type is readonly

StructType extends CommonType

Represents a struct type. A struct type contains a fix set of defined properties
{
  "$final": Boolean,
  "$extends": String,
  "type": String,
  "properties": Properties,
  "required": Array (String),
}
FieldDescription
$finalBoolean
Indicates that a struct is final, this means it is not possible to extend this struct
$extendsString
Extends an existing type with the referenced type
typeString
Enum
  • "object"
propertiesProperties
requiredArray (String)

Properties

Properties of a struct
Map (BooleanType | NumberType | StringType | ArrayType | UnionType | IntersectionType | ReferenceType | GenericType)

MapType extends CommonType

Represents a map type. A map type contains variable key value entries of a specific type
{
  "type": String,
  "additionalProperties": BooleanType | NumberType | StringType | ArrayType | UnionType | IntersectionType | ReferenceType | GenericType,
  "maxProperties": Integer,
  "minProperties": Integer,
}
FieldDescription
typeString
Enum
  • "object"
additionalPropertiesBooleanType | NumberType | StringType | ArrayType | UnionType | IntersectionType | ReferenceType | GenericType
maxPropertiesInteger
Positive integer value
minPropertiesInteger
Positive integer value

ArrayType extends CommonType

Represents an array type. An array type contains an ordered list of a specific type
{
  "type": String,
  "items": BooleanType | NumberType | StringType | ReferenceType | GenericType,
  "maxItems": Integer,
  "minItems": Integer,
}
FieldDescription
typeString
Enum
  • "array"
itemsBooleanType | NumberType | StringType | ReferenceType | GenericType
maxItemsInteger
Positive integer value
minItemsInteger
Positive integer value

ScalarType extends CommonType

Represents a scalar type
{
  "format": String,
  "enum": Array (String | Number),
  "default": String | Number | Boolean,
}
FieldDescription
formatString
Describes the specific format of this type i.e. date-time or int64
enumArray (String | Number)
defaultString | Number | Boolean

BooleanType extends ScalarType

Represents a boolean type
{
  "type": String,
}
FieldDescription
typeString
Enum
  • "boolean"

NumberType extends ScalarType

Represents a number type (contains also integer)
{
  "type": String,
  "multipleOf": Number,
  "maximum": Number,
  "exclusiveMaximum": Boolean,
  "minimum": Number,
  "exclusiveMinimum": Boolean,
}
FieldDescription
typeString
Enum
  • "number"
  • "integer"
multipleOfNumber
maximumNumber
exclusiveMaximumBoolean
minimumNumber
exclusiveMinimumBoolean

StringType extends ScalarType

Represents a string type
{
  "type": String,
  "maxLength": Integer,
  "minLength": Integer,
  "pattern": String,
}
FieldDescription
typeString
Enum
  • "string"
maxLengthInteger
Positive integer value
minLengthInteger
Positive integer value
patternString

IntersectionType

Represents an intersection type
{
  "description": String,
  "allOf": Array (ReferenceType),
}
FieldDescription
descriptionString
allOfArray (ReferenceType)
Contains an array of references. The reference must only point to a struct type

UnionType

Represents an union type. An union type can contain one of the provided types
{
  "description": String,
  "discriminator": Discriminator,
  "oneOf": Array (NumberType | StringType | BooleanType | ReferenceType),
}
FieldDescription
descriptionString
discriminatorDiscriminator
oneOfArray (NumberType | StringType | BooleanType | ReferenceType)
Contains an array of references. The reference must only point to a struct type

DiscriminatorMapping

An object to hold mappings between payload values and schema names or references
Map (String)

Discriminator

Adds support for polymorphism. The discriminator is an object name that is used to differentiate between other schemas which may satisfy the payload description
{
  "propertyName": String,
  "mapping": DiscriminatorMapping,
}
FieldDescription
propertyNameString
The name of the property in the payload that will hold the discriminator value
mappingDiscriminatorMapping

ReferenceType

Represents a reference type. A reference type points to a specific type at the definitions map
{
  "$ref": String,
  "$template": TemplateProperties,
}
FieldDescription
$refString
Reference to a type under the definitions map
$templateTemplateProperties
Optional concrete type definitions which replace generic template types

TemplateProperties

Map (String)

GenericType

Represents a generic type. A generic type can be used i.e. at a map or array which then can be replaced on reference via the $template keyword
{
  "$generic": String,
}
FieldDescription
$genericString

Definitions

The definitions map which contains all types
Map (StructType | MapType | ReferenceType)

Import

Contains external definitions which are imported. The imported schemas can be used via the namespace i.e. 'my_namespace:my_type'
Map (String)

TypeSchema

The root TypeSchema
{
  "$import": Import,
  "definitions": Definitions,
  "$ref": String,
}
FieldDescription
$importImport
definitionsDefinitions
$refString
Reference to a root schema under the definitions key