Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Changes to property definitions #457

Merged
merged 6 commits into from
Feb 21, 2023
Merged

Changes to property definitions #457

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
e9933ae
Change property definitions uri to and add x-optimade-type
rartino Feb 20, 2023
b8ff13f
Update property definitions description of to match introduction of x…
rartino Feb 20, 2023
9bd23d6
Minor language fixes from review
rartino Feb 20, 2023
0274def
Fix missing commas, etc.
rartino Feb 21, 2023
83d9aee
Fix propery definitions example formatting, commas
rartino Feb 21, 2023
673d311
Clarify the meaning of a list value in the property definition type f…
rartino Feb 21, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 53 additions & 39 deletions optimade.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1181,7 +1181,9 @@ Example (note: the description strings have been wrapped for readability only):
"description": "a structures entry",
"properties": {
"nelements": {
"$id": "urn:uuid:10a05e55-0c20-4f68-89ad-35a18eb7076f",
"title": "Number of elements",
"x-optimade-type": "integer",
"type": ["integer", "null"],
"description": "Number of different elements in the structure as an integer.\n
\n
Expand All @@ -1192,7 +1194,7 @@ Example (note: the description strings have been wrapped for readability only):
3
],
"x-optimade-property": {
"property-uri": "urn:uuid:10a05e55-0c20-4f68-89ad-35a18eb7076f",
"property-format": "1.2"
},
"x-optimade-unit": "dimensionless",
"x-optimade-implementation": {
Expand All @@ -1206,7 +1208,9 @@ Example (note: the description strings have been wrapped for readability only):
}
},
"lattice_vectors": {
"$id": "urn:uuid:81edf372-7b1b-4518-9c14-7d482bd67834",
"title": "Unit cell lattice vectors",
"x-optimade-type": "list",
"type": ["array", "null"],
"description": "The three lattice vectors in Cartesian coordinates, in ångström (Å).\n
\n
Expand All @@ -1218,7 +1222,7 @@ Example (note: the description strings have been wrapped for readability only):
],
"x-optimade-unit": "inapplicable",
"x-optimade-property": {
"property-uri": "urn:uuid:81edf372-7b1b-4518-9c14-7d482bd67834",
"property-format": "1.2",
"unit-definitions": [
{
"symbol": "angstrom",
Expand All @@ -1231,7 +1235,7 @@ Example (note: the description strings have been wrapped for readability only):
}
}
]
}
},
"x-optimade-implementation": {
"sortable": false,
"query-support": "none"
Expand All @@ -1240,26 +1244,28 @@ Example (note: the description strings have been wrapped for readability only):
"support": "should",
"sortable": false,
"query-support": "none"
}
"maxItems": 3
"minItems": 3
},
"maxItems": 3,
"minItems": 3,
"items": {
"type": "array",
"x-optimade-unit": "inapplicable",
"maxItems": 3
"minItems": 3
"items": {
"type": "number",
"x-optimade-unit": "angstrom",
"x-optimade-implementation": {
"sortable": true,
"query-support": "none"
},
"x-optimade-requirements": {
"sortable": false,
"query-support": "none"
}
}
"type": "array",
"x-optimade-type": "list",
"x-optimade-unit": "inapplicable",
"maxItems": 3,
"minItems": 3,
"items": {
"type": "number",
"x-optimade-type": "float",
"x-optimade-unit": "angstrom",
"x-optimade-implementation": {
"sortable": true,
"query-support": "none"
},
"x-optimade-requirements": {
"sortable": false,
"query-support": "none"
}
}
}
}
// ... <other property descriptions>
Expand Down Expand Up @@ -1823,7 +1829,7 @@ A Property Definition MUST be composed according to the combination of the requi

**REQUIRED keys for the outermost level of the Property Definition:**

- :field:`title`: String and :field:`description`: String.
- :field:`$id`: String, :field:`title`: String, and :field:`description`: String.
See the subsection `Property definition keys from JSON Schema`_ for the definitions of these fields.
They are defined in that subsection as OPTIONAL on any level of the Property Definition, but are REQUIRED on the outermost level.

Expand All @@ -1840,11 +1846,6 @@ A Property Definition MUST be composed according to the combination of the requi
A client MUST disregard the property definition if the field is not a string of the format MAJOR.MINOR or if the MAJOR version number is unrecognized.
This field allows future versions of this standard to support implementations keeping definitions that adhere to older versions of the property definition format.

