Struct Schema

pub struct Schema(/* private fields */);

A JSON Schema.

This wraps a JSON Value that must be either an object or a bool.

A custom JSON schema can be created using the json_schema! macro:

use schemars::{Schema, json_schema};

let my_schema: Schema = json_schema!({
    "type": ["object", "null"]
});

Because a Schema is a thin wrapper around a Value, you can also use TryFrom::try_from/TryInto::try_into to create a Schema from an existing Value. This operation is fallible, because only objects and bools can be converted in this way.

use schemars::{Schema, json_schema};
use serde_json::json;

let json_object = json!({"type": ["object", "null"]});
let object_schema: Schema = json_object.try_into().unwrap();

let json_bool = json!(true);
let bool_schema: Schema = json_bool.try_into().unwrap();

let json_string = json!("This is neither an object nor a bool!");
assert!(Schema::try_from(json_string).is_err());

// You can also convert a `&Value`/`&mut Value` to a `&Schema`/`&mut Schema` the same way:

let json_object = json!({"type": ["object", "null"]});
let object_schema_ref: &Schema = (&json_object).try_into().unwrap();

let mut json_object = json!({"type": ["object", "null"]});
let object_schema_mut: &mut Schema = (&mut json_object).try_into().unwrap();

Similarly, you can use From/Into to (infallibly) create a Schema from an existing Map<String, Value> or bool.

use schemars::{Schema, json_schema};
use serde_json::{Map, json};

let mut map = Map::new();
map.insert("type".to_owned(), json!(["object", "null"]));
let object_schema: Schema = map.into();

let bool_schema: Schema = true.into();

Implementations

impl Schema

pub fn new_ref(reference: String) -> Self

Creates a new schema object with a single string property "$ref".

The given reference string should be a URI reference. This will usually be a JSON Pointer in URI Fragment representation.

pub fn as_value(&self) -> &Value

Borrows the Schema’s underlying JSON value.

pub fn as_bool(&self) -> Option<bool>

If the Schema’s underlying JSON value is a bool, returns the bool value.

pub fn as_object(&self) -> Option<&Map<String, Value>>

If the Schema’s underlying JSON value is an object, borrows the object as a Map of properties.

pub fn as_object_mut(&mut self) -> Option<&mut Map<String, Value>>

If the Schema’s underlying JSON value is an object, mutably borrows the object as a Map of properties.

pub fn to_value(self) -> Value

Returns the Schema’s underlying JSON value.

pub fn ensure_object(&mut self) -> &mut Map<String, Value>

Converts the Schema (if it wraps a bool value) into an equivalent object schema. Then mutably borrows the object as a Map of properties.

true is transformed into an empty schema {}, which successfully validates against all possible values. false is transformed into the schema {"not": {}}, which does not successfully validate against any value.

pub fn insert(&mut self, k: String, v: Value) -> Option<Value>

Inserts a property into the schema, replacing any previous value.

If the schema wraps a bool value, it will first be converted into an equivalent object schema.

If the schema did not have this key present, None is returned.

If the schema did have this key present, the value is updated, and the old value is returned.

Example

use schemars::json_schema;
use serde_json::json;

let mut schema = json_schema!(true);
assert_eq!(schema.insert("type".to_owned(), "array".into()), None);
assert_eq!(schema.insert("type".to_owned(), "object".into()), Some(json!("array")));

assert_eq!(schema, json_schema!({"type": "object"}));

pub fn get<Q>(&self, key: &Q) -> Option<&Value>

where String: Borrow<Q>, Q: ?Sized + Ord + Eq + Hash,

If the Schema’s underlying JSON value is an object, gets a reference to that object’s value for the given key if it exists.

This always returns None for bool schemas.

Example

use schemars::json_schema;
use serde_json::json;

let obj_schema = json_schema!({"type": "array"});
assert_eq!(obj_schema.get("type"), Some(&json!("array")));
assert_eq!(obj_schema.get("format"), None);

let bool_schema = json_schema!(true);
assert_eq!(bool_schema.get("type"), None);

pub fn get_mut<Q>(&mut self, key: &Q) -> Option<&mut Value>

