pub trait JsonSchema {
// Required methods
fn schema_name() -> String;
fn json_schema(gen: &mut SchemaGenerator) -> Schema;
// Provided methods
fn is_referenceable() -> 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)].
§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::{gen::SchemaGenerator, schema::Schema, JsonSchema};
use std::borrow::Cow;
struct NonGenericType;
impl JsonSchema for NonGenericType {
fn schema_name() -> String {
// Exclude the module path to make the name in generated schemas clearer.
"NonGenericType".to_owned()
}
fn schema_id() -> Cow<'static, str> {
// Include the module, in case a type with the same name is in another module/crate
Cow::Borrowed(concat!(module_path!(), "::NonGenericType"))
}
fn json_schema(_gen: &mut SchemaGenerator) -> Schema {
todo!()
}
}
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::{gen::SchemaGenerator, schema::Schema, JsonSchema};
use std::{borrow::Cow, marker::PhantomData};
struct GenericType<T>(PhantomData<T>);
impl<T: JsonSchema> JsonSchema for GenericType<T> {
fn schema_name() -> String {
format!("GenericType_{}", T::schema_name())
}
fn schema_id() -> Cow<'static, str> {
Cow::Owned(format!(
"{}::GenericType<{}>",
module_path!(),
T::schema_id()
))
}
fn json_schema(_gen: &mut SchemaGenerator) -> Schema {
todo!()
}
}
assert_eq!(<GenericType<i32>>::schema_id(), <&mut GenericType<&i32>>::schema_id());Required Methods§
sourcefn schema_name() -> String
fn schema_name() -> String
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(gen: &mut SchemaGenerator) -> Schema
fn json_schema(gen: &mut SchemaGenerator) -> Schema
Generates a JSON Schema for this type.
If the returned schema depends on any referenceable schemas, then this method will
add them to the SchemaGenerator’s schema definitions.
This should not return a $ref schema.
Provided Methods§
sourcefn is_referenceable() -> bool
fn is_referenceable() -> bool
Whether JSON Schemas generated for this type should be re-used where possible using the $ref keyword.
For trivial types (such as primitives), this should return false. For more complex types, it should return true.
For recursive types, this must return true to prevent infinite cycles when generating schemas.
By default, this returns true.
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().
Object Safety§
This trait is not object safe.