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

Final formatting fixes #511

Merged
merged 3 commits into from
Apr 4, 2024
Merged

Final formatting fixes #511

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
98cc4a0
Remove erroneously escaped underscores inside rst roles
ml-evs Apr 4, 2024
b6d6950
Fix indentation level of some blocks
ml-evs Apr 4, 2024
48f8ed2
Change some single backtick quotes. (#513)
vaitkus Apr 4, 2024
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
88 changes: 44 additions & 44 deletions optimade.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1040,7 +1040,7 @@ The API implementation MAY provide other entry types than the ones standardized
Such entry types MUST be prefixed by a database-provider-specific prefix (i.e., the resource objects' :property:`type` value should start with the database-provider-specific prefix, e.g., :property:`type` = :val:`_exmpl_workflows`).
Each custom entry type SHOULD be served at a corresponding entry listing endpoint under the versioned or unversioned base URL that serves the API with the same name (i.e., equal to the resource objects' :property:`type` value, e.g., :endpoint:`/_exmpl_workflows`).
It is RECOMMENDED to align with the OPTIMADE API specification practice of using a plural for entry resource types and entry type endpoints.
Any custom entry listing endpoint MUST also be added to the :property:`available\_endpoints` and :property:`entry\_types\_by\_format` attributes of the `Base Info Endpoint`_.
Any custom entry listing endpoint MUST also be added to the :property:`available_endpoints` and :property:`entry_types_by_format` attributes of the `Base Info Endpoint`_.

For more on custom endpoints, see `Custom Extension Endpoints`_.

Expand Down Expand Up @@ -1125,7 +1125,7 @@ Examples:

- :query-url:`http://example.com/optimade/v1/structures?_exmpl_key=A3242DSFJFEJE`
- :query-url:`http://example.com/optimade/v1/structures?_exmpl_warning_verbosity=10`
- :query-url:`http://example.com/optimade/v1/structures?\_exmpl\_filter="elements all in [Al, Si, Ga]"`
- :query-url:`http://example.com/optimade/v1/structures?_exmpl_filter="elements all in [Al, Si, Ga]"`

**Note**: the specification presently makes no attempt to standardize access control mechanisms.
There are security concerns with access control based on URL tokens, and the above example is not to be taken as a recommendation for such a mechanism.
Expand Down Expand Up @@ -2109,48 +2109,48 @@ A Property Definition MUST be composed according to the combination of the requi

.. _definition of the property-format field:

- :field:`format`: String.
A string that declares the OPTIMADE definition format the definition adheres to.
Currently, this is expressed as the minor version of the OPTIMADE specification that describes the property definition format used.
The string MUST be of the format "MAJOR.MINOR", referring to the version of the OPTIMADE standard that describes the format in which this property definition is expressed.
The version number string MUST NOT be prefixed by, e.g., "v".
In implementations of the present version of the standard, the value MUST be exactly :field-val:`1.2`.
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:`format`: String.
A string that declares the OPTIMADE definition format the definition adheres to.
Currently, this is expressed as the minor version of the OPTIMADE specification that describes the property definition format used.
The string MUST be of the format "MAJOR.MINOR", referring to the version of the OPTIMADE standard that describes the format in which this property definition is expressed.
The version number string MUST NOT be prefixed by, e.g., "v".
In implementations of the present version of the standard, the value MUST be exactly :field-val:`1.2`.
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:`kind`: String.
A string specifying what entity is being defined.
For Property Definitions this MUST be the string "property".
- :field:`kind`: String.
A string specifying what entity is being defined.
For Property Definitions this MUST be the string "property".

- :field:`name`: String.
An short identifier (as defined in `Definition of Terms`_) that provides a reasonable short non-unique name for the entity being defined.
- :field:`name`: String.
An short identifier (as defined in `Definition of Terms`_) that provides a reasonable short non-unique name for the entity being defined.

- :field:`label`: String.
An extended identifier (as defined in `Definition of Terms`_) that describes the entity being defined in a way that is unique within a set of definitions provided together.
The label SHOULD start with the name.
- :field:`label`: String.
An extended identifier (as defined in `Definition of Terms`_) that describes the entity being defined in a way that is unique within a set of definitions provided together.
The label SHOULD start with the name.

Implementation notes:
Implementation notes:

The name and label fields ensure implementations will be able to give meaningful names to definitions if they are translated into other formats with various requirements on human-readable names, e.g., as `RDF data <https://www.w3.org/TR/rdf-schema/>`__ (see, e.g., rdfs:label).
The name and label fields ensure implementations will be able to give meaningful names to definitions if they are translated into other formats with various requirements on human-readable names, e.g., as `RDF data <https://www.w3.org/TR/rdf-schema/>`__ (see, e.g., rdfs:label).

**OPTIONAL keys:**
**OPTIONAL keys:**

- :field:`version`: String.
This string indicates the version of the definition.
The string SHOULD be in the format described by the `semantic versioning v2 <https://semver.org/spec/v2.0.0.html>`__ standard.
When a definition is changed in a way that consitutes a redefinition it SHOULD indicate this by incrementing the MAJOR version number.
- :field:`version`: String.
This string indicates the version of the definition.
The string SHOULD be in the format described by the `semantic versioning v2 <https://semver.org/spec/v2.0.0.html>`__ standard.
When a definition is changed in a way that consitutes a redefinition it SHOULD indicate this by incrementing the MAJOR version number.

- :field:`resources`: List.
A list of dictionaries that references remote resources that describe the property.
The format of each dictionary is:
- :field:`resources`: List.
A list of dictionaries that references remote resources that describe the property.
The format of each dictionary is:

**REQUIRED keys:**
**REQUIRED keys:**

- :field:`relation`: String.
A human-readable description of the relationship between the property and the remote resource, e.g., a "natural language description".
- :field:`relation`: String.
A human-readable description of the relationship between the property and the remote resource, e.g., a "natural language description".

- :field:`resource-id`: String.
An IRI of the external resource, which MAY be a resolvable URL.
- :field:`resource-id`: String.
An IRI of the external resource, which MAY be a resolvable URL.

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

Expand Down Expand Up @@ -2181,15 +2181,15 @@ A Property Definition MUST be composed according to the combination of the requi

**REQUIRED keys:**

- :field:`names`: List of Strings.
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 the first name applies to the outermost list, the next name to the lists embedded in that list, etc.
- :field:`names`: List of Strings.
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 the first name applies to the outermost list, the next name to the lists embedded in that list, etc.

- :field:`sizes`: List of Integers or :val:`null`.
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 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.
- :field:`sizes`: List of Integers or :val:`null`.
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 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.

Note: OPTIMADE Property Definitions use this field, and MUST NOT use the JSON Schema validating fields minItems and maxItems since that would require reprocessing the schema to handle requests using the OPTIMADE features that requests partial data in lists.
Instead, the length of lists can be validated against the length information provided in the :field:`sizes` subfield of :field:`x-optimade-dimensions` (which, at this time, can only specify a fixed length requirement.)
Expand Down Expand Up @@ -3154,7 +3154,7 @@ space\_group\_symmetry\_operations\_xyz
- Space group operations for the space group with ITC number 3 (H-M symbol :val:`P 2`, extended H-M symbol :val:`P 1 2 1`, Hall symbol :val:`P 2y`): :val:`["x,y,z", "-x,y,-z"]`
- Space group operations for the space group with ITC number 5 (H-M symbol :val:`C 2`, extended H-M symbol :val:`C 1 2 1`, Hall symbol :val:`C 2y`): :val:`["x,y,z", "-x,y,-z", "x+1/2,y+1/2,z", "-x+1/2,y+1/2,-z"]`

- **Notes:** The list of space group symmetry operations applies to the whole periodic array of atoms and together with the lattice translations given in the :property:`lattice\_vectors` property provides the necessary information to reconstruct all atom site positions of the periodic material.
- **Notes:** The list of space group symmetry operations applies to the whole periodic array of atoms and together with the lattice translations given in the :property:`lattice_vectors` property provides the necessary information to reconstruct all atom site positions of the periodic material.
Thus, the symmetry operations described in this property are only applicable to material models with at least one periodic dimension.
This property is not meant to represent arbitrary symmetries of molecules, non-periodic (finite) collections of atoms or non-crystallographic symmetry.

Expand Down Expand Up @@ -3240,7 +3240,7 @@ space\_group\_symbol\_hermann\_mauguin\_extended
- The change-of-basis operation SHOULD be provided for the non-standard axis and cell choices.
- The extended H-M symbol does not unambiguously communicate the origin choice, and the given symbol SHOULD NOT be amended to convey this information.
- The description of the change-of-basis SHOULD follow conventions of the ITC Vol. B, Sect. 1.4, Appendix A1.4.2 (IUCr, 2001).
- The same character string encoding conventions MUST be used as for the specification of the :property:`space\_group\_symbol\_hermann\_mauguin` property.
- The same character string encoding conventions MUST be used as for the specification of the :property:`space_group_symbol_hermann_mauguin` property.

- **Examples**:

Expand Down Expand Up @@ -4095,7 +4095,7 @@ The strings below contain Extended Regular Expressions (EREs) to recognize ident
The Symmetry Operation String Regular Expressions
-------------------------------------------------

Symmetry operation strings that comprise the :property:`space\_group\_symmetry\_operations\_xyz` property MUST conform to the following regular expressions.
Symmetry operation strings that comprise the :property:`space_group_symmetry_operations_xyz` property MUST conform to the following regular expressions.
The regular expressions are recorded below in two forms, one in a more readable form using variables and the other as an explicit pattern compatible with the `OPTIMADE Regular Expression Format`_.

- Perl Compatible Regular Expression (PCRE) syntax, with `Perl extensions <https://perldoc.perl.org/perlre>`__ used for readability and expressivity.
Expand Down
Loading