where String: Borrow<Q>, Q: ?Sized + Ord + Eq + Hash,

If the Schema’s underlying JSON value is an object, gets a mutable reference to that object’s value for the given key if it exists.

This always returns None for bool schemas.

Example

use schemars::json_schema;
use serde_json::{json, Value};

let mut obj_schema = json_schema!({ "properties": {} });
if let Some(Value::Object(properties)) = obj_schema.get_mut("properties") {
    properties.insert("anything".to_owned(), true.into());
}
assert_eq!(obj_schema, json_schema!({ "properties": { "anything": true } }));

pub fn pointer(&self, pointer: &str) -> Option<&Value>

If the Schema’s underlying JSON value is an object, looks up a value within the schema by a JSON Pointer.

If the given pointer begins with a #, then the rest of the value is assumed to be in “URI Fragment Identifier Representation”, and will be percent-decoded accordingly.

For more information on JSON Pointer, read RFC6901.

This always returns None for bool schemas.

Example

use schemars::json_schema;
use serde_json::json;

let schema = json_schema!({
    "properties": {
        "anything": true
    },
    "$defs": {
        "🚀": true
    }
});

assert_eq!(schema.pointer("/properties/anything").unwrap(), &json!(true));
assert_eq!(schema.pointer("#/$defs/%F0%9F%9A%80").unwrap(), &json!(true));
assert_eq!(schema.pointer("/does/not/exist"), None);

pub fn pointer_mut(&mut self, pointer: &str) -> Option<&mut Value>

If the Schema’s underlying JSON value is an object, looks up a value by a JSON Pointer and returns a mutable reference to that value.

For more information on JSON Pointer, read RFC6901.

This always returns None for bool schemas.

Example

use schemars::{json_schema, Schema};
use serde_json::json;

let mut schema = json_schema!({
    "properties": {
        "anything": true
    }
});

let subschema_value = schema.pointer_mut("/properties/anything").unwrap();
let subschema: &mut Schema = subschema_value.try_into().unwrap();
subschema.ensure_object();

assert_eq!(schema.pointer_mut("/properties/anything").unwrap(), &json!({}));

pub fn remove<Q>(&mut self, key: &Q) -> Option<Value>

where String: Borrow<Q>, Q: ?Sized + Ord + Eq + Hash,

If the Schema’s underlying JSON value is an object, removes and returns its value for the given key.

This always returns None for bool schemas, without modifying them.

Example

use schemars::json_schema;
use serde_json::json;

let mut schema = json_schema!({"type": "array"});
assert_eq!(schema.remove("type"), Some(json!("array")));
assert_eq!(schema, json_schema!({}));

Trait Implementations

impl Clone for Schema

fn clone(&self) -> Schema

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Schema

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Schema

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Schema

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl From<Map<String, Value>> for Schema

fn from(o: Map<String, Value>) -> Self

Converts to this type from the input type.

impl From<Schema> for Value

fn from(v: Schema) -> Value

Converts to this type from the input type.

impl From<bool> for Schema

fn from(b: bool) -> Self

Converts to this type from the input type.

impl JsonSchema for Schema

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

The name of the generated JSON Schema.

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

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

fn json_schema(_: &mut SchemaGenerator) -> Schema

Generates a JSON Schema for this type.

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.

impl PartialEq<Map<String, Value>> for Schema

fn eq(&self, other: &Map<String, Value>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Schema> for Map<String, Value>

fn eq(&self, other: &Schema) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Schema> for Value

fn eq(&self, other: &Schema) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Schema> for bool

fn eq(&self, other: &Schema) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Value> for Schema

fn eq(&self, other: &Value) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<bool> for Schema

fn eq(&self, other: &bool) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq for Schema

fn eq(&self, other: &Schema) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Schema

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl<'a> TryFrom<&'a Value> for &'a Schema

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: &Value) -> Result<&Schema>

Performs the conversion.

impl<'a> TryFrom<&'a mut Value> for &'a mut Schema

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: &mut Value) -> Result<&mut Schema>

Performs the conversion.

impl TryFrom<Value> for Schema

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: Value) -> Result<Schema>

Performs the conversion.

impl StructuralPartialEq for Schema