[−][src]Crate schemars
Generate JSON Schema documents from Rust code
Basic Usage
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<MyEnum>, } #[derive(JsonSchema)] pub enum MyEnum { StringNewType(String), StructVariant { floats: Vec<f32>, } } fn main() { let schema = schema_for!(MyStruct); println!("{}", serde_json::to_string_pretty(&schema).unwrap()); }
Click to see the output JSON schema...
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "MyStruct",
"type": "object",
"required": [
"my_bool",
"my_int",
"my_nullable_enum"
],
"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"
}
}
}
}
}
}
]
}
}
}
Serde Compatibility
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")] pub struct MyStruct { #[serde(rename = "myNumber")] pub my_int: i32, pub my_bool: bool, #[serde(default)] pub my_nullable_enum: Option<MyEnum>, } #[derive(Deserialize, Serialize, JsonSchema)] #[serde(untagged)] pub enum MyEnum { StringNewType(String), StructVariant { floats: Vec<f32>, } } fn main() { let schema = schema_for!(MyStruct); println!("{}", serde_json::to_string_pretty(&schema).unwrap()); }
Click to see the output JSON schema...
{
"$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"
}
},
"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.
Feature Flags
impl_json_schema
- implementsJsonSchema
for Schemars types themselves
Optional Dependencies
Schemars can implement JsonSchema
on types from several popular crates, enabled via optional dependencies (dependency versions are shown in brackets):
Modules
gen | JSON Schema generator and settings. |
schema | JSON Schema types. |
Macros
schema_for | Generates a |
Traits
JsonSchema | A type which can be described as a JSON Schema document. |
Type Definitions
Map | The map type used by schemars types. |
Set | The set type used by schemars types. |
Derive Macros
JsonSchema |