jsonschema_schema/schema/vocabularies/meta_data.rs
1use serde_json::Value;
2
3/// Meta-data vocabulary — annotations (title, description, etc.).
4///
5/// See [JSON Schema Validation §9](https://json-schema.org/draft/2020-12/json-schema-validation#section-9).
6#[derive(
7 Debug,
8 Clone,
9 Default,
10 PartialEq,
11 Eq,
12 serde::Serialize,
13 serde::Deserialize,
14 schemars::JsonSchema,
15 combine_structs::Fields,
16)]
17pub struct MetaDataVocabulary {
18 /// The `title` keyword — short summary annotation.
19 ///
20 /// The value of this keyword MUST be a string.
21 ///
22 /// Both `"title"` and `"description"` can be used to decorate a
23 /// user interface with information about the data produced by this
24 /// user interface. A title will preferably be short, whereas a
25 /// description will provide explanation about the purpose of the
26 /// instance described by this schema.
27 ///
28 /// See [JSON Schema Validation §9.1](https://json-schema.org/draft/2020-12/json-schema-validation#section-9.1).
29 #[serde(skip_serializing_if = "Option::is_none")]
30 pub title: Option<String>,
31
32 /// The `description` keyword — explanatory annotation.
33 ///
34 /// The value of this keyword MUST be a string.
35 ///
36 /// Both `"title"` and `"description"` can be used to decorate a
37 /// user interface with information about the data produced by this
38 /// user interface. A title will preferably be short, whereas a
39 /// description will provide explanation about the purpose of the
40 /// instance described by this schema.
41 ///
42 /// See [JSON Schema Validation §9.1](https://json-schema.org/draft/2020-12/json-schema-validation#section-9.1).
43 #[serde(skip_serializing_if = "Option::is_none")]
44 pub description: Option<String>,
45
46 /// The `default` keyword — default value annotation.
47 ///
48 /// There are no restrictions placed on the value of this keyword.
49 /// When multiple occurrences of this keyword are applicable to a
50 /// single sub-instance, implementations SHOULD remove duplicates.
51 ///
52 /// This keyword can be used to supply a default JSON value
53 /// associated with a particular schema. It is RECOMMENDED that a
54 /// default value be valid against the associated schema.
55 ///
56 /// See [JSON Schema Validation §9.2](https://json-schema.org/draft/2020-12/json-schema-validation#section-9.2).
57 #[serde(skip_serializing_if = "Option::is_none")]
58 pub default: Option<Value>,
59
60 /// The `deprecated` keyword — deprecation annotation.
61 ///
62 /// The value of this keyword MUST be a boolean. When multiple
63 /// occurrences of this keyword are applicable to a single
64 /// sub-instance, applications SHOULD consider the instance location
65 /// to be deprecated if any occurrence specifies a true value.
66 ///
67 /// If `"deprecated"` has a value of boolean true, it indicates that
68 /// applications SHOULD refrain from usage of the declared property.
69 /// It MAY mean the property is going to be removed in the future.
70 ///
71 /// A root schema containing `"deprecated"` with a value of true
72 /// indicates that the entire resource being described MAY be removed
73 /// in the future.
74 ///
75 /// The `"deprecated"` keyword applies to each instance location to
76 /// which the schema object containing the keyword successfully
77 /// applies. This can result in scenarios where every array item or
78 /// object property is deprecated even though the containing array
79 /// or object is not.
80 ///
81 /// Omitting this keyword has the same behavior as a value of false.
82 ///
83 /// See [JSON Schema Validation §9.3](https://json-schema.org/draft/2020-12/json-schema-validation#section-9.3).
84 #[serde(default, skip_serializing_if = "crate::schema::is_false")]
85 #[schemars(extend("default" = false))]
86 pub deprecated: bool,
87
88 /// The `readOnly` keyword — read-only annotation.
89 ///
90 /// The value of this keyword MUST be a boolean. When multiple
91 /// occurrences of this keyword are applicable to a single
92 /// sub-instance, the resulting behavior SHOULD be as for a true
93 /// value if any occurrence specifies a true value, and SHOULD be as
94 /// for a false value otherwise.
95 ///
96 /// If `"readOnly"` has a value of boolean true, it indicates that
97 /// the value of the instance is managed exclusively by the owning
98 /// authority, and attempts by an application to modify the value of
99 /// this property are expected to be ignored or rejected by that
100 /// owning authority.
101 ///
102 /// An instance document that is marked as `"readOnly"` for the
103 /// entire document MAY be ignored if sent to the owning authority,
104 /// or MAY result in an error, at the authority's discretion.
105 ///
106 /// Omitting this keyword has the same behavior as a value of false.
107 ///
108 /// See [JSON Schema Validation §9.4](https://json-schema.org/draft/2020-12/json-schema-validation#section-9.4).
109 #[serde(
110 default,
111 rename = "readOnly",
112 skip_serializing_if = "crate::schema::is_false"
113 )]
114 #[schemars(extend("default" = false))]
115 pub read_only: bool,
116
117 /// The `writeOnly` keyword — write-only annotation.
118 ///
119 /// The value of this keyword MUST be a boolean.
120 ///
121 /// If `"writeOnly"` has a value of boolean true, it indicates that
122 /// the value is never present when the instance is retrieved from
123 /// the owning authority. It can be present when sent to the owning
124 /// authority to update or create the document (or the resource it
125 /// represents), but it will not be included in any updated or newly
126 /// created version of the instance.
127 ///
128 /// An instance document that is marked as `"writeOnly"` for the
129 /// entire document MAY be returned as a blank document of some
130 /// sort, or MAY produce an error upon retrieval, or have the
131 /// retrieval request ignored, at the authority's discretion.
132 ///
133 /// Omitting this keyword has the same behavior as a value of false.
134 ///
135 /// See [JSON Schema Validation §9.4](https://json-schema.org/draft/2020-12/json-schema-validation#section-9.4).
136 #[serde(
137 default,
138 rename = "writeOnly",
139 skip_serializing_if = "crate::schema::is_false"
140 )]
141 #[schemars(extend("default" = false))]
142 pub write_only: bool,
143
144 /// The `examples` keyword — example values annotation.
145 ///
146 /// The value of this keyword MUST be an array. There are no
147 /// restrictions placed on the values within the array. When
148 /// multiple occurrences of this keyword are applicable to a single
149 /// sub-instance, implementations MUST provide a flat array of all
150 /// values rather than an array of arrays.
151 ///
152 /// This keyword can be used to provide sample JSON values
153 /// associated with a particular schema, for the purpose of
154 /// illustrating usage. It is RECOMMENDED that these values be valid
155 /// against the associated schema.
156 ///
157 /// Implementations MAY use the value(s) of `"default"`, if present,
158 /// as an additional example. If `"examples"` is absent, `"default"`
159 /// MAY still be used in this manner.
160 ///
161 /// See [JSON Schema Validation §9.5](https://json-schema.org/draft/2020-12/json-schema-validation#section-9.5).
162 #[serde(skip_serializing_if = "Option::is_none")]
163 pub examples: Option<Vec<Value>>,
164}