API

JSONSchema2Types

JSONSchema2Types — Module
JSONSchema2Types

Generate Julia types from a JSON Schema, together with functions to read and write JSON documents conforming to the schema. See generate_module.

source
JSONSchema2Types.generate_module — Function
generate_module(schema_file, output; root_name, module_name, schemas, split, type_names,
                download, typed_formats, use_defaults, checks, validation) -> String

Read the JSON Schema in schema_file (and every schema file it references through $ref) and write to output_file a Julia module defining types for all the objects and enums in the schema, together with functions to read and write JSON documents with them:

  • readjson(T, filename) and fromjson(T, string) parse a JSON document into a value of type T (e.g. the root type), validating it against the schema;
  • writejson(filename, x) and tojson(x) write a value back to JSON;
  • fromdict(T, x) and todict(x) convert from/to parsed JSON values;
  • setfields(x; kwargs...) returns a copy of a value with some fields changed.

The generated module only depends on JSON.jl.

References ($ref) are resolved as URIs, against the base URI set by the enclosing $ids: JSON pointers, $ids, $anchors, and paths relative to the file containing them. Additional schema files that are only referenced by their $id (e.g. https://example.com/address.schema.json) can be given in schemas. Remote schemas are downloaded only with download = true (or download = url -> content).

With typed_formats = true, strings with the formats date, date-time and uuid are stored as Dates.Date, Dates.DateTime (in UTC) and UUIDs.UUID. With use_defaults = true, optional fields default to the default given in the schema, instead of nothing. Both are off by default, since documents are then written back in a different form (normalized dates, defaults filled in).

With checks = false, the module starts with the checks of the constraints of the schema turned off, for speed: values are only converted to the types of their fields, and checked by validate(x), and by tojson and writejson before writing. The checks can be turned on and off at any time with checks!(flag) and with_checks(f, flag).

With validation = :separate, the types are minimal: their constructors only convert the values to the types of their fields, without checking the constraints of the schema, and the code for checking them (the constraints of each type, and the validator) is written to a separate file, validation.jl (or <name>_validation.jl next to output, without split), which the module includes only if it is present. It provides validate(x), violations(x) and isvalid(x), and makes tojson and writejson validate before writing. With validation = :none, that file is not written. The default, validation = :inline, puts the checks in the constructors.

The name of the root type is root_name, which defaults to the title of the schema or else to the name of the schema file. The module name defaults to the root type name followed by Types.

By default the whole module is written to the file output. With split = true, output is a directory, and the module is split into several files in it, following the schema files: <module_name>.jl defines the module and includes runtime.jl (the code for reading, writing and validating) and one file per schema file, named after it, with the types defined in that schema file (inline subschemas go with the type containing them). Schema files whose types depend on each other in a cycle share a single file. Load the module by including <module_name>.jl.

Type names are derived from the schema (see the README). Any of them can be chosen with type_names, mapping the location of a subschema, as "file.json#/json/pointer" (or "#/json/pointer" in the root schema file), to the name of its type, e.g. Dict("recipe.json#/definitions/RecipeType/properties/type" => "RecipeKind").

Returns the path of the file defining the module.

source

Generated modules

Every generated module defines the types of the schema, RootType (the type of the root of the schema), and the following functions and types (with validation = :separate, validate, violations, isvalid and check_formats! only when its validation file is present, and checks! and with_checks not at all; with validation = :none, none of them). They are documented in the generated code, so in the REPL, ?readjson shows their documentation once the module is loaded.

NameDescription
readjson(T, filename)read the JSON file filename into a value of type T
fromjson(T, json)parse the JSON string json into a value of type T
writejson(filename, x; pretty = true, validate)write x as JSON to the file filename (validated first when the checks are off)
tojson(x; pretty = false, validate)convert x into a JSON string (validated first when the checks are off)
fromdict(T, x)convert a parsed JSON value into a value of type T
todict(x)convert x into a JSON-compatible value
setfields(x; kwargs...)a copy of the struct x with some fields changed, validated
check_formats!(flag)turn the validation of the format keyword off or on
checks!(flag)turn the checks of the constraints off or on; returns the previous setting
with_checks(f, flag)call f() with the checks of the constraints off or on
validate(x)check x and the values nested in it; throw a SchemaValidationError listing the problems
violations(x)the problems found in x and the values nested in it, with their locations
isvalid(x)whether x and the values nested in it conform to the schema
AbstractSchemaObjectsupertype of the generated structs
AbstractSchemaEnumsupertype of the generated enum types; the value is in the field value
SchemaValidationErrorerror thrown when a value does not conform to the schema