Developer

This chapter provides some guidelines for developers how to build a TypeSchema code generator.

• TypeSchema is designed so that a processor can create an in-memory object representation of a schema. Every schema can be exactly assigned to a specific type. A processor should create a fitting class for each type and a factory which creates the fitting type depending on the used keywords.
• There is one key where all reusable types are located. For plain TypeSchema documents this is /definitions for OpenAPI, AsyncAPI and OpenRPC documents it is /components/schemas. A processor should have an option to set the location of the definitions location. There is also no need for a JSON Pointer implementation since we only resolve local schemas.
• There are no nested objects instead every object must be defined under the definitions location. Object types can then reference these types. This is required since a processor needs a unique name for each object type, which is the definition key of the type (i.e. which is used as class name).
• To parse a TypeSchema we transform at the first step only the JSON into fitting objects representing the types. It is important that we _do not_ resolve references at the parsing step. This step is always executed when processing a schema.

---

Overview

The following TypeSchema shows most keywords with a concrete reference to the specification, which should give you a first overview of the available keywords.

{
  "$import": {
    "my_ns": "file:///generic.json"
  },
  "definitions": {
    "Human": {
      "type": "struct",
      "properties": {
        "firstName": {
          "type": "string"
        },
        "lastName": {
          "type": "string"
        },
        "age": {
          "type": "integer"
        }
      }
    },
    "Student": {
      "parent": "Human",
      "type": "struct",
      "properties": {
        "matricleNumber": {
          "type": "integer"
        }
      }
    },
    "StudentMap": {
      "$ref": "Map",
      "$template": {
        "T": "Student"
      }
    },
    "Map": {
      "type": "struct",
      "properties": {
        "totalResults": {
          "type": "integer"
        },
        "entries": {
          "type": "array",
          "items": {
            "$generic": "T"
          }
        }
      }
    }
  },
  "$ref": "StudentMap"
}

---

Parse type

The following algorithm shows how to create an object in-memory representation of a type. It assumes that you pass the raw JSON decoded object into this function and it returns a concrete type.

function parseType(object json): Type

• Type type = newType(json)
• If type is an instance of StructType
  • Map<string, Type> properties = Create a new empty map
  • For each key : property in json.properties
    • properties[key] = parseType(property)
  • Set properties to type
  • Parse the remaining struct type properties from json and set them to type
  • return type
• Else If type is an instance of MapType
  • Type additionalProperties = parseType(json.additionalProperties)
  • Set additionalProperties to type
  • Parse the remaining map type properties from json and set them to the type
  • return type
• Else If type is an instance of ArrayType
  • Type items = parseType(json.items)
  • Set items to type
  • Parse the remaining array type properties from json and set them to type
  • return type
• Else If type is an instance of BooleanType
  • return type
• Else If type is an instance of NumberType
  • Parse the number type properties from json and set them to type
  • return type
• Else If type is an instance of StringType
  • Parse the string type properties from json and set them to type
  • return type
• Else If type is an instance of AnyType
  • return type
• Else If type is an instance of GenericType
  • return type
• Else If type is an instance of UnionType
  • Array<Type> items = Create an empty array
  • For each property in json.oneOf
    • items[] = parseType(property)
  • Set items to type
  • Parse the remaining union type properties from json and set them to type
  • return type
• Else If type is an instance of IntersectionType
  • Array<Type> items = Create an empty array
  • For each property in json.oneOf
    • items[] = parseType(property)
  • Set items to type
  • Parse the remaining intersection type properties from json and set them to type
  • return type
• Else If type is an instance of ReferenceType
  • Parse the reference type properties from json and set them to type
  • return type
• Else
  • Throw an exception that we could not resolve the type

---

Type detection

The following algorithm shows how to detect the correct type from a decoded JSON value.

function newType(object json): Type|null

• If json.type is available
  • If json.type is equal to object
    • If json.properties is available
      • return new StructType
    • Else If json.additionalProperties is available
      • return new MapType
  • Else If json.type is equal to array
    • return new ArrayType
  • Else If json.type is equal to boolean
    • return new BooleanType
  • Else If json.type is equal to number
    • return new NumberType
  • Else If json.type is equal to string
    • return new StringType
  • Else If json.type is equal to any
    • return new AnyType
• Else If json.allOf is available
  • return new IntersectionType
• Else If json.oneOf is available
  • return new UnionType
• Else If json.$ref is available
  • return new ReferenceType
• Else If json.$generic is available
  • return new GenericType
• return null

---

Reference resolution

The following algorithm shows how to resolve a reference.

function resolveReference(ReferenceType type, Definitions definitions): Type

• string ref = type.ref
• Replace the string #/definitions/ and #/components/schemas/ on ref with an empty string
• If the ref contains not a colon :
  • If the ref is available under the definitions
    • return definitions[ref]
  • Else
    • Throw an exception that we could not resolve the type
• Else
  • Split up the ref string based on the colon : into two parts
  • string namespace = parts[0]
  • string name = parts[1]
  • If the namespace is available under the $import keyword
    • Lookup the imported schema
    • If the resolved schema contains a type with the provided name
      • Return the type of the remote schema
    • Else
      • Throw an exception that the remote schema does not contain the referenced type
  • Else
    • Throw an exception that we could not resolve the namespace