Generate JSON Schema documents from Rust code
Generate JSON Schema documents from Rust code
If you don't really care about the specifics, the easiest way to generate a JSON schema for your types is to
#[derive(JsonSchema)]and use the
schema_for!macro. All fields of the type must also implement
JsonSchema- Schemars implements this for many standard library types.
use schemars::{schema_for, JsonSchema};#[derive(JsonSchema)] pub struct MyStruct { pub my_int: i32, pub my_bool: bool, pub my_nullable_enum: Option, }
#[derive(JsonSchema)] pub enum MyEnum { StringNewType(String), StructVariant { floats: Vec }, }
fn main() { let schema = schema_for!(MyStruct); println!("{}", serde_json::to_string_pretty(&schema).unwrap()); }
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "MyStruct",
"type": "object",
"required": [
"my_bool",
"my_int"
],
"properties": {
"my_bool": {
"type": "boolean"
},
"my_int": {
"type": "integer",
"format": "int32"
},
"my_nullable_enum": {
"anyOf": [
{
"$ref": "#/definitions/MyEnum"
},
{
"type": "null"
}
]
}
},
"definitions": {
"MyEnum": {
"anyOf": [
{
"type": "object",
"required": [
"StringNewType"
],
"properties": {
"StringNewType": {
"type": "string"
}
}
},
{
"type": "object",
"required": [
"StructVariant"
],
"properties": {
"StructVariant": {
"type": "object",
"required": [
"floats"
],
"properties": {
"floats": {
"type": "array",
"items": {
"type": "number",
"format": "float"
}
}
}
}
}
}
]
}
}
}
One of the main aims of this library is compatibility with Serde. Any generated schema should match how serde_json would serialize/deserialize to/from JSON. To support this, Schemars will check for any
#[serde(...)]attributes on types that derive
JsonSchema, and adjust the generated schema accordingly.
use schemars::{schema_for, JsonSchema}; use serde::{Deserialize, Serialize};#[derive(Deserialize, Serialize, JsonSchema)] #[serde(rename_all = "camelCase", deny_unknown_fields)] pub struct MyStruct { #[serde(rename = "myNumber")] pub my_int: i32, pub my_bool: bool, #[serde(default)] pub my_nullable_enum: Option, }
#[derive(Deserialize, Serialize, JsonSchema)] #[serde(untagged)] pub enum MyEnum { StringNewType(String), StructVariant { floats: Vec }, }
fn main() { let schema = schema_for!(MyStruct); println!("{}", serde_json::to_string_pretty(&schema).unwrap()); }
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "MyStruct",
"type": "object",
"required": [
"myBool",
"myNumber"
],
"properties": {
"myBool": {
"type": "boolean"
},
"myNullableEnum": {
"default": null,
"anyOf": [
{
"$ref": "#/definitions/MyEnum"
},
{
"type": "null"
}
]
},
"myNumber": {
"type": "integer",
"format": "int32"
}
},
"additionalProperties": false,
"definitions": {
"MyEnum": {
"anyOf": [
{
"type": "string"
},
{
"type": "object",
"required": [
"floats"
],
"properties": {
"floats": {
"type": "array",
"items": {
"type": "number",
"format": "float"
}
}
}
}
]
}
}
}
#[serde(...)]attributes can be overriden using
#[schemars(...)]attributes, which behave identically (e.g.
#[schemars(rename_all = "camelCase")]). You may find this useful if you want to change the generated schema without affecting Serde's behaviour, or if you're just not using Serde.
derive(enabled by default) - provides
#[derive(JsonSchema)]macro
impl_json_schema- implements
JsonSchemafor Schemars types themselves
preserve_order- keep the order of struct fields in
Schemaand
SchemaObject
Schemars can implement
JsonSchemaon types from several popular crates, enabled via optional dependencies (dependency versions are shown in brackets): -
chrono(^0.4) -
indexmap(^1.2) -
either(^1.3) -
uuid(^0.8) -
smallvec(^1.0) -
arrayvec(^0.5)