Trait JsonSchema

Source

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> { ... }
}

Available on crate feature schema only.

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§

Source

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.

Source

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.

Provided Methods§

Source

fn inline_schema() -> bool

Whether JSON Schemas generated for this type should be included directly in parent schemas, rather than being re-used where possible using the $ref keyword.

For trivial types (such as primitives), this should return true. For more complex types, it should return false. For recursive types, this must return false to prevent infinite cycles when generating schemas.

By default, this returns false.

Source

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

Returns a string that uniquely identifies the schema produced by this type.

This does not have to be a human-readable string, and the value will not itself be included in generated schemas. If two types produce different schemas, then they must have different schema_id()s, but two types that produce identical schemas should ideally have the same schema_id().

The default implementation returns the same value as schema_name().

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

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`