Specification

Table of Contents

• Introduction
• Root
  • Import
• Types
  • Struct
  • Map
  • Array
  • Boolean
  • Number
  • String
  • Intersection
  • Union
  • Reference
  • Generic
• Structure
• Generator
• Appendix

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.

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.

{
  "type": String,
}

{
  "type": String,
  "items": BooleanType | NumberType | StringType | ReferenceType | GenericType | AnyType,
  "maxItems": Integer,
  "minItems": Integer,
}

{
  "type": String,
}

{
  "description": String,
  "type": String,
  "nullable": Boolean,
  "deprecated": Boolean,
  "readonly": Boolean,
}

Map (StructType | MapType | ReferenceType)

{
  "propertyName": String,
  "mapping": DiscriminatorMapping,
}

Map (String)

{
  "$generic": String,
}

Map (String)

{
  "description": String,
  "allOf": Array (ReferenceType),
}

{
  "type": String,
  "additionalProperties": BooleanType | NumberType | StringType | ArrayType | UnionType | IntersectionType | ReferenceType | GenericType | AnyType,
  "maxProperties": Integer,
  "minProperties": Integer,
}

{
  "type": String,
  "multipleOf": Number,
  "maximum": Number,
  "exclusiveMaximum": Boolean,
  "minimum": Number,
  "exclusiveMinimum": Boolean,
}

Map (BooleanType | NumberType | StringType | ArrayType | UnionType | IntersectionType | ReferenceType | GenericType | AnyType)

{
  "$ref": String,
  "$template": TemplateProperties,
}

{
  "format": String,
  "enum": Array (String | Number),
  "default": String | Number | Boolean,
}

{
  "type": String,
  "maxLength": Integer,
  "minLength": Integer,
  "pattern": String,
}

{
  "$final": Boolean,
  "$extends": String,
  "type": String,
  "properties": Properties,
  "required": Array (String),
}

Map (String)

{
  "$import": Import,
  "definitions": Definitions,
  "$ref": String,
}

{
  "description": String,
  "discriminator": Discriminator,
  "oneOf": Array (NumberType | StringType | BooleanType | ReferenceType),
}