Debian Codegraph @

externals/OPTIMADE/schemas/src/meta/v1.2/optimade/property_definition.yaml

raw
1 $schema: "https://json-schema.org/draft/2020-12/schema"
2 $id: "https://schemas.optimade.org/meta/v1.2/optimade/property_definition"
3 title: "OPTIMADE property definition schema"
4 type: object
5 allOf:
6 - $ref: "#/$defs/property_definition_field"
7 - required: ["$id", "$schema", "title", "description", "x-optimade-definition"]
8 $$inherit: "physical_unit_definition"
9 $defs:
10 id_field:
11 $$inherit: "/v1.2/common/id_field"
12 property_definition_field:
13 required: ["type", "x-optimade-type", "x-optimade-unit"]
14 anyOf:
15 - type: object
16 required: ["properties"]
17 properties:
18 type:
19 enum: [["object"],["object", "null"]]
20 enum:
21 type: "array"
22 items:
23 type: "object"
24 examples:
25 type: "array"
26 items:
27 type: "object"
28 - type: object
29 required: ["type", "items"]
30 properties:
31 type:
32 enum: [["array"],["array", "null"]]
33 enum:
34 type: "array"
35 items:
36 type: "array"
37 examples:
38 type: "array"
39 items:
40 type: "array"
41 - type: object
42 required: ["type"]
43 properties:
44 type:
45 enum: [["integer"],["integer", "null"]]
46 multipleOf:
47 type: "integer"
48 maximum:
49 type: "integer"
50 exclusiveMaximum:
51 type: "integer"
52 minimum:
53 type: "integer"
54 exclusiveMinimum:
55 type: "integer"
56 enum:
57 type: "array"
58 items:
59 type: "integer"
60 examples:
61 type: "array"
62 items:
63 type: "integer"
64 - type: object
65 required: ["type"]
66 properties:
67 type:
68 enum: [["number"],["number", "null"]]
69 multipleOf:
70 type: "number"
71 maximum:
72 type: "number"
73 exclusiveMaximum:
74 type: "number"
75 minimum:
76 type: "number"
77 exclusiveMinimum:
78 type: "number"
79 enum:
80 type: "array"
81 items:
82 type: "number"
83 examples:
84 type: "array"
85 items:
86 type: "number"
87 - type: object
88 required: ["type"]
89 properties:
90 type:
91 enum: [["string"],["string", "null"]]
92 enum:
93 type: "array"
94 items:
95 type: "string"
96 examples:
97 type: "array"
98 items:
99 type: "string"
100 - type: object
101 required: ["type"]
102 properties:
103 type:
104 enum: [["boolean"],["boolean", "null"]]
105 enum:
106 type: "array"
107 items:
108 type: "boolean"
109 examples:
110 type: "array"
111 items:
112 type: "boolean"
113 properties:
114 type:
115 description: |-
116 Specifies the corresponding JSON type for this level of the defined property and whether the property can be `null` or not.
117 The value is directly correlated with `x-optimade-type` (cf. the `definition of the x-optimade-type field`).
118
119 It MUST be a list of one or two elements where the first element is a string correlated with `x-optimade-type` as follows; if `x-optimade-type` is:
120 * `"boolean"`, `"string"`, or `"integer"` then `type` is the same string.
121 * `"dictionary"` then `type` is `"object"`.
122 * `"list"` then `type` is `"array"`.
123 * `"float"` then `type` is `"number"`.
124 * `"timestamp"` then `type` is `"string"`.
125
126 If the second element is included, it MUST be the string `"null"`.
127 This two element form specifies that the defined property can be `null`.
128 type: array
129 enum: [["object"],["object", "null"],["array"],["array", "null"],["integer"],["integer", "null"],["number"],["number", "null"],["string"],["string", "null"],["boolean"],["boolean", "null"]]
130 items:
131 type: string
132 properties:
133 description: |-
134 Gives key-value pairs where each value is an inner Property Definition.
135 The defined property is a dictionary that can only contain keys present in this dictionary, and, if so, the corresponding value is described by the respective inner Property Definition.
136 (Or, if the type field is the list "object" and "null", it can also be null.)
137 type: object
138 additionalProperties:
139 $ref: '#/$defs/property_definition_field'
140 required:
141 description: |-
142 The defined property MUST have keys that match all the strings in this list.
143 Other keys present in the properties field are OPTIONAL in the defined property.
144 If not present or empty, all keys in properties are regarded as OPTIONAL.
145 type: "array"
146 items:
147 type: string
148 uniqueItems: true
149 maxProperties:
150 description: |-
151 The defined property is a dictionary where the number of keys MUST be less than or equal to the number given.
152 type: "integer"
153 minimum: 0
154 minProperties:
155 description: |-
156 The defined property is a dictionary where the number of keys MUST be greater than or equal to the number given.
157 type: "integer"
158 minimum: 0
159 dependentRequired:
160 description: |-
161 The dictionary keys are strings and the values are lists of unique strings.
162 If the defined property has a key that is equal to a key in the given dictionary, the defined property MUST also have keys that match each of the corresponding values.
163 No restriction is inferred from this field for keys in the defined property that do not match any key in the given dictionary.
164 type: "object"
165 additionalProperties:
166 type: "array"
167 items:
168 type: "string"
169 uniqueItems: true
170 enum:
171 description: "The defined property MUST take one of the values given in the provided list."
172 type: "array"
173 items:
174 $comment: "Must validate against the Property Definition itself, but there is no easy way to express that in the schema."
175 examples:
176 description: "A list of example values that the defined property can have."
177 type: "array"
178 items:
179 $comment: "Must validate against the Property Definition itself, but there is no easy way to express that in the schema."
180 items:
181 allOf:
182 - $ref: '#/$defs/property_definition_field'
183 - description: |-
184 The defined property is a list where each item MUST match this inner Property Definition.
185 uniqueItems:
186 description: "If TRUE, the defined property is an array that MUST only contain unique items. If FALSE, this field sets no limitation on the defined property."
187 type: "boolean"
188 multipleOf:
189 description: |-
190 An integer is strictly greater than 0.
191 The defined property MUST have a value that when divided by the given number results in an integer (i.e., it must be even divisible by this value without a fractional part).
192 type: ["integer", "number"]
193 exclusiveMinimum: 0
194 maximum:
195 description: "The defined property MUST be less than or equal to the given value."
196 type: ["integer","number"]
197 exclusiveMaximum:
198 description: "The defined property MUST be strictly less than the given value; it cannot be equal."
199 type: ["integer","number"]
200 minimum:
201 description: "The defined property MUST be greater than or equal to the given value."
202 type: ["integer","number"]
203 exclusiveMinimum:
204 description: "The defined property MUST be strictly greater than the given value; it cannot be equal."
205 type: ["integer","number"]
206 maxLength:
207 description: |-
208 The defined property is a string that MUST have a length that is less than or equal to the given integer.
209 (The length of the string is the number of individual Unicode characters it is composed of.)
210 type: "integer"
211 minimum: 0
212 minLength:
213 description: |-
214 The defined property is a string that MUST have a length that is less than or equal to the given integer.
215 (The length of the string is the number of individual Unicode characters it is composed of.)
216 type: "integer"
217 minimum: 0
218 format:
219 description: |-
220 Choose one of the following values to indicate that the defined property is a string that MUST adhere to the specified format:
221 - "date-time": the date-time production in RFC 3339 section 5.6.
222 - "date": the full-date production in RFC 3339 section 5.6.
223 - "time": the full-time production in RFC 3339 section 5.6.
224 - "duration": the duration production in RFC 3339 Appendix A.
225 - "email": the "Mailbox" ABNF rule in RFC 5321 section 4.1.2.
226 - "uri": a string instance is valid against this attribute if it is a valid URI according to RFC 3986.
227 - "iri": a string instance is valid against this attribute if it is a valid IRI according to RFC 3987.
228 type: "string"
229 enum: ["date-time", "date", "time", "duration", "email", "uri", "iri"]
230 "$id":
231 allOf:
232 - $ref: '#/$defs/id_field'
233 - description: |-
234 A static IRI identifier that is a URN or URL representing the specific version of this level of the defined property.
235 (If it is a URL, clients SHOULD NOT assign any interpretation to the response when resolving that URL.)
236 It SHOULD NOT be changed as long as the property definition remains the same, and SHOULD be changed when the property definition changes.
237 Property Definitions SHOULD be regarded as the same if they only differ by:
238 - The inclusion or omission of "null" in the type in the outermost layer of the definition.
239 - Additions of annotating notes to end of the description field.
240 - Changes to the following specific fields at any level: deprecated, examples, $comment, x-optimade-implementation, and x-optimade-requirements.
241 "$schema":
242 description: |-
243 A normalized URI for a meta-schema that validates the Property Definition.
244 This SHOULD be https://schemas.optimade.org/meta/{OPTIMADE_VERSION}/optimade/physical_unit_definition.json
245 title:
246 description: |-
247 A short single-line human-readable explanation of the defined property appropriate to show as part of a user interface.
248 type: string
249 description:
250 description: |-
251 A human-readable multi-line description that explains the purpose, requirements, and conventions of the defined property.
252 The format SHOULD be a one-line description, followed by a new paragraph (two newlines), followed by a more detailed description of all the requirements and conventions of the defined property.
253 Formatting in the text SHOULD use Markdown in the CommonMark v0.3 format, with mathematical expressions written to render correctly with the LaTeX mode of Mathjax 3.2 <https://docs.mathjax.org/en/v3.2-latest/>.
254 When possible, it is preferable for mathematical expressions to use as straightforward notation as possible to make them readable also when not rendered.
255
256 Additions appended to the end of the description field that are clearly marked as notes that clarify the definition without changing it are viewed as annotations to the Property Definition rather than an integral part of it.
257 Such annotations SHOULD only be added to the end of an otherwise unmodified description and MUST NOT change the meaning or interpretation of the text above them.
258 The purpose is to provide a way to add explanations and clarifications to a definition without having to regard it as a new definition.
259 For example, these annotations to the description MAY be used to explain why a definition has been deprecated.
260 type: string
261 x-optimade-definition:
262 $$inherit: "x-optimade-definition-field"
263 label: "property_definition_meta"
264 kind: "meta"
265 version: "1.2.1"
266 format: "1.2"
267 name: "property_definition"
268 x-optimade-dimensions:
269 description: |-
270 Specification of the dimensions of one or multi-dimensional data represented as multiple levels of lists.
271 Each dimension is given a name and optionally a fixed size.
272 It was decided that OPTIMADE Property Definitions cannot use the JSON Schema validating fields minItems and maxItems since that would require reprocessing the schema to handle requests asking for only parts of the data in the lists.
273 Instead, provide information on the length of a list for an implementation to validate. This is communicated in the `sizes` subfield of this field. At this time, `sizes` can only specify a fixed length requirement.
274 type: object
275 additionalProperties: false
276 patternProperties:
277 "^x-(?!optimade-)": {}
278 properties:
279 names:
280 description: |-
281 A list of names of the dimensions of the underlying one or multi-dimensionsional data represented as mutiple levels of lists.
282 The order is that the first name applies to the outermost list, the next name to the lists embedded in that list, etc.
283 type: array
284 items:
285 type: string
286 sizes:
287 description: |-
288 A list of fixed length requirements on the underlying one or multi-dimensionsional data represented as mutiple levels of lists.
289 The order is that the first name applies to the outermost list, the next name to the lists embedded in that list, etc.
290 The data only validates if the respective level consists of lists of exactly this length.
291 A value of `null` allows arbitrary-length lists at the corresponding level.
292 type: array
293 items:
294 type:
295 - "integer"
296 - "null"
297 x-optimade-unit-definitions:
298 type: array
299 items:
300 allOf:
301 - $ref: "#/$defs/unit_entity_definition_field"
302 - required: ['title', 'symbol', 'display-symbol', 'description']
303 x-optimade-type:
304 type: string
305 enum:
306 - string
307 - integer
308 - float
309 - boolean
310 - timestamp
311 - list
312 - dictionary
313 x-optimade-unit:
314 type: string
315 x-optimade-implementation:
316 additionalProperties: false
317 patternProperties:
318 "^x-(?!optimade-)": {}
319 properties:
320 query-support:
321 enum:
322 - all mandatory
323 - equality only
324 - partial
325 - none
326 type: string
327 query-support-operators:
328 items:
329 enum:
330 - '<'
331 - '<='
332 - '>'
333 - '>='
334 - '='
335 - '!='
336 - 'CONTAINS'
337 - 'STARTS WITH'
338 - 'ENDS WITH'
339 - 'HAS'
340 - 'HAS ALL'
341 - 'HAS ANY'
342 - 'HAS ONLY'
343 - 'IS KNOWN'
344 - 'IS UNKNOWN'
345 type: string
346 type: array
347 response-level:
348 enum:
349 - "always"
350 - "yes"
351 - "no"
352 sortable:
353 type: boolean
354 "$comment":
355 type: string
356 type: object
357 x-optimade-requirements:
358 additionalProperties: false
359 patternProperties:
360 "^x-(?!optimade-)": {}
361 properties:
362 query-support:
363 enum:
364 - all mandatory
365 - equality only
366 - partial
367 - none
368 type: string
369 query-support-operators:
370 items:
371 enum:
372 - '<'
373 - '<='
374 - '>'
375 - '>='
376 - '='
377 - '!='
378 - 'CONTAINS'
379 - 'STARTS WITH'
380 - 'ENDS WITH'
381 - 'HAS'
382 - 'HAS ALL'
383 - 'HAS ANY'
384 - 'HAS ONLY'
385 - 'IS KNOWN'
386 - 'IS UNKNOWN'
387 type: string
388 type: array
389 response-level:
390 enum:
391 - always
392 - must
393 - should
394 - may
395 - should not
396 - must not
397 type: string
398 sortable:
399 type: boolean
400 support:
401 enum:
402 - must
403 - should
404 - may
405 type: string
406 "$comment":
407 type: string
408 type: object
409 x-optimade-metadata-definition:
410 description: |-
411 A dictionary that is a property definition of a dictionary-type property that defines all metadata properties.
412 allOf:
413 - $ref: '#/$defs/property_definition_field'
414 - properties:
415 type:
416 enum:
417 - ["object", "null"]
418 "$comment":
419 description: |-
420 A human-readable comment relevant in the context of the raw definition data.
421 These comments should normally not be shown to the end users.
422 Comments pertaining to the Property Definition that are relevant to end users should go into the field description.
423 Formatting in the text SHOULD use Markdown using the format described in the definition of the description field.
424
425 This field is an annotation rather than an integral part of the Property Definition.
426 Property Definitions that only differ by fields that are considered annotations are to be considered the same, and as explained in the definition of the $id field SHOULD share the same $id.
427 type: string
428 deprecated:
429 description: |-
430 If TRUE, implementations SHOULD not use the defined property, and it MAY be removed in the future.
431 If FALSE, the defined property is not deprecated. The field not being present means FALSE.
432
433 This field is an annotation rather than an integral part of the Property Definition.
434 Property Definitions that only differ by fields that are considered annotations are to be considered the same, and as explained in the definition of the $id field SHOULD share the same $id.
435 type: boolean
436 # Allow database-specific fields
437 additionalProperties: false
438 patternProperties:
439 "^x-(?!optimade-)": {}