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
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§
Sourcefn schema_name() -> Cow<'static, str>
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.
Sourcefn json_schema(generator: &mut SchemaGenerator) -> Schema
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§
Sourcefn inline_schema() -> bool
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.
Sourcefn schema_id() -> Cow<'static, str>
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", so this trait is not object safe.