Crate typify

Typify

Typify lets you convert JSON Schema documents into Rust types. It can be used via a macro import_types! or a build.rs file.

A typical use looks like this:

import_types!("../example.json");

This expands to type definitions corresponding to the types from the file example.json. The types are pub and have a number of useful associated impls including Debug, Clone, Serialize, and Deserialize.

Alternatively, you may use the expanded form:

import_types!(schema = "../example.json");

If you want to add additional derives for the generated types, you can specify them with the derives property of the expanded form:

import_types!(
    schema = "../example.json",
    derives = [schemars::JsonSchema],
);

Generated structs can optionally include a builder-style interface:

import_types!(
    schema = "../example.json",
    struct_builder = true,
);

With this set, consumers can construct a struct Veggie as follows:

let veggie: Veggie = Veggie::builder()
    .veggie_name("radish")
    .veggie_like(true)
    .try_into()
    .unwrap();

Altering Conversion

Renames and additional derivations

You can specify renames types or add additional derive macros for generated types using the patch syntax:

import_types!(
    schema = "../example.json",
    patch = {
        Veggie = {
            rename = "Vegetable",
            derives = [ schemars::JsonSchema ],
        }
    }
);

Replacement types

You can replace a generated type with an existing type by specifying an association between the name of a type with the type to use in its place:

import_types!(
    schema = "../example.json",
    replace = {
        Ipv6Cidr = my_fancy_networking_crate::Ipv6Cidr,
    }
);

Conversion overrides

You can override a conversion for a particular JSON schema construct by specifying an association between the schema and the type.

import_types!(
    schema = "../example.json",
    convert = {
        {
            type = "string",
            format = "uuid",
        } = my_fancy_uuid_crate::MyUuid,
    }
);

Macro vs. build.rs

While using the import_types! macro is quite a bit simpler, you can also construct output in a build.rs script. Doing so requires a little more work to process the JSON Schema document and write out the file to your intended location. The biggest benefit is that the generated type definitions are significantly easier to inspect. The macro-generated types can be viewed with cargo expand and they (like build.rs-derived types) have generated documentation, but if you find that you’d like to see the actual code generated you may prefer a build.rs.

Builder interface

Typify exports a TypeSpace interface that is intended for programmatic construction of types. This can be for something simple like a build.rs script or something more complex like a generator whose input includes JSON schema type definitions.

Mapping JSON Schema to Rust

JSON Schema allows for extreme flexibility. As such, there are some schemas that Typify isn’t able to interpret (please file an issue!). In general, though, Typify does a pretty job of mapping JSON Schema types to Rust. For more information, see the project’s README.md.

Macros

• import_types
  Import types from a schema file. This may be invoked with simply a pathname for a JSON Schema file (relative to $CARGO_MANIFEST_DIR), or it may be invoked with a structured form:

Structs

• Type
  Representation of a type which may have a definition or may be built-in.
• TypeEnum
  Enum type details.
• TypeId
  Type identifier returned from type creation and used to lookup types.
• TypeNewtype
  Newtype details.
• TypeSpace
  A collection of types.
• TypeSpacePatch
  Contains a set of modifications that may be applied to an existing type.
• TypeSpaceSettings
  Settings that alter type generation.
• TypeStruct
  Struct type details.
• TypeStructPropInfo
  Full information pertaining to a struct property.

Enums

• CrateVers
  Specify the version for a named crate to consider for type use (rather than generating types) in the presense of a schema extension.
• Error
• TypeDetails
  Type details returned by Type::details() to inspect a type.
• TypeEnumVariant
  Enum variant details.
• TypeSpaceImpl
• UnknownPolicy
  Policy to apply to external types described by schema extensions whose crates are not explicitly specified.