Generated code

This page explains the code that generate_module writes, using the BeerJSON types as an example. Knowing it is not needed to use the generated types, but helps to read the generated files, which contain calls to a few internal functions: _jsfrom, _jscheck, _jsto, and the metadata in _SPECS.

A generated struct

The schema of a volume, in measureable_units.json, is

"VolumeType": {
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "unit": { "$ref": "#/definitions/VolumeUnitType" },
    "value": { "type": "number" }
  },
  "required": ["unit", "value"]
}

and this is the code generated for it:

show_definition("measureable_units.jl", "VolumeType")
"""
    VolumeType(; kwargs...)
    VolumeType{I, T}(; kwargs...)

Integers are stored as `I <: Integer` and other numbers as `T <: Real`; by default, `Int64`
and `Float64`.

# Fields

- `unit::VolumeUnitType` (required)
- `value::T` (required)
"""
struct VolumeType{I <: Integer, T <: Real} <: AbstractSchemaObject
    unit::VolumeUnitType
    value::T
    function VolumeType{I, T}(; unit, value) where {I <: Integer, T <: Real}
        unit = _jsfrom(VolumeUnitType, unit)
        value = _jsfrom(T, value)
        _jscheck(VolumeType{I, T}, (unit, value), nothing)
        return new(unit, value)
    end
end
VolumeType(; kwargs...) = VolumeType{Int64, Float64}(; kwargs...)
VolumeType{I, T}(unit, value) where {I <: Integer, T <: Real} = VolumeType{I, T}(; unit, value)
VolumeType(unit, value) = VolumeType{_jsnumbertypes(unit, value)...}(; unit, value)
const _SPEC_VolumeType = (
    fields = (
        (name = :unit, key = "unit", required = true, nullable = false, constraints = nothing),
        (name = :value, key = "value", required = true, nullable = false, constraints = nothing),
    ),
    additionalProperties = false,
    extra = nothing,
    minProperties = nothing,
    maxProperties = nothing,
    schema = nothing,
)
_specs(::Type{<:VolumeType}) = _SPEC_VolumeType
_SPECS[VolumeType] = _SPEC_VolumeType

It has four parts:

  1. A docstring, from the descriptions in the schema, listing the fields with their types and whether they are required.
  2. The struct, a subtype of AbstractSchemaObject, with one field per property. Optional properties have the type Union{Nothing, T}.
  3. An inner keyword constructor, the only way to create a value of the type. Each argument is passed through _jsfrom with the type of its field, which converts and validates it. Then _jscheck checks the constraints of the schema on the converted values, and new creates the value. Optional arguments default to nothing.
  4. The metadata _SPEC_VolumeType: the JSON name of each field (which may differ from the Julia name, e.g. for first-name or end), whether it is required, its constraints, and more, used for reading, writing and checking. It is a constant, returned by _specs(VolumeType), so that the checks are type stable and compiled for each type (and also registered in the dictionary _SPECS, by type).

_jsfrom: from JSON to Julia

_jsfrom(T, x) converts x into a value of type T, and throws a SchemaValidationError if it cannot. The name stands for "from JSON". x can be a parsed JSON value, or a plain Julia one (a Dict or a named tuple for an object, a vector for an array, a string, a number...), or already a value of type T:

BeerJSONTypes._jsfrom(Float64, 20)
20.0
BeerJSONTypes._jsfrom(VolumeUnitType, "l")
VolumeUnitType("l")
BeerJSONTypes._jsfrom(VolumeType, Dict("unit" => "l", "value" => 20))
VolumeType(VolumeUnitType("l"), 20.0)
BeerJSONTypes._jsfrom(Union{VolumeType, MassType}, (unit = "kg", value = 2))
MassType(MassUnitType("kg"), 2.0)
try
    BeerJSONTypes._jsfrom(Int64, 2.5)
catch err
    showerror(stdout, err)
end
SchemaValidationError: expected an integer, got 2.5

The conversion is recursive. For a generated struct, _jsfrom calls its keyword constructor with the properties of the dict, whose arguments go through _jsfrom in turn, and so on. For a Union, which comes from oneOf, anyOf or an optional field, the options are tried in turn.

So constructing a value and reading a document are the same thing. VolumeType(unit = "l", value = 20) converts "l" with _jsfrom(VolumeUnitType, "l") and 20 with _jsfrom(Float64, 20). Reading a document is _jsfrom(RootType, JSON.parse(text)), which is what fromjson does. Either way, the result is valid.

_jscheck and _SPECS: the constraints

The types enforce much of the schema by themselves: the type of each property, the required ones, enums. The rest is checked by _jscheck, using the metadata in _SPECS: the constraints of each field (minimum, pattern, minItems...), and the keywords that cannot be expressed by types at all (not, if/then/else, the exclusivity of oneOf, format...). The generator embeds these as subschemas in _SPECS, written as JSON, and _jscheck validates the JSON form of the values against them with a small JSON Schema validator, _jsvalid. For instance, the amount of a hop addition is a volume or a mass, exactly one of them:

show_definition("hop.jl", "HopAdditionType")
"""
    HopAdditionType(; kwargs...)
    HopAdditionType{I, T}(; kwargs...)

HopAdditionType collects the attributes of each hop ingredient for use in a recipe hop bil.

Integers are stored as `I <: Integer` and other numbers as `T <: Real`; by default, `Int64`
and `Float64`.

# Fields

- `name::String` (required)
- `producer::Union{Nothing, String}`
- `product_id::Union{Nothing, String}`
- `origin::Union{Nothing, String}`
- `year::Union{Nothing, String}`
- `form::Union{Nothing, HopVarietyFormEnum}`
- `alpha_acid::PercentType{I, T}` (required)
- `beta_acid::Union{Nothing, PercentType{I, T}}`
- `timing::TimingType{I, T}` (required): The timing object fully describes the timing of an addition with options for basis on time, gravity, or pH at any process step.
- `amount::Union{VolumeType{I, T}, MassType{I, T}}` (required)
- `_extra::Dict{String, Any}`: additional properties, not described in the schema
"""
struct HopAdditionType{I <: Integer, T <: Real} <: AbstractSchemaObject
    name::String
    producer::Union{Nothing, String}
    product_id::Union{Nothing, String}
    origin::Union{Nothing, String}
    year::Union{Nothing, String}
    form::Union{Nothing, HopVarietyFormEnum}
    alpha_acid::PercentType{I, T}
    beta_acid::Union{Nothing, PercentType{I, T}}
    timing::TimingType{I, T}
    amount::Union{VolumeType{I, T}, MassType{I, T}}
    _extra::Dict{String, Any}
    function HopAdditionType{I, T}(; name, producer = nothing, product_id = nothing, origin = nothing, year = nothing, form = nothing, alpha_acid, beta_acid = nothing, timing, amount, _extra = Dict{String, Any}()) where {I <: Integer, T <: Real}
        name = _jsfrom(String, name)
        producer = _jsfrom(Union{Nothing, String}, producer)
        product_id = _jsfrom(Union{Nothing, String}, product_id)
        origin = _jsfrom(Union{Nothing, String}, origin)
        year = _jsfrom(Union{Nothing, String}, year)
        form = _jsfrom(Union{Nothing, HopVarietyFormEnum}, form)
        alpha_acid = _jsfrom(PercentType{I, T}, alpha_acid)
        beta_acid = _jsfrom(Union{Nothing, PercentType{I, T}}, beta_acid)
        timing = _jsfrom(TimingType{I, T}, timing)
        amount = _jsfrom(Union{VolumeType{I, T}, MassType{I, T}}, amount)
        _extra = _jsfrom(Dict{String, Any}, _extra)
        _jscheck(HopAdditionType{I, T}, (name, producer, product_id, origin, year, form, alpha_acid, beta_acid, timing, amount), _extra)
        return new(name, producer, product_id, origin, year, form, alpha_acid, beta_acid, timing, amount, _extra)
    end
end
HopAdditionType(; kwargs...) = HopAdditionType{Int64, Float64}(; kwargs...)
HopAdditionType{I, T}(name, producer, product_id, origin, year, form, alpha_acid, beta_acid, timing, amount, _extra) where {I <: Integer, T <: Real} = HopAdditionType{I, T}(; name, producer, product_id, origin, year, form, alpha_acid, beta_acid, timing, amount, _extra)
HopAdditionType(name, producer, product_id, origin, year, form, alpha_acid, beta_acid, timing, amount, _extra) = HopAdditionType{_jsnumbertypes(name, producer, product_id, origin, year, form, alpha_acid, beta_acid, timing, amount, _extra)...}(; name, producer, product_id, origin, year, form, alpha_acid, beta_acid, timing, amount, _extra)
const _SPEC_HopAdditionType = (
    fields = (
        (name = :name, key = "name", required = true, nullable = false, constraints = nothing),
        (name = :producer, key = "producer", required = false, nullable = false, constraints = nothing),
        (name = :product_id, key = "product_id", required = false, nullable = false, constraints = nothing),
        (name = :origin, key = "origin", required = false, nullable = false, constraints = nothing),
        (name = :year, key = "year", required = false, nullable = false, constraints = nothing),
        (name = :form, key = "form", required = false, nullable = false, constraints = nothing),
        (name = :alpha_acid, key = "alpha_acid", required = true, nullable = false, constraints = nothing),
        (name = :beta_acid, key = "beta_acid", required = false, nullable = false, constraints = nothing),
        (name = :timing, key = "timing", required = true, nullable = false, constraints = nothing),
        (name = :amount, key = "amount", required = true, nullable = false, constraints = (schema = JSON.parse("""
            {
              "oneOf": [
                {
                  "\$type": "VolumeType"
                },
                {
                  "\$type": "MassType"
                }
              ]
            }
            """),)),
    ),
    additionalProperties = true,
    extra = :_extra,
    minProperties = nothing,
    maxProperties = nothing,
    schema = nothing,
)
_specs(::Type{<:HopAdditionType}) = _SPEC_HopAdditionType
_SPECS[HopAdditionType] = _SPEC_HopAdditionType

The validator can be called directly, with a schema and a value as parsed JSON:

schema = Dict("type" => "string", "not" => Dict("enum" => ["password", "123456"]))
BeerJSONTypes._jsvalid(schema, "123456")
"must not match the schema in `not`"

_jsto: from Julia to JSON

_jsto(x) is the inverse of _jsfrom ("to JSON"). It converts a value into JSON-compatible values: structs become objects with the original JSON property names (leaving out optional fields that are nothing), enums become their values, vectors and tuples become arrays:

v = VolumeType(unit = "l", value = 20)
BeerJSONTypes._jsto(v)
JSON.Object{String, Any} with 2 entries:
  "unit"  => "l"
  "value" => 20

todict is _jsto, and tojson and writejson serialize its result with JSON.jl.

Enum types

An enum becomes a type wrapping the value, whose constructor checks it against the allowed values, recorded in _SPECS:

show_definition("measureable_units.jl", "VolumeUnitType")
"""
    VolumeUnitType(value)

Allowed values: `"ml"`, `"l"`, `"tsp"`, `"tbsp"`, `"floz"`, `"cup"`, `"pt"`, `"qt"`, `"gal"`, `"bbl"`, `"ifloz"`, `"ipt"`, `"iqt"`, `"igal"`, `"ibbl"`.
"""
struct VolumeUnitType <: AbstractSchemaEnum
    value::String
    VolumeUnitType(value) = new(_jscheckenum(VolumeUnitType, _jsfrom(String, value)))
end
const _VALUES_VolumeUnitType = ("ml", "l", "tsp", "tbsp", "floz", "cup", "pt", "qt", "gal", "bbl", "ifloz", "ipt", "iqt", "igal", "ibbl")
_enumvalues(::Type{VolumeUnitType}) = _VALUES_VolumeUnitType
_SPECS[VolumeUnitType] = (values = _VALUES_VolumeUnitType,)

The runtime code

All of these functions are defined in the generated module itself, in runtime.jl (or at the top of the file, for a single-file module), so a generated module does not depend on JSONSchema2Types.jl. The runtime code is the same for every generated module. Its functions are internal (their names start with _js), except for those listed in the API, which are exported.