Guide
Generating a module
generate_module reads a schema, and every schema file it references with $ref, and writes a module:
generate_module(schema_file, output;
root_name = nothing, # name of the root type; defaults to the schema `title` or file name
module_name = nothing, # defaults to `root_name * "Types"`
split = false, # write a directory with one file per schema file
schemas = String[], # other schema files, referenced by their `$id`
type_names = Dict(), # names chosen for some types
download = false, # fetch remote schemas referenced by `$ref`
typed_formats = false, # store `date`, `date-time` and `uuid` strings as Julia types
use_defaults = false, # optional fields default to the schema `default`, not `nothing`
)The generated module only needs JSON.jl. It exports the generated types and:
| Function | Purpose |
|---|---|
readjson(T, filename), fromjson(T, string) | read a JSON document into a value of type T, validating it |
writejson(filename, x), tojson(x) | write a value as JSON |
setfields(x; kwargs...) | a copy of x with some fields changed, validated |
fromdict(T, x), todict(x) | convert from and to parsed JSON values (Dicts, vectors, numbers...) |
RootType | alias for the type of the root of the schema |
SchemaValidationError | error thrown when a value does not conform to the schema |
check_formats!(flag) | turn the validation of format off or on |
checks!(flag), with_checks(f, flag) | turn the checks of the constraints off or on |
validate(x), violations(x), isvalid(x) | check a value, and the values nested in it, later |
How a schema is translated
| JSON Schema | Julia |
|---|---|
object with properties | struct <: AbstractSchemaObject, with a keyword constructor |
allOf | a single struct with the merged properties; $refs are resolved |
enum, const | struct <: AbstractSchemaEnum wrapping the value, with a checking constructor |
oneOf, anyOf, "type": [...] | Union{...} |
array | Vector{T} |
prefixItems (or items as a list), all required | Tuple{A, B}, or Tuple{A, B, Vararg{T}} when more items are allowed |
object without properties | Dict{String, T} (T from additionalProperties, or Any) |
string, boolean, null | String, Bool, Nothing |
integer, number | the type parameters I <: Integer and T <: Real of the structs; Int64 and Float64 by default (see Numeric types) |
optional property, or null allowed | Union{Nothing, T}; optional fields default to nothing and are omitted when writing |
additionalProperties not false | unknown properties are kept in the _extra field, so nothing is lost when a document is read and written back |
additionalProperties: false, unevaluatedProperties: false | unknown properties are an error |
patternProperties | matching properties are kept (in _extra for a struct) and checked against their schemas |
format | the value stays a String; well-known formats are checked. With typed_formats = true, date, date-time and uuid become Dates.Date, Dates.DateTime and UUIDs.UUID |
deprecated: true | flagged in the docstrings |
The keyword constructors convert plain values, so VolumeType(unit = "l", value = 20) works as well as VolumeType(unit = VolumeUnitType("l"), value = 20.0), and nested objects can be given as Dicts or named tuples: HopAdditionType(..., amount = (unit = "g", value = 50)). Reading a document goes through the same constructors, so a value read from a file is always valid.
Types are written in dependency order. When a schema is recursive, the fields that close a cycle are declared as Any, but they are still converted and checked by the constructor.
Validation
Most of a schema is enforced by the types themselves: the type of each field, required properties, enums, and the constraints minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf, minLength, maxLength, pattern, minItems, maxItems, uniqueItems, minProperties and maxProperties.
The keywords that cannot be expressed by Julia types are checked at runtime. The generator embeds the corresponding subschemas in the generated code, and a small JSON Schema validator checks the JSON form of the values against them:
not,if/then/else,dependentRequired,dependentSchemas,dependencies,propertyNames,contains,prefixItemsandpatternProperties;oneOfandanyOf: reading picks the first option of theUnionwhose type fits, and the runtime check makes sure that the value satisfies the full schema of an option and, foroneOf, that it matches exactly one option;format:date-time,date,time,duration,email,idn-email,hostname,idn-hostname,ipv4,ipv6,uri,uri-reference,iri,iri-reference,uri-template,json-pointer,relative-json-pointer,uuidandregexare checked (idn-hostnameloosely: the IDNA2008 rules are not), and other formats are ignored. JSON Schema treatsformatas an annotation by default, so these checks can be turned off withcheck_formats!(false).
A value that does not conform throws a SchemaValidationError that says where and why.
Turning the checks off
For speed, the checks of the constraints can be turned off with checks!(false), or only for some code with with_checks(false) do ... end, or from the start, by generating the module with checks = false. Values are then only converted to the types of their fields. These still enforce the structure of the schema: the types of the properties, required properties, the properties allowed and the enumeration types. But the constraints (minimum, pattern, the values of enumerations, minItems, oneOf...) are not checked. A JSON value read into a union of generated types (from oneOf or anyOf) is still checked, to choose its type.
The values can be checked later, e.g. after processing them, before saving them:
violations(x)returns the problems found inxand in every value nested in it (the first problem of each value), with their locations, e.g."recipes[1].batch_size.unit: invalid value \"litre\" for ...";validate(x)throws aSchemaValidationErrorlisting them, if any, and returnsx;isvalid(x)says whether there are none.
With the checks off, tojson and writejson call validate before writing, unless they are given validate = false.
checks!(false)
recipe2 = setfields(recipe; batch_size = (unit = "litre", value = 20)) # not checked
isvalid(recipe2) # false
writejson("recipe.json", recipe2) # SchemaValidationError: 1 value does not conform ...
checks!(true)In the BeerJSON example, reading the Punk IPA sample takes about 25% less time with the checks off, building a VolumeType about 3 times less, and setfields on a hop addition (whose amount is oneOf a volume or a mass) about 7 times less. Validating the whole document takes about a quarter of the time it takes to read it.
Minimal types, with the validation in a separate file
With validation = :separate, the generated types are minimal: the same structs, with the same constructors, which convert the values to the types of their fields but do not check the constraints of the schema. Everything needed to check them (the constraints of each type, the subschemas checked at runtime and the validator) goes in a separate file, validation.jl (or <name>_validation.jl next to the module file, without split), which the module includes only if it is present:
isfile(joinpath(@__DIR__, "validation.jl")) && include("validation.jl")Without that file, the module only reads and writes. With it, it also has validate(x), violations(x) and isvalid(x), and tojson and writejson validate before writing (unless given validate = false). Reading is not checked: use validate(readjson(T, file)) for that. With validation = :none, the validation file is not written at all.
The types still enforce the structure of the schema: the types of the properties, required properties, the properties allowed and the enumeration types. A JSON value read into a union of generated types (from oneOf or anyOf) gets the first option that fits by its properties and the values of its enumerations (e.g. a unit that is "l" for a volume, "kg" for a mass); options that only differ by other constraints cannot be told apart.
For BeerJSON, the minimal module is 221 KiB of code, instead of 280 KiB, and the validation file 90 KiB.
Type names
Type names come from the definition names: #/definitions/VolumeType (or #/$defs/VolumeType) becomes VolumeType. Inline subschemas are named after their title, if they have one. Otherwise the name is built from the parent type, without a trailing Type or Base, and the property name:
- inline enums get an
Enumsuffix: thetypeofRecipeTypeisRecipeTypeEnum, theformofHopVarietyBaseisHopVarietyFormEnum; - a property with the same name as its parent gets
Content:beerjsoninBeerJSONisBeerJSONContent; - options of
oneOf/anyOfgetOption1,Option2..., array items getItem.
Any type can be given another name with type_names, which maps the location of its subschema, "file.json#/json/pointer" (or "#/json/pointer" in the root schema file), to a name:
generate_module("beer.json", "BeerJSONTypes"; root_name = "BeerJSON",
type_names = Dict("recipe.json#/definitions/RecipeType/properties/type" => "RecipeKind"))Property names that are not valid Julia identifiers, or are Julia keywords, are changed (first-name becomes first_name, end becomes end_). The fields keep their original JSON names for reading and writing.
Splitting into several files
For a schema spread over several files, split = true writes a directory with one Julia file per schema file:
BeerJSONTypes/
BeerJSONTypes.jl # the module: exports and includes, in dependency order
runtime.jl # reading, writing and validation
measureable_units.jl # types from measureable_units.json
hop.jl, recipe.jl, ...
beer.jl # the root type, from beer.jsonAll the files belong to the same module, which is loaded by including the main file. Each type is in the file of the schema file that defines it, and inline subschemas go with the type containing them. Schema files whose types depend on each other in a cycle share a single file.
Tuples
An array described by prefixItems (or, before 2020-12, by items as a list) is a tuple when all its prefix items are required (minItems at least their number), since a Julia tuple cannot have optional elements:
| Schema | Julia |
|---|---|
"prefixItems": [{"type": "number"}, {"type": "number"}], "items": false, "minItems": 2 | Tuple{Float64, Float64} |
"prefixItems": [{"type": "string"}], "items": {"type": "integer"}, "minItems": 1 | Tuple{String, Vararg{Int64}} |
"prefixItems": [{"type": "string"}], "minItems": 1 | Tuple{String, Vararg{Any}} |
"prefixItems": [{"type": "string"}, {"type": "integer"}] (no minItems) | Vector{Any}, with the items checked at runtime |
Tuples are written as JSON arrays.
Numeric types
JSON Schema has two numeric types, integer and number, with no limit on their size or precision. The generated structs leave the choice of the Julia types to their users: each struct has two type parameters, I <: Integer for the integers and T <: Real for the other numbers (VolumeType{I, T}), and passes them on to the structs it contains. Without them, the defaults are Int64 and Float64:
VolumeType(unit = "l", value = 20) # VolumeType{Int64, Float64}
VolumeType{Int, BigFloat}(unit = "l", value = 20) # values as BigFloat
readjson(BeerJSON{BigInt, BigFloat}, "recipe.json") # all the numbers in the document
VolumeType{Int, Rational{Int}}(unit = "l", value = 0.5).value # 1//2Properties and definitions can be named I or T, like the type parameters: a struct named T, or with a field whose type is named T, simply uses other names for its type parameters (I1 and T1), and so do the constructors of a struct with a field named I or T. This changes nothing for the users of the types.
Any Integer and Real types can be used: Int32, Int128, BigInt; Float32, BigFloat, rationals, or types from other packages that convert from numbers. Values that cannot be represented in the chosen type (e.g. an integer too large for Int64) are rejected with a SchemaValidationError.
When reading a document with a floating-point type other than Float64, its numbers are parsed with full precision (as BigFloat at the current precision, see setprecision), not through Float64. Writing a document writes the numbers as they are stored: note that a decimal number such as 1.1 has no exact binary representation, so a BigFloat writes all the digits of its precision.
RootType is the root type with the default numeric types. Printed values show the numeric types only when they are not the default ones, e.g. VolumeType{Int64, BigFloat}(VolumeUnitType("l"), 20.0).
Changing values
The generated structs are immutable. setfields(x; field = value, ...) returns a copy of x with some fields replaced; the new values are converted and validated as by the constructor, so plain values can be given:
v = VolumeType(unit = "l", value = 20)
setfields(v; value = 40) # VolumeType(VolumeUnitType("l"), 40.0)
setfields(v; unit = "litre") # SchemaValidationErrorEach struct also has a positional constructor, with its fields in order, so values can be written as they are printed (VolumeType(VolumeUnitType("l"), 20.0)). This is also what Accessors.jl uses, so its @set works on the generated types, for changes deep inside a document, without further setup:
using Accessors
recipe2 = @set recipe.ingredients.hop_additions[1].amount.value = 0.05Default values
By default, an optional property that is missing is nothing. With use_defaults = true, optional properties with a default in the schema (or in the schema their \$ref points to) default to it instead, both in the keyword constructors and when reading a document. Since the default values are then written out, a document missing them is not written back unchanged: that is why this is not the default.
Dates and UUIDs
With typed_formats = true, strings with these formats are stored as Julia values:
format | Julia | Written back as |
|---|---|---|
date | Dates.Date | 2026-11-15 |
date-time | Dates.DateTime, in UTC, with millisecond precision | 2026-11-15T08:30:00.250Z |
uuid | UUIDs.UUID | lowercase |
A date-time with a UTC offset, such as 2026-11-15T10:30:00+02:00, is converted to UTC, so it is written back as the same instant in a different notation. Likewise, a UUID in uppercase is written back in lowercase. That is why this is not the default. time stays a String, since Dates.Time has no UTC offset. The generated module then imports the Dates and UUIDs standard libraries, which must be available where it is loaded (in a package, add them to its dependencies).
References
$refs are resolved as URIs, against the base URI at their location, which is set by the $id of the enclosing (sub)schemas, as JSON Schema specifies. They can point to:
- a location in the same or another file, by a JSON pointer (
#/$defs/Address, orcommon.json#/definitions/Address), withdefinitionsor$defs; - a schema or subschema by its
$id, including nested$ids (embedded resources), within which#/...pointers are relative to that resource; - a subschema with an
$anchor(#name), or an"$id": "#name"in earlier drafts; - a file, by a path relative to the file containing the reference. This also works for local copies of schemas whose
$ids are remote URLs, as BeerJSON's are.
Schema files that are only referenced by their $id URL can be given in schemas. Remote schemas are not downloaded unless download = true, which fetches them with Downloads.jl. download can also be a function, called with the URL and returning the content of the schema, e.g. to use a cache.
Limitations
See also Conformance for the results of the official JSON Schema Test Suite.
- A schema with
propertiesbut notypeis a struct, so it only accepts objects. $dynamicRef/$dynamicAnchorare resolved statically, like$ref/$anchor;$recursiveRef(2019-09) is not supported.- Arrays with optional prefix items are
Vector{Any}, with their items checked at runtime. timestrings are not converted to Julia values, even withtyped_formats = true.- Integers are
Int64and numbersFloat64.