Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,10 @@ The generated module exports:
`nothing`. Defaults to `false`, since the defaults are then written out.
* `checks`: whether the checks of the constraints are on when the module is loaded.
Defaults to `true` (see [Turning the checks off](#turning-the-checks-off)).
* `validation`: `:inline` (the default), the constructors check the constraints of the
schema; `:separate`, minimal types whose constructors do not, with the checks in a
separate, optional file; `:none`, minimal types without any checks (see
[Minimal types](#minimal-types-with-the-validation-in-a-separate-file)).

### Splitting into several files

Expand Down Expand Up @@ -186,6 +190,33 @@ violations(recipe2) # ["batch_size.unit: invalid value \"litre\" for `VolumeUn
writejson("recipe.json", recipe2) # SchemaValidationError
```

### 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:

```julia
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, for example `#/definitions/VolumeType` becomes
Expand Down
4 changes: 3 additions & 1 deletion docs/src/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,9 @@ generate_module
## 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. They are documented in the generated
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.

| Name | Description |
Expand Down
27 changes: 27 additions & 0 deletions docs/src/guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,33 @@ checks off, building a `VolumeType` about 3 times less, and `setfields` on a hop
(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:

```julia
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
Expand Down
4 changes: 4 additions & 0 deletions examples/generate_examples.jl
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,10 @@ generate_module(ex("acme_schemas", "acme_flatschema.json"), joinpath(OUT, "AcmeF
module_name = "AcmeFlat")
generate_module(ex("acme_schemas", "acme_nestedschema.json"), joinpath(OUT, "AcmeNested.jl");
module_name = "AcmeNested")
# the same, with minimal types (constructors that only convert values) and the checks of the
# constraints in a separate, optional file, `AcmeNestedMinimal_validation.jl`
generate_module(ex("acme_schemas", "acme_nestedschema.json"), joinpath(OUT, "AcmeNestedMinimal.jl");
module_name = "AcmeNestedMinimal", validation = :separate)
generate_module(ex("acme_schemas", "acme_nestedschema_mod.json"), joinpath(OUT, "AcmeNestedMod.jl");
module_name = "AcmeNestedMod")
generate_module(ex("acme_schemas", "acme_withreferenceschema.json"), joinpath(OUT, "AcmeWithReference.jl");
Expand Down
Loading
Loading