Specification

---

Table of Contents

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

---

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

---

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

---

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

---

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

---

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

---

String

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.

---

Intersection

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

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

All allowed properties are described at TypeHub.

---

Union

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

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

All allowed properties are described at TypeHub.

---

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

---

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

---

Structure

The following image shows how the types can be nested.

---