Debian Codegraph @

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

raw
1 $schema: "https://json-schema.org/draft/2020-12/schema"
2 $id: "https://schemas.optimade.org/meta/v1.3/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: "/v1.2/optimade/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 * provider-specific data type, then `type` is the JSON type used as a carrier for this data type.
126
127 If the second element is included, it MUST be the string `"null"`.
128 This two element form specifies that the defined property can be `null`.
129 type: array
130 enum: [["object"],["object", "null"],["array"],["array", "null"],["integer"],["integer", "null"],["number"],["number", "null"],["string"],["string", "null"],["boolean"],["boolean", "null"]]
131 items:
132 type: string
133 properties:
134 description: |-
135 Gives key-value pairs where each value is an inner Property Definition.
136 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.
137 (Or, if the type field is the list "object" and "null", it can also be null.)
138 type: object
139 additionalProperties:
140 $ref: '#/$defs/property_definition_field'
141 required:
142 description: |-
143 The defined property MUST have keys that match all the strings in this list.
144 Other keys present in the properties field are OPTIONAL in the defined property.
145 If not present or empty, all keys in properties are regarded as OPTIONAL.
146 type: "array"
147 items:
148 type: string
149 uniqueItems: true
150 maxProperties:
151 description: |-
152 The defined property is a dictionary where the number of keys MUST be less than or equal to the number given.
153 type: "integer"
154 minimum: 0
155 minProperties:
156 description: |-
157 The defined property is a dictionary where the number of keys MUST be greater than or equal to the number given.
158 type: "integer"
159 minimum: 0
160 dependentRequired:
161 description: |-
162 The dictionary keys are strings and the values are lists of unique strings.
163 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.
164 No restriction is inferred from this field for keys in the defined property that do not match any key in the given dictionary.
165 type: "object"
166 additionalProperties:
167 type: "array"
168 items:
169 type: "string"
170 uniqueItems: true
171 enum:
172 description: "The defined property MUST take one of the values given in the provided list."
173 type: "array"
174 items:
175 $comment: "Must validate against the Property Definition itself, but there is no easy way to express that in the schema."
176 examples:
177 description: "A list of example values that the defined property can have."
178 type: "array"
179 items:
180 $comment: "Must validate against the Property Definition itself, but there is no easy way to express that in the schema."
181 items:
182 allOf:
183 - $ref: '#/$defs/property_definition_field'
184 - description: |-
185 The defined property is a list where each item MUST match this inner Property Definition.
186 uniqueItems:
187 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."
188 type: "boolean"
189 multipleOf:
190 description: |-
191 An integer is strictly greater than 0.
192 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).
193 type: ["integer", "number"]
194 exclusiveMinimum: 0
195 maximum:
196 description: "The defined property MUST be less than or equal to the given value."
197 type: ["integer","number"]
198 exclusiveMaximum:
199 description: "The defined property MUST be strictly less than the given value; it cannot be equal."
200 type: ["integer","number"]
201 minimum:
202 description: "The defined property MUST be greater than or equal to the given value."
203 type: ["integer","number"]
204 exclusiveMinimum:
205 description: "The defined property MUST be strictly greater than the given value; it cannot be equal."
206 type: ["integer","number"]
207 maxLength:
208 description: |-
209 The defined property is a string that MUST have a length that is less than or equal to the given integer.
210 (The length of the string is the number of individual Unicode characters it is composed of.)
211 type: "integer"
212 minimum: 0
213 minLength:
214 description: |-
215 The defined property is a string that MUST have a length that is less than or equal to the given integer.
216 (The length of the string is the number of individual Unicode characters it is composed of.)
217 type: "integer"
218 minimum: 0
219 format:
220 description: |-
221 Choose one of the following values to indicate that the defined property is a string that MUST adhere to the specified format:
222 - "date-time": the date-time production in RFC 3339 section 5.6.
223 - "date": the full-date production in RFC 3339 section 5.6.
224 - "time": the full-time production in RFC 3339 section 5.6.
225 - "duration": the duration production in RFC 3339 Appendix A.
226 - "email": the "Mailbox" ABNF rule in RFC 5321 section 4.1.2.
227 - "uri": a string instance is valid against this attribute if it is a valid URI according to RFC 3986.
228 - "iri": a string instance is valid against this attribute if it is a valid IRI according to RFC 3987.
229 type: "string"
230 enum: ["date-time", "date", "time", "duration", "email", "uri", "iri"]
231 "$id":
232 allOf:
233 - $ref: '#/$defs/id_field'
234 - description: |-
235 A static IRI identifier that is a URN or URL representing the specific version of this level of the defined property.
236 (If it is a URL, clients SHOULD NOT assign any interpretation to the response when resolving that URL.)
237 It SHOULD NOT be changed as long as the property definition remains the same, and SHOULD be changed when the property definition changes.
238 Property Definitions SHOULD be regarded as the same if they only differ by:
239 - The inclusion or omission of "null" in the type in the outermost layer of the definition.
240 - Additions of annotating notes to end of the description field.
241 - Changes to the following specific fields at any level: deprecated, examples, $comment, x-optimade-implementation, and x-optimade-requirements.
242 "$schema":
243 description: |-
244 A normalized URI for a meta-schema that validates the Property Definition.
245 This SHOULD be https://schemas.optimade.org/meta/{OPTIMADE_VERSION}/optimade/physical_unit_definition.json
246 title:
247 description: |-
248 A short single-line human-readable explanation of the defined property appropriate to show as part of a user interface.
249 type: string
250 description:
251 description: |-
252 A human-readable multi-line description that explains the purpose, requirements, and conventions of the defined property.
253 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.
254 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/>.
255 When possible, it is preferable for mathematical expressions to use as straightforward notation as possible to make them readable also when not rendered.
256
257 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.
258 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.
259 The purpose is to provide a way to add explanations and clarifications to a definition without having to regard it as a new definition.
260 For example, these annotations to the description MAY be used to explain why a definition has been deprecated.
261 type: string
262 x-optimade-definition:
263 $$inherit: "/v1.2/optimade/x-optimade-definition-field"
264 label: "property_definition_meta"
265 kind: "meta"
266 version: "1.2.1"
267 format: "1.2"
268 name: "property_definition"
269 x-optimade-dimensions:
270 description: |-
271 Specification of the dimensions of one or multi-dimensional data represented as multiple levels of lists.
272 Each dimension is given a name and optionally a fixed size.
273 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.
274 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.
275 type: object
276 additionalProperties: false
277 patternProperties:
278 "^x-(?!optimade-)": {}
279 properties:
280 names:
281 description: |-
282 A list of names of the dimensions of the underlying one or multi-dimensionsional data represented as mutiple levels of lists.
283 The order is that the first name applies to the outermost list, the next name to the lists embedded in that list, etc.
284 type: array
285 items:
286 type: string
287 sizes:
288 description: |-
289 A list of fixed length requirements on the underlying one or multi-dimensionsional data represented as mutiple levels of lists.
290 The order is that the first name applies to the outermost list, the next name to the lists embedded in that list, etc.
291 The data only validates if the respective level consists of lists of exactly this length.
292 A value of `null` allows arbitrary-length lists at the corresponding level.
293 type: array
294 items:
295 type:
296 - "integer"
297 - "null"
298 x-optimade-unit-definitions:
299 type: array
300 items:
301 allOf:
302 - $ref: "#/$defs/unit_entity_definition_field"
303 - required: ['title', 'symbol', 'display-symbol', 'description']
304 x-optimade-type:
305 type: string
306 pattern: "^(string|integer|float|boolean|timestamp|list|dictionary|_\\S+_\\S+)$"
307 x-optimade-unit:
308 type: string
309 x-optimade-implementation:
310 additionalProperties: false
311 patternProperties:
312 "^x-(?!optimade-)": {}
313 properties:
314 query-support:
315 enum:
316 - all mandatory
317 - equality only
318 - partial
319 - none
320 type: string
321 query-support-operators:
322 items:
323 enum:
324 - '<'
325 - '<='
326 - '>'
327 - '>='
328 - '='
329 - '!='
330 - 'CONTAINS'
331 - 'STARTS WITH'
332 - 'ENDS WITH'
333 - 'HAS'
334 - 'HAS ALL'
335 - 'HAS ANY'
336 - 'HAS ONLY'
337 - 'IS KNOWN'
338 - 'IS UNKNOWN'
339 type: string
340 type: array
341 response-level:
342 enum:
343 - "always"
344 - "yes"
345 - "no"
346 sortable:
347 type: boolean
348 "$comment":
349 type: string
350 type: object
351 x-optimade-requirements:
352 additionalProperties: false
353 patternProperties:
354 "^x-(?!optimade-)": {}
355 properties:
356 query-support:
357 enum:
358 - all mandatory
359 - equality only
360 - partial
361 - none
362 type: string
363 query-support-operators:
364 items:
365 enum:
366 - '<'
367 - '<='
368 - '>'
369 - '>='
370 - '='
371 - '!='
372 - 'CONTAINS'
373 - 'STARTS WITH'
374 - 'ENDS WITH'
375 - 'HAS'
376 - 'HAS ALL'
377 - 'HAS ANY'
378 - 'HAS ONLY'
379 - 'IS KNOWN'
380 - 'IS UNKNOWN'
381 type: string
382 type: array
383 response-level:
384 enum:
385 - always
386 - must
387 - should
388 - may
389 - should not
390 - must not
391 type: string
392 sortable:
393 type: boolean
394 support:
395 enum:
396 - must
397 - should
398 - may
399 type: string
400 "$comment":
401 type: string
402 type: object
403 x-optimade-metadata-definition:
404 description: |-
405 A dictionary that is a property definition of a dictionary-type property that defines all metadata properties.
406 allOf:
407 - $ref: '#/$defs/property_definition_field'
408 - properties:
409 type:
410 enum:
411 - ["object", "null"]
412 "$comment":
413 description: |-
414 A human-readable comment relevant in the context of the raw definition data.
415 These comments should normally not be shown to the end users.
416 Comments pertaining to the Property Definition that are relevant to end users should go into the field description.
417 Formatting in the text SHOULD use Markdown using the format described in the definition of the description field.
418
419 This field is an annotation rather than an integral part of the Property Definition.
420 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.
421 type: string
422 deprecated:
423 description: |-
424 If TRUE, implementations SHOULD not use the defined property, and it MAY be removed in the future.
425 If FALSE, the defined property is not deprecated. The field not being present means FALSE.
426
427 This field is an annotation rather than an integral part of the Property Definition.
428 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.
429 type: boolean
430 # Allow database-specific fields
431 additionalProperties: false
432 patternProperties:
433 "^x-(?!optimade-)": {}