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_VolumeTypeIt has four parts:
- A docstring, from the descriptions in the schema, listing the fields with their types and whether they are required.
- The struct, a subtype of
AbstractSchemaObject, with one field per property. Optional properties have the typeUnion{Nothing, T}. - An inner keyword constructor, the only way to create a value of the type. Each argument is passed through
_jsfromwith the type of its field, which converts and validates it. Then_jscheckchecks the constraints of the schema on the converted values, andnewcreates the value. Optional arguments default tonothing. - The metadata
_SPEC_VolumeType: the JSON name of each field (which may differ from the Julia name, e.g. forfirst-nameorend), 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.0BeerJSONTypes._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)
endSchemaValidationError: expected an integer, got 2.5The 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_HopAdditionTypeThe 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" => 20todict 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.