Trait JsonSchema

pub trait JsonSchema {
    // Required methods
    fn schema_name() -> Cow<'static, str>;
    fn json_schema(generator: &mut SchemaGenerator) -> Schema;

    // Provided methods
    fn inline_schema() -> bool { ... }
    fn schema_id() -> Cow<'static, str> { ... }
}

Expand description

Re-export of the schemars derive macro and trait. Deriving JsonSchema on your Rust type is what makes schema_for / schema_for_yaml produce a schema for it.

§Downstream `Cargo.toml`

The proc-macro that powers #[derive(JsonSchema)] expands to code that references ::schemars::... paths in the call site’s dep graph. That means downstream crates that derive JsonSchema must add schemars to their own Cargo.toml alongside noyalib:

[dependencies]
noyalib = { version = "0.0.7", features = ["schema"] }
schemars = "1.2"

(Same precedent as serde::Deserialize — derive macros that re-export through a wrapper crate cannot rewrite the generated paths without an explicit #[schemars(crate = "...")] attribute on every type.)

§Examples

use noyalib::JsonSchema;

#[derive(JsonSchema)]
struct Cfg { port: u16 }

A type which can be described as a JSON Schema document.

This is implemented for many Rust primitive and standard library types.

This can also be automatically derived on most custom types with #[derive(JsonSchema)] by enabling the derive feature flag (which is enabled by default). For more info on deriving JsonSchema, see the derive macro documentation.

§Examples

Deriving an implementation:

use schemars::{schema_for, JsonSchema};

#[derive(JsonSchema)]
struct MyStruct {
    foo: i32,
}

let my_schema = schema_for!(MyStruct);

When manually implementing JsonSchema, as well as determining an appropriate schema, you will need to determine an appropriate name and ID for the type. For non-generic types, the type name/path are suitable for this:

use schemars::{SchemaGenerator, Schema, JsonSchema, json_schema};
use std::borrow::Cow;

struct NonGenericType;

impl JsonSchema for NonGenericType {
    fn schema_name() -> Cow<'static, str> {
        // Exclude the module path to make the name in generated schemas clearer.
        "NonGenericType".into()
    }

    fn schema_id() -> Cow<'static, str> {
        // Include the module, in case a type with the same name is in another module/crate
        concat!(module_path!(), "::NonGenericType").into()
    }

    fn json_schema(_gen: &mut SchemaGenerator) -> Schema {
        json_schema!({
            "foo": "bar"
        })
    }
}

assert_eq!(NonGenericType::schema_id(), <&mut NonGenericType>::schema_id());

But generic type parameters which may affect the generated schema should typically be included in the name/ID:

use schemars::{SchemaGenerator, Schema, JsonSchema, json_schema};
use std::{borrow::Cow, marker::PhantomData};

struct GenericType<T>(PhantomData<T>);

impl<T: JsonSchema> JsonSchema for GenericType<T> {
    fn schema_name() -> Cow<'static, str> {
        format!("GenericType_{}", T::schema_name()).into()
    }

    fn schema_id() -> Cow<'static, str> {
        format!(
            "{}::GenericType<{}>",
            module_path!(),
            T::schema_id()
        ).into()
    }

    fn json_schema(_gen: &mut SchemaGenerator) -> Schema {
        json_schema!({
            "foo": "bar"
        })
    }
}

assert_eq!(<GenericType<i32>>::schema_id(), <&mut GenericType<&i32>>::schema_id());

Required Methods§

fn schema_name() -> Cow<'static, str>

The name of the generated JSON Schema.

This is used as the title for root schemas, and the key within the root’s definitions property for subschemas.

fn json_schema(generator: &mut SchemaGenerator) -> Schema

Generates a JSON Schema for this type.

If the returned schema depends on any non-inlined schemas, then this method will add them to the [SchemaGenerator]’s schema definitions.

This should not return a $ref schema.

Trait JsonSchema Copy item path

§Downstream Cargo.toml

§Examples

§Examples

Required Methods§

fn schema_name() -> Cow<'static, str>

fn json_schema(generator: &mut SchemaGenerator) -> Schema

Provided Methods§

fn inline_schema() -> bool

fn schema_id() -> Cow<'static, str>

Dyn Compatibility§

Implementations on Foreign Types§

impl JsonSchema for ()

fn inline_schema() -> bool

fn schema_name() -> Cow<'static, str>

fn json_schema(_: &mut SchemaGenerator) -> Schema

impl JsonSchema for Atomic<bool>

fn inline_schema() -> bool

fn schema_name() -> Cow<'static, str>

fn schema_id() -> Cow<'static, str>

fn json_schema(generator: &mut SchemaGenerator) -> Schema

impl JsonSchema for Atomic<i8>

fn inline_schema() -> bool

fn schema_name() -> Cow<'static, str>

fn schema_id() -> Cow<'static, str>

fn json_schema(generator: &mut SchemaGenerator) -> Schema

impl JsonSchema for Atomic<i16>

fn inline_schema() -> bool

fn schema_name() -> Cow<'static, str>

fn schema_id() -> Cow<'static, str>

fn json_schema(generator: &mut SchemaGenerator) -> Schema

impl JsonSchema for Atomic<i32>

fn inline_schema() -> bool

fn schema_name() -> Cow<'static, str>

fn schema_id() -> Cow<'static, str>

fn json_schema(generator: &mut SchemaGenerator) -> Schema

impl JsonSchema for Atomic<i64>

fn inline_schema() -> bool

fn schema_name() -> Cow<'static, str>

fn schema_id() -> Cow<'static, str>

fn json_schema(generator: &mut SchemaGenerator) -> Schema

impl JsonSchema for Atomic<isize>

fn inline_schema() -> bool

fn schema_name() -> Cow<'static, str>

fn schema_id() -> Cow<'static, str>

fn json_schema(generator: &mut SchemaGenerator) -> Schema

impl JsonSchema for Atomic<u8>

fn inline_schema() -> bool

fn schema_name() -> Cow<'static, str>

fn schema_id() -> Cow<'static, str>

fn json_schema(generator: &mut SchemaGenerator) -> Schema

impl JsonSchema for Atomic<u16>

fn inline_schema() -> bool

fn schema_name() -> Cow<'static, str>

fn schema_id() -> Cow<'static, str>

fn json_schema(generator: &mut SchemaGenerator) -> Schema

impl JsonSchema for Atomic<u32>

fn inline_schema() -> bool

fn schema_name() -> Cow<'static, str>

fn schema_id() -> Cow<'static, str>

fn json_schema(generator: &mut SchemaGenerator) -> Schema

impl JsonSchema for Atomic<u64>

fn inline_schema() -> bool

fn schema_name() -> Cow<'static, str>

fn schema_id() -> Cow<'static, str>

fn json_schema(generator: &mut SchemaGenerator) -> Schema

impl JsonSchema for Atomic<usize>

fn inline_schema() -> bool

fn schema_name() -> Cow<'static, str>

fn schema_id() -> Cow<'static, str>

fn json_schema(generator: &mut SchemaGenerator) -> Schema

impl JsonSchema for CStr

fn inline_schema() -> bool

fn schema_name() -> Cow<'static, str>

fn schema_id() -> Cow<'static, str>

fn json_schema(generator: &mut SchemaGenerator) -> Schema

impl JsonSchema for CString

fn schema_name() -> Cow<'static, str>

fn schema_id() -> Cow<'static, str>

fn json_schema(generator: &mut SchemaGenerator) -> Schema

Trait JsonSchema

§Downstream `Cargo.toml`