$schema: "https://json-schema.org/draft/2020-12/schema" $id: "https://schemas.optimade.org/meta/v1.3/optimade/property_definition" title: "OPTIMADE property definition schema" type: object allOf: - $ref: "#/$defs/property_definition_field" - required: ["$id", "$schema", "title", "description", "x-optimade-definition"] $$inherit: "/v1.2/optimade/physical_unit_definition" $defs: id_field: $$inherit: "/v1.2/common/id_field" property_definition_field: required: ["type", "x-optimade-type", "x-optimade-unit"] anyOf: - type: object required: ["properties"] properties: type: enum: [["object"],["object", "null"]] enum: type: "array" items: type: "object" examples: type: "array" items: type: "object" - type: object required: ["type", "items"] properties: type: enum: [["array"],["array", "null"]] enum: type: "array" items: type: "array" examples: type: "array" items: type: "array" - type: object required: ["type"] properties: type: enum: [["integer"],["integer", "null"]] multipleOf: type: "integer" maximum: type: "integer" exclusiveMaximum: type: "integer" minimum: type: "integer" exclusiveMinimum: type: "integer" enum: type: "array" items: type: "integer" examples: type: "array" items: type: "integer" - type: object required: ["type"] properties: type: enum: [["number"],["number", "null"]] multipleOf: type: "number" maximum: type: "number" exclusiveMaximum: type: "number" minimum: type: "number" exclusiveMinimum: type: "number" enum: type: "array" items: type: "number" examples: type: "array" items: type: "number" - type: object required: ["type"] properties: type: enum: [["string"],["string", "null"]] enum: type: "array" items: type: "string" examples: type: "array" items: type: "string" - type: object required: ["type"] properties: type: enum: [["boolean"],["boolean", "null"]] enum: type: "array" items: type: "boolean" examples: type: "array" items: type: "boolean" properties: type: description: |- Specifies the corresponding JSON type for this level of the defined property and whether the property can be `null` or not. The value is directly correlated with `x-optimade-type` (cf. the `definition of the x-optimade-type field`). 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: * `"boolean"`, `"string"`, or `"integer"` then `type` is the same string. * `"dictionary"` then `type` is `"object"`. * `"list"` then `type` is `"array"`. * `"float"` then `type` is `"number"`. * `"timestamp"` then `type` is `"string"`. * provider-specific data type, then `type` is the JSON type used as a carrier for this data type. If the second element is included, it MUST be the string `"null"`. This two element form specifies that the defined property can be `null`. type: array enum: [["object"],["object", "null"],["array"],["array", "null"],["integer"],["integer", "null"],["number"],["number", "null"],["string"],["string", "null"],["boolean"],["boolean", "null"]] items: type: string properties: description: |- Gives key-value pairs where each value is an inner Property Definition. 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. (Or, if the type field is the list "object" and "null", it can also be null.) type: object additionalProperties: $ref: '#/$defs/property_definition_field' required: description: |- The defined property MUST have keys that match all the strings in this list. Other keys present in the properties field are OPTIONAL in the defined property. If not present or empty, all keys in properties are regarded as OPTIONAL. type: "array" items: type: string uniqueItems: true maxProperties: description: |- The defined property is a dictionary where the number of keys MUST be less than or equal to the number given. type: "integer" minimum: 0 minProperties: description: |- The defined property is a dictionary where the number of keys MUST be greater than or equal to the number given. type: "integer" minimum: 0 dependentRequired: description: |- The dictionary keys are strings and the values are lists of unique strings. 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. No restriction is inferred from this field for keys in the defined property that do not match any key in the given dictionary. type: "object" additionalProperties: type: "array" items: type: "string" uniqueItems: true enum: description: "The defined property MUST take one of the values given in the provided list." type: "array" items: $comment: "Must validate against the Property Definition itself, but there is no easy way to express that in the schema." examples: description: "A list of example values that the defined property can have." type: "array" items: $comment: "Must validate against the Property Definition itself, but there is no easy way to express that in the schema." items: allOf: - $ref: '#/$defs/property_definition_field' - description: |- The defined property is a list where each item MUST match this inner Property Definition. uniqueItems: 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." type: "boolean" multipleOf: description: |- An integer is strictly greater than 0. 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). type: ["integer", "number"] exclusiveMinimum: 0 maximum: description: "The defined property MUST be less than or equal to the given value." type: ["integer","number"] exclusiveMaximum: description: "The defined property MUST be strictly less than the given value; it cannot be equal." type: ["integer","number"] minimum: description: "The defined property MUST be greater than or equal to the given value." type: ["integer","number"] exclusiveMinimum: description: "The defined property MUST be strictly greater than the given value; it cannot be equal." type: ["integer","number"] maxLength: description: |- The defined property is a string that MUST have a length that is less than or equal to the given integer. (The length of the string is the number of individual Unicode characters it is composed of.) type: "integer" minimum: 0 minLength: description: |- The defined property is a string that MUST have a length that is less than or equal to the given integer. (The length of the string is the number of individual Unicode characters it is composed of.) type: "integer" minimum: 0 format: description: |- Choose one of the following values to indicate that the defined property is a string that MUST adhere to the specified format: - "date-time": the date-time production in RFC 3339 section 5.6. - "date": the full-date production in RFC 3339 section 5.6. - "time": the full-time production in RFC 3339 section 5.6. - "duration": the duration production in RFC 3339 Appendix A. - "email": the "Mailbox" ABNF rule in RFC 5321 section 4.1.2. - "uri": a string instance is valid against this attribute if it is a valid URI according to RFC 3986. - "iri": a string instance is valid against this attribute if it is a valid IRI according to RFC 3987. type: "string" enum: ["date-time", "date", "time", "duration", "email", "uri", "iri"] "$id": allOf: - $ref: '#/$defs/id_field' - description: |- A static IRI identifier that is a URN or URL representing the specific version of this level of the defined property. (If it is a URL, clients SHOULD NOT assign any interpretation to the response when resolving that URL.) It SHOULD NOT be changed as long as the property definition remains the same, and SHOULD be changed when the property definition changes. Property Definitions SHOULD be regarded as the same if they only differ by: - The inclusion or omission of "null" in the type in the outermost layer of the definition. - Additions of annotating notes to end of the description field. - Changes to the following specific fields at any level: deprecated, examples, $comment, x-optimade-implementation, and x-optimade-requirements. "$schema": description: |- A normalized URI for a meta-schema that validates the Property Definition. This SHOULD be https://schemas.optimade.org/meta/{OPTIMADE_VERSION}/optimade/physical_unit_definition.json title: description: |- A short single-line human-readable explanation of the defined property appropriate to show as part of a user interface. type: string description: description: |- A human-readable multi-line description that explains the purpose, requirements, and conventions of the defined property. 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. 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 . When possible, it is preferable for mathematical expressions to use as straightforward notation as possible to make them readable also when not rendered. 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. 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. The purpose is to provide a way to add explanations and clarifications to a definition without having to regard it as a new definition. For example, these annotations to the description MAY be used to explain why a definition has been deprecated. type: string x-optimade-definition: $$inherit: "/v1.2/optimade/x-optimade-definition-field" label: "property_definition_meta" kind: "meta" version: "1.2.1" format: "1.2" name: "property_definition" x-optimade-dimensions: description: |- Specification of the dimensions of one or multi-dimensional data represented as multiple levels of lists. Each dimension is given a name and optionally a fixed size. 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. 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. type: object additionalProperties: false patternProperties: "^x-(?!optimade-)": {} properties: names: description: |- A list of names of the dimensions of the underlying one or multi-dimensionsional data represented as mutiple levels of lists. The order is that the first name applies to the outermost list, the next name to the lists embedded in that list, etc. type: array items: type: string sizes: description: |- A list of fixed length requirements on the underlying one or multi-dimensionsional data represented as mutiple levels of lists. The order is that the first name applies to the outermost list, the next name to the lists embedded in that list, etc. The data only validates if the respective level consists of lists of exactly this length. A value of `null` allows arbitrary-length lists at the corresponding level. type: array items: type: - "integer" - "null" x-optimade-unit-definitions: type: array items: allOf: - $ref: "#/$defs/unit_entity_definition_field" - required: ['title', 'symbol', 'display-symbol', 'description'] x-optimade-type: type: string pattern: "^(string|integer|float|boolean|timestamp|list|dictionary|_\\S+_\\S+)$" x-optimade-unit: type: string x-optimade-implementation: additionalProperties: false patternProperties: "^x-(?!optimade-)": {} properties: query-support: enum: - all mandatory - equality only - partial - none type: string query-support-operators: items: enum: - '<' - '<=' - '>' - '>=' - '=' - '!=' - 'CONTAINS' - 'STARTS WITH' - 'ENDS WITH' - 'HAS' - 'HAS ALL' - 'HAS ANY' - 'HAS ONLY' - 'IS KNOWN' - 'IS UNKNOWN' type: string type: array response-level: enum: - "always" - "yes" - "no" sortable: type: boolean "$comment": type: string type: object x-optimade-requirements: additionalProperties: false patternProperties: "^x-(?!optimade-)": {} properties: query-support: enum: - all mandatory - equality only - partial - none type: string query-support-operators: items: enum: - '<' - '<=' - '>' - '>=' - '=' - '!=' - 'CONTAINS' - 'STARTS WITH' - 'ENDS WITH' - 'HAS' - 'HAS ALL' - 'HAS ANY' - 'HAS ONLY' - 'IS KNOWN' - 'IS UNKNOWN' type: string type: array response-level: enum: - always - must - should - may - should not - must not type: string sortable: type: boolean support: enum: - must - should - may type: string "$comment": type: string type: object x-optimade-metadata-definition: description: |- A dictionary that is a property definition of a dictionary-type property that defines all metadata properties. allOf: - $ref: '#/$defs/property_definition_field' - properties: type: enum: - ["object", "null"] "$comment": description: |- A human-readable comment relevant in the context of the raw definition data. These comments should normally not be shown to the end users. Comments pertaining to the Property Definition that are relevant to end users should go into the field description. Formatting in the text SHOULD use Markdown using the format described in the definition of the description field. This field is an annotation rather than an integral part of the Property Definition. 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. type: string deprecated: description: |- If TRUE, implementations SHOULD not use the defined property, and it MAY be removed in the future. If FALSE, the defined property is not deprecated. The field not being present means FALSE. This field is an annotation rather than an integral part of the Property Definition. 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. type: boolean # Allow database-specific fields additionalProperties: false patternProperties: "^x-(?!optimade-)": {}