fekad/property_definition.rst

## property_definition.rst

      
    Raw
  

              property_definition.rst
            
          
Info Endpoints

Entry Listing Info Endpoints

Entry listing info endpoints are accessed under the versioned or unversioned base URL serving the API as /info/<entry_type> (e.g., http://example.com/optimade/v1/info/structures or http://example.com/optimade/info/structures). The response for these endpoints MUST include the following information in the data field:

description: Description of the entry.
properties: A dictionary describing properties for this entry type, where each key is a property name and the value is an OPTIMADE Property Definition described in detail below Property Definitions.
formats: List of output formats available for this type of entry.
output_fields_by_format: Dictionary of available output fields for this entry type, where the keys are the values of the formats list and the values are the keys of the properties dictionary.

Example (note: the description string has been wrapped for readability only):
{
  "data": {
    "description": "a structures entry",
    "properties": {
      "nelements": {
        "type": ["integer", "null"],
        "title": "Number of elements",
        "description": "Number of different elements in the structure as an integer. \n
        \n
          -  Note: queries on this property can equivalently be formulated using `elements LENGTH`.\n
          -  A filter that matches structures that have exactly 4 elements: `nelements=4`.\n
          -  A filter that matches structures that have between 2 and 7 elements: `nelements>=2 AND nelements<=7`.",
        "examples": [
          3
        ],
        "x-optimade-support": {
          "sortable": true,
          "support": "should",
          "queryable": "full"
        }
      },
      "lattice_vectors": {
        "title": "Unit cell lattice vectors",
        "description": "The three lattice vectors in Cartesian coordinates, in ångström (Å).\n
        ...",
        "x-optimade-property": {
          "unit": {
            symbol: "angstrom"
          }
        },
        "x-optimade-support": {
          "sortable": false,
          "support": "should",
          "queryable": "full"
        },
        "type": "array",

        // ... <further fields defining lattice_vectors>
      }
      // ... <other property descriptions>
    },
    "formats": ["json", "xml"],
    "output_fields_by_format": {
      "json": [
        "nelements",
        "lattice_vectors",
        // ...
      ],
      "xml": ["nelements"]
    }
  }
  // ...
}
Property Definitions

The property definition uses a dictionary-based construct that strictly follows a subset of the JSON Schema Validation Draft 2020-12 and JSON Schema Core Draft 2020-12 standards. The motivation for this design decision is that it makes the JSON representation of a Property Definition a fully valid standard JSON Schema meanwhile these restrictions are intended to reduce the complexity of possible data types that implementations have to handle in different formats and database backends. While these standards are JSON-based, the dictionary construct can be realized in any format capable of representing the basic OPTIMADE data types. Hence, the field definitions below are given in terms of OPTIMADE data types, and the implementation maps these to the corresponding data types for the output format in which the property definition is expressed, as described in detail in the appendix Property Definitions. Nevertheless, for consistency across formats, the JSON type names MUST be used regardless of the standard type names of the output format.
An OPTIMADE Property Definition defines a specific property, which will be referred to as the defined property.
A Property Definition is a dictionary that has the following format:
REQUIRED keys:

type: String or List. The string or list specifies the type of the defined property. The list where the first item MUST be one of the strings below, and the second item MUST be the string "null". The strings are JSON type names encoded as strings, but they technically refer to the corresponding OPTIMADE data types as described in detail in the appendix Property Definitions.
For specific types addition keys are REQUIRED:

REQUIRED keys for Property Definitions where the type field includes "object":

properties: Dictionary. Each key in the given dictionary provides a nested inner Property Definition. The value of each corresponding key in the defined property MUST adhere to this definition. The defined property MUST only contain keys present in this dictionary.

REQUIRED keys for Property Definitions where the type field includes "array":

items: List. A nested inner Property Definition. The defined property is an array where all items MUST match the given Property Definition.


The type specific OPTIONAL keys are described in detail in the appendix Property Definitions.

OPTIONAL keys:

title: String. A short single-line human-readable name for the defined property appropriate to show as part of a user interface.
description: String. 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.
examples: List. A list of example values that the defined property can have. These examples MUST all be of a data type that matches the type field and otherwise adhere to the rest of the Property Description.
x-optimade-property: Dictionary. A dictionary of OPTIMADE-specific information about the defined property (i.e., the JSON Schema standard does not define these fields). The dictionary could contain the following OPTIONAL keys:
OPTIONAL keys:

uri: String. A URI that SHOULD resolve to a JSON response that contains the present Property Definition. The format of the response MUST be that of an OPTIMADE Entry Listing Info Endpoint, except the only mandatory keys are data with the subfield properties, but the response MAY contain other fields. This format makes it possible for a Property Definition in an Entry Listing Info endpoint to set x-optimade-property-uri as a link back to the same Info endpoint. However, the field MAY also link to a resource external from the implementation to clarify to clients that a property used in several databases represents the same thing.
unit: Dictionary. If the unit field is omitted the value is interpreted as unitless e.g., a string representing a chemical formula or an integer counting the number of atoms in the unit cell. The unit field is a dictionary that has the following format:
REQUIRED keys:

symbol: String. The string is a (compound) symbol for the physical unit in which the value of the defined property is given, if it uses a unit. The default set of unit symbols for OPTIMADE are taken from version 3.09 unit database definition.units from GNU units software. If the unit is available in this database, or if it can be expressed as a compound unit expression using these units, the value of unit SHOULD be set to the corresponding (compound) string symbol and no further definition be given. See subsection Compound Units Expression in Property Definitions for the details on how compound units are represented in OPTIMADE Property Definitions and the precise format of this string.
If a (compound) symbol based on the GNU units database is not used, the string in unit MUST be defined in the unit-definition field inside the x-optimade-property field of the Property Definition.

OPTIONAL keys:

uri: String. This field is a (unique) URI that can be used as a reference to the unit definition.
description: String. A human-readable multiple-line description of the unit.
standard: Dictionary. This field is used to define the unit symbol using a preexisting standard. The dictionary has the following format:
REQUIRED keys:

name: String. The abbreviated name of the standard being referenced. One of the following:

"gnu": the symbol comes from unit database definition.units from GNU units software.
"ucum": the symbol comes from The Unified Code for Units of Measure (UCUM) standard.
"qudt": the symbol comes from the QUDT standard. Not only symbols strictly defined within the QUDT standard are allowed, but also other symbols constructed by following the scheme for how new unit symbols are formed in this standard.

version: String. The version string of the referenced standard.

resources: List. A list of dictionaries that references remote resources that describe the unit. The format of each dictionary is:
REQUIRED keys:

relation: String. A human-readable description of the relationship between the unit and the remote resource, e.g., a "natural language description".
uri: String. A URI of the external resource.


resources: List. A list of dictionaries that references remote resources that describe the property. The format of each dictionary is:
REQUIRED keys:

relation: String. A human-readable description the relationship between the property and the remote resource, e.g., "natural language description".
uri: String. A URI of the external resource.


x-optimade-support: Dictionary. A dictionary of OPTIMADE-specific information about the defined property (i.e., the JSON Schema standard does not define these fields). The dictionary has the following format:

support: String The string MUST be one of the following:

"must": the defined property MUST be recognized by the implementation (e.g., in filter strings) and MUST not be null.
"should", the defined property MUST be recognized by the implementation (e.g., in filter strings) and SHOULD not be null.
"may": the defined property MAY not be recognized by the implementation and MAY be equal to null.

Note: the specification in this field of whether the defined property can be null or not MUST match the value of the type field outside of x-optimade-property. If null values are allowed, that field must be a list where the string "null" is the second element.
deprecated: Boolean. 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.
queryable: String. The string MUST be one of the following:

"full": the defined property MUST be queryable using the OPTIMADE filter language with support for all mandatory filter features.
"partial:only full string": the defined property is a string that MUST be queryable using the OPTIMADE filter language. However, support for the partial string matching operators are OPTIONAL (i.e., the operators BEGINS WITH, ENDS WITH, and CONTAINS).
"partial": the defined property MUST be queryable, but the support MAY be restricted to any subset of the filter language operators and features. The level of support is described in the field query-description.
"none": the defined property MAY not be queryable at all.

query-description: String. This string is a human-readable multi-line text that describes the limitations of support of the OPTIMADE filter language. It SHOULD only be given if the field queryable is set to the string "partial". Formatting in the text SHOULD use Markdown in the CommonMark v3.0 format.
sortable: Boolean. If TRUE, specifies that results can be sorted on this property (see Entry Listing URL Query Parameters for more information on this field). If FALSE, specifies that results cannot be sorted on this property. The field not being included means the same as FALSE.


Appendix

Mapping between OPTIMADE data types and Property Definitions data types


dictionary: "object"
list: "array"
string: "string"
boolean: "boolean"
integer: "integer"
float: "number"
timestamp: "string" with the "date-time" value in its format field.

The OPTIONAL keys for specific data types of Property Definitions


"object":

:field:`required`: List. The list MUST only contain strings. 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.
:field:`maxProperties`: Integer. The defined property is a dictionary where the number of keys MUST be less than or equal to the number given.
:field:`minProperties`: Integer. The defined property is a dictionary where the number of keys MUST be greater than or equal to the number given.
:field:`dependentRequired`: Dictionary. 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 matches 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.

"array":

maxItems: Integer. A non-negative integer. The defined property is an array that MUST contain a number of items that is less than or equal to the given integer.
minItems: Integer. A non-negative integer. The defined property is an array that MUST contain a number of items that is greater than or equal to the given integer.
uniqueItems: Boolean. 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.

"integer":

multipleOf: Integer. An integer is strictly greater than 0. The defined property MUST have an integer value that when divided by the given integer results in an integer (i.e., it must be even divisible by this integer without a fractional part).
maximum: Integer. The defined property is an integer that MUST be less than or equal to this number.
exclusiveMaximum: Integer. The defined property is an integer that MUST be strictly less than this number; it cannot equal the number.
minimum: Integer. The defined property is an integer that MUST be greater than or equal to this number.
exclusiveMinimum: Integer. The defined property is an integer that MUST be strictly greater than this number; it cannot equal the number.

"number":

:field:`maximum`: Float. The defined property is a float that MUST be less than or equal to this number.
:field:`exclusiveMaximum`: Float. The defined property is a float that MUST be strictly less than this number; it cannot equal the number.
:field:`minimum`: Float. The defined property is a float that MUST be greater than or equal to this number.
:field:`exclusiveMinimum`: Float. The defined property is a float that MUST be strictly greater than this number; it cannot equal the number.

"string":

:field:`maxLength`: Integer. A non-negative integer. 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 defined according to RFC 8259.
:field:`minLength`: Integer. A non-negative integer. 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 defined according to RFC 8259.
:field:`enum`: List. The defined property MUST take one of the values given in the provided list. The items in the list MUST all be of a data type that matches the type field and otherwise adhere to the rest of the Property Description. If this key is given, for null to be a valid value of the defined property, the list MUST contain a null value and the type MUST be a list where the second value is the string "null".
:field:`pattern`: String. The defined property MUST adhere to the format as specified by the given string when interpreted as a regular expression according to the ECMA-262 regular expression dialect.
:field:`format`: String. 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": the extended "Mailbox" ABNF rule in RFC 6531, section 3.3.


Compound Units Expression in Property Definitions

Compound unit expressions are created by combining unit symbols defined in the GNU units database, optionally prefixed by one or more of the prefixes defined in the database (indicated thereby trailing -), multiplication *, division /, and power ^ directly followed by a positive integer. Furthermore:

No whitespace, parenthesis, or other symbols than specified above are permitted.
If multiple string representations of the same unit exist in definition.units, the first one in that file consisting of only lowercase letter and underscore characters SHOULD be used.
The unit symbols MUST appear in alphabetical order.
Consecutive divisions, e.g., a/b/c are interpreted separately, i.e., b and c are both interpreted to be to the power of -1.