- :field:`property-uri`: String.
A static URI identifier that is a URN or URL representing the specific version of the property.
It SHOULD NOT be changed as long as the property definition remains the same, and SHOULD be changed when the property definition changes.
(If it is a URL, clients SHOULD NOT assign any interpretation to the response when resolving that URL.)

**OPTIONAL keys:**

- :field:`version`: String.
Expand All @@ -1870,6 +1871,10 @@ A Property Definition MUST be composed according to the combination of the requi

**REQUIRED keys for all levels of the Property Definition:**

- :field:`x-optimade-type`: String
Specifies the OPTIMADE data type for this level of the defined property.
MUST be one of :val:`"string"`, :val:`"integer"`, :val:`"float"`, :val:`"boolean"`, :val:`"timestamp"`, :val:`"list"`, or :val:`"dictionary"`.

- :field:`x-optimade-unit`: String.
A (compound) symbol for the physical unit in which the value of the defined property is given or one of the strings :val:`dimensionless` or :val:`inapplicable`.
See subsection `Physical Units in Property Definitions`_ for the details on how compound units are represented in OPTIMADE Property Definitions and the precise format of this string.
Expand Down Expand Up @@ -1941,33 +1946,42 @@ The format described in this subsection forms a subset of the `JSON Schema Valid
**REQUIRED keys**

- :field:`type`: String or List.
The string or list specifies the type of the defined property.
It MUST be one of:
Specifies the corresponding JSON type for this level of the defined property and whether the property can be :val:`null` or not.
The value is directly correlated with :field:`x-optimade-type` as explained below.

- One of the strings :val:`"boolean"`, :val:`"object"` (refers to an OPTIMADE dictionary), :val:`"array"` (refers to an OPTIMADE list), :val:`"number"` (refers to an OPTIMADE float), :val:`"string"`, or :val:`"integer"`.
- A list where the first item MUST be one of the strings above, and the second item MUST be the string :val:`"null"`.
It MUST be one of:

For OPTIMADE data types not covered above:
- A string correlated with :field:`x-optimade-type` as follows.
If :field:`x-optimade-type` is:

- timestamps are represented by setting the :field:`type` field to :val:`"string"` and the :field:`format` field to :val:`"date-time"`.
In this case it is MANDATORY to include the field :field:`format`.
* :val:`"boolean"`, `"string"`, or `"integer"` then :field:`type` is the same string.
* :val:`"dictionary"` then :field:`type` is `"object"`.
* :val:`"list"` then :field:`type` is `"array"`.
* :val:`"float"` then :field:`type` is `"number"`.
* :val:`"timestamp"` then :field:`type` is `"string"`.

Output formats that represent these OPTIMADE data types in other ways have to recognize them and reinterpret the definition accordingly.
- A list where the first item MUST be the string described above (correlated to the field :field:`x-optimade-type` in the same way) and the second item MUST be the string :val:`"null"`.
This form specifies that the defined property can be :val:`null`.

..

Implementation notes:

- The strings used in the :field:`type` field are JSON type names encoded as strings, but they refer to the corresponding OPTIMADE data types.
Nevertheless, for consistency across formats, the JSON type names MUST be used regardless of the standard type names of the output format.
The motivation for this design decision is that it makes the JSON representation of a Property Definition a fully valid standard JSON Schema.
- The field :field:`type` can be derived from the field :field:`x-optimade-type` and its role is only to provide the JSON type names corresponding to :field:`x-optimade-type`.
The motivation to include these type names is that it makes the JSON representation of a Property Definition a fully valid standard JSON Schema.
Nevertheless, for consistency across formats, these JSON type names MUST still be included when a property definition is represented in other output formats (i.e., the JSON names MUST NOT be translated into the type names of that output format).

- The allowed values of the :field:`type` field are highly restricted compared to what is permitted using the full JSON Schema standard.
Values can only be defined to be a single OPTIMADE data type or, optionally, :val:`null`.
This restriction is intended to reduce the complexity of possible data types that implementations have to handle in different formats and database backends.

**OPTIONAL keys**

- :field:`$id`: String.
A static URI identifier that is a URN or URL representing the specific version of this level of the defined property.
It SHOULD NOT be changed as long as the property definition remains the same, and SHOULD be changed when the property definition changes.
(If it is a URL, clients SHOULD NOT assign any interpretation to the response when resolving that URL.)

- :field:`title`: String.
A short single-line human-readable explanation of the defined property appropriate to show as part of a user interface.

Expand Down