From ea2009ba001019b5bf3c1d0cb2ac5dfac9acbfd3 Mon Sep 17 00:00:00 2001 From: Matthew Evans Date: Tue, 6 Dec 2022 19:29:20 +0000 Subject: [PATCH 01/19] Add `space_group_hall` and `space_group_it_number` to structure model --- openapi/openapi.json | 28 ++++++++++++++++++++------ optimade/models/structures.py | 38 ++++++++++++++++++++++++++++++++++- 2 files changed, 59 insertions(+), 7 deletions(-) diff --git a/openapi/openapi.json b/openapi/openapi.json index 918a2965c..969507aa2 100644 --- a/openapi/openapi.json +++ b/openapi/openapi.json @@ -3359,9 +3359,9 @@ "type": "number" }, "description": "If present MUST be a list of floats expressed in a.m.u.\nElements denoting vacancies MUST have masses equal to 0.", + "x-optimade-unit": "a.m.u.", "x-optimade-queryable": "optional", - "x-optimade-support": "optional", - "x-optimade-unit": "a.m.u." + "x-optimade-support": "optional" }, "original_name": { "title": "Original Name", @@ -3639,9 +3639,25 @@ }, "description": "The three lattice vectors in Cartesian coordinates, in \u00e5ngstr\u00f6m (\u00c5).\n\n- **Type**: list of list of floats or unknown values.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - MUST be a list of three vectors *a*, *b*, and *c*, where each of the vectors MUST BE a list of the vector's coordinates along the x, y, and z Cartesian coordinates.\n (Therefore, the first index runs over the three lattice vectors and the second index runs over the x, y, z Cartesian coordinates).\n - For databases that do not define an absolute Cartesian system (e.g., only defining the length and angles between vectors), the first lattice vector SHOULD be set along *x* and the second on the *xy*-plane.\n - MUST always contain three vectors of three coordinates each, independently of the elements of property `dimension_types`.\n The vectors SHOULD by convention be chosen so the determinant of the `lattice_vectors` matrix is different from zero.\n The vectors in the non-periodic directions have no significance beyond fulfilling these requirements.\n - The coordinates of the lattice vectors of non-periodic dimensions (i.e., those dimensions for which `dimension_types` is `0`) MAY be given as a list of all `null` values.\n If a lattice vector contains the value `null`, all coordinates of that lattice vector MUST be `null`.\n\n- **Examples**:\n - `[[4.0,0.0,0.0],[0.0,4.0,0.0],[0.0,1.0,4.0]]` represents a cell, where the first vector is `(4, 0, 0)`, i.e., a vector aligned along the `x` axis of length 4 \u00c5; the second vector is `(0, 4, 0)`; and the third vector is `(0, 1, 4)`.", "nullable": true, + "x-optimade-unit": "\u00c5", + "x-optimade-queryable": "optional", + "x-optimade-support": "should" + }, + "space_group_hall": { + "title": "Space Group Hall", + "type": "string", + "description": "A Hall space group symbol representing the symmetry of the structure as defined in Hall, S. R. (1981), Acta Cryst. A37, 517-525 and erratum (1981), A37, 921.\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - Each component of the Hall symbol MUST be separated by a single space symbol.\n - If there exists a standard Hall symbol which represents the symmetry it SHOULD be used.\n - MUST be null if `nperiodic_dimensions` is not equal to 3.", "x-optimade-queryable": "optional", - "x-optimade-support": "should", - "x-optimade-unit": "\u00c5" + "x-optimade-support": "optional" + }, + "space_group_it_number": { + "title": "Space Group It Number", + "maximum": 230.0, + "minimum": 1.0, + "type": "integer", + "description": "Space group number for the structure assigned by the International Tables for Crystallography Vol. A.\n- **Type**: integer\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - The integer value MUST be between 1 and 230.\n - MUST be null if `nperiodic_dimensions` is not equal to 3.", + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "cartesian_site_positions": { "title": "Cartesian Site Positions", @@ -3656,9 +3672,9 @@ }, "description": "Cartesian positions of each site in the structure.\nA site is usually used to describe positions of atoms; what atoms can be encountered at a given site is conveyed by the `species_at_sites` property, and the species themselves are described in the `species` property.\n\n- **Type**: list of list of floats\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - It MUST be a list of length equal to the number of sites in the structure, where every element is a list of the three Cartesian coordinates of a site expressed as float values in the unit angstrom (\u00c5).\n - An entry MAY have multiple sites at the same Cartesian position (for a relevant use of this, see e.g., the property `assemblies`).\n\n- **Examples**:\n - `[[0,0,0],[0,0,2]]` indicates a structure with two sites, one sitting at the origin and one along the (positive) *z*-axis, 2 \u00c5 away from the origin.", "nullable": true, + "x-optimade-unit": "\u00c5", "x-optimade-queryable": "optional", - "x-optimade-support": "should", - "x-optimade-unit": "\u00c5" + "x-optimade-support": "should" }, "nsites": { "title": "Nsites", diff --git a/optimade/models/structures.py b/optimade/models/structures.py index c9424254b..1ac456ae4 100644 --- a/optimade/models/structures.py +++ b/optimade/models/structures.py @@ -7,7 +7,7 @@ from functools import reduce from typing import List, Optional, Union -from pydantic import BaseModel, conlist, root_validator, validator +from pydantic import BaseModel, conint, conlist, root_validator, validator from optimade.models.entries import EntryResource, EntryResourceAttributes from optimade.models.utils import ( @@ -525,6 +525,36 @@ class StructureResourceAttributes(EntryResourceAttributes): queryable=SupportLevel.OPTIONAL, ) + space_group_hall: Optional[str] = OptimadeField( + None, + description="""A Hall space group symbol representing the symmetry of the structure as defined in Hall, S. R. (1981), Acta Cryst. A37, 517-525 and erratum (1981), A37, 921. + +- **Type**: string + +- **Requirements/Conventions**: + - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`. + - **Query**: Support for queries on this property is OPTIONAL. + - Each component of the Hall symbol MUST be separated by a single space symbol. + - If there exists a standard Hall symbol which represents the symmetry it SHOULD be used. + - MUST be null if `nperiodic_dimensions` is not equal to 3.""", + support=SupportLevel.OPTIONAL, + queryable=SupportLevel.OPTIONAL, + ) + + space_group_it_number: Optional[conint(ge=1, le=230)] = OptimadeField( # type: ignore[valid-type] + None, + description="""Space group number for the structure assigned by the International Tables for Crystallography Vol. A. +- **Type**: integer + +- **Requirements/Conventions**: + - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`. + - **Query**: Support for queries on this property is OPTIONAL. + - The integer value MUST be between 1 and 230. + - MUST be null if `nperiodic_dimensions` is not equal to 3.""", + support=SupportLevel.OPTIONAL, + queryable=SupportLevel.OPTIONAL, + ) + cartesian_site_positions: Optional[List[Vector3D]] = OptimadeField( # type: ignore[valid-type] ..., description="""Cartesian positions of each site in the structure. @@ -950,6 +980,12 @@ def check_periodic_dimensions(cls, v, values): return v + @validator("space_group_hall", "space_group_it_number") + def check_space_group_vs_nperiodic_dimensions(cls, v, values, field): + if v is not None and values.get("nperiodic_dimensions", 3) != 3: + raise ValueError(f"{field.name} provided but `nperiodic_dimensions!=3`") + return v + @validator("lattice_vectors", always=True) def required_if_dimension_types_has_one(cls, v, values): if v is None: From 4b64b9a2a91fcf8a2759cff02cdb64f343cad5c7 Mon Sep 17 00:00:00 2001 From: Matthew Evans Date: Wed, 20 Dec 2023 13:56:01 +0000 Subject: [PATCH 02/19] Add new space group fields and outline tests --- openapi/index_openapi.json | 20 +-- openapi/openapi.json | 291 ++++++++++++++++++---------------- optimade/models/structures.py | 91 ++++++++++- optimade/models/utils.py | 6 + tests/models/test_utils.py | 10 ++ 5 files changed, 270 insertions(+), 148 deletions(-) diff --git a/openapi/index_openapi.json b/openapi/index_openapi.json index 62c29ef4a..337e33d09 100644 --- a/openapi/index_openapi.json +++ b/openapi/index_openapi.json @@ -498,15 +498,15 @@ "type": "string", "title": "Id", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "type": { "type": "string", "title": "Type", "description": "The name of the type of an entry.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - MUST be an existing entry type.\n - The entry of type `` and ID `` MUST be returned in response to a request for `//` under the versioned base URL.\n\n- **Example**: `\"structures\"`", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "links": { "allOf": [ @@ -560,16 +560,16 @@ "type": "string", "title": "Immutable Id", "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", - "x-optimade-support": "optional", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "optional" }, "last_modified": { "type": "string", "format": "date-time", "title": "Last Modified", "description": "Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n - As part of JSON response format: `\"2007-04-05T14:30:20Z\"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)", - "x-optimade-support": "should", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "should" } }, "type": "object", @@ -1107,8 +1107,8 @@ "type": "string", "title": "Id", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "type": { "type": "string", diff --git a/openapi/openapi.json b/openapi/openapi.json index 3854de21e..db5e5d79b 100644 --- a/openapi/openapi.json +++ b/openapi/openapi.json @@ -1335,8 +1335,8 @@ "type": "array", "title": "Sites In Groups", "description": "Index of the sites (0-based) that belong to each group for each assembly.\n\n- **Examples**:\n - `[[1], [2]]`: two groups, one with the second site, one with the third.\n - `[[1,2], [3]]`: one group with the second and third site, one with the fourth.", - "x-optimade-support": "must", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "must" }, "group_probabilities": { "items": { @@ -1345,8 +1345,8 @@ "type": "array", "title": "Group Probabilities", "description": "Statistical probability of each group. It MUST have the same length as `sites_in_groups`.\nIt SHOULD sum to one.\nSee below for examples of how to specify the probability of the occurrence of a vacancy.\nThe possible reasons for the values not to sum to one are the same as already specified above for the `concentration` of each `species`.", - "x-optimade-support": "must", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "must" } }, "type": "object", @@ -1748,15 +1748,15 @@ "type": "string", "title": "Id", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "type": { "type": "string", "title": "Type", "description": "The name of the type of an entry.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - MUST be an existing entry type.\n - The entry of type `` and ID `` MUST be returned in response to a request for `//` under the versioned base URL.\n\n- **Example**: `\"structures\"`", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "links": { "allOf": [ @@ -1810,16 +1810,16 @@ "type": "string", "title": "Immutable Id", "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", - "x-optimade-support": "optional", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "optional" }, "last_modified": { "type": "string", "format": "date-time", "title": "Last Modified", "description": "Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n - As part of JSON response format: `\"2007-04-05T14:30:20Z\"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)", - "x-optimade-support": "should", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "should" } }, "type": "object", @@ -2216,8 +2216,8 @@ "type": "string", "title": "Id", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "type": { "type": "string", @@ -2517,22 +2517,22 @@ "type": "string", "title": "Name", "description": "Full name of the person, REQUIRED.", - "x-optimade-support": "must", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "must" }, "firstname": { "type": "string", "title": "Firstname", "description": "First name of the person.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "lastname": { "type": "string", "title": "Lastname", "description": "Last name of the person.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" } }, "type": "object", @@ -2632,8 +2632,8 @@ "type": "string", "title": "Id", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "type": { "type": "string", @@ -2641,8 +2641,8 @@ "title": "Type", "description": "The name of the type of an entry.\n- **Type**: string.\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - MUST be an existing entry type.\n - The entry of type and ID MUST be returned in response to a request for `//` under the versioned base URL.\n- **Example**: `\"structures\"`", "default": "references", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "links": { "allOf": [ @@ -2690,16 +2690,16 @@ "type": "string", "title": "Immutable Id", "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", - "x-optimade-support": "optional", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "optional" }, "last_modified": { "type": "string", "format": "date-time", "title": "Last Modified", "description": "Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n - As part of JSON response format: `\"2007-04-05T14:30:20Z\"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)", - "x-optimade-support": "should", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "should" }, "authors": { "items": { @@ -2708,8 +2708,8 @@ "type": "array", "title": "Authors", "description": "List of person objects containing the authors of the reference.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "editors": { "items": { @@ -2718,15 +2718,15 @@ "type": "array", "title": "Editors", "description": "List of person objects containing the editors of the reference.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "doi": { "type": "string", "title": "Doi", "description": "The digital object identifier of the reference.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "url": { "type": "string", @@ -2735,162 +2735,162 @@ "format": "uri", "title": "Url", "description": "The URL of the reference.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "address": { "type": "string", "title": "Address", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "annote": { "type": "string", "title": "Annote", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "booktitle": { "type": "string", "title": "Booktitle", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "chapter": { "type": "string", "title": "Chapter", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "crossref": { "type": "string", "title": "Crossref", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "edition": { "type": "string", "title": "Edition", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "howpublished": { "type": "string", "title": "Howpublished", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "institution": { "type": "string", "title": "Institution", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "journal": { "type": "string", "title": "Journal", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "key": { "type": "string", "title": "Key", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "month": { "type": "string", "title": "Month", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "note": { "type": "string", "title": "Note", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "number": { "type": "string", "title": "Number", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "organization": { "type": "string", "title": "Organization", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "pages": { "type": "string", "title": "Pages", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "publisher": { "type": "string", "title": "Publisher", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "school": { "type": "string", "title": "School", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "series": { "type": "string", "title": "Series", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "title": { "type": "string", "title": "Title", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "bib_type": { "type": "string", "title": "Bib Type", "description": "Type of the reference, corresponding to the **type** property in the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "volume": { "type": "string", "title": "Volume", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "year": { "type": "string", "title": "Year", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" } }, "type": "object", @@ -3310,8 +3310,8 @@ "type": "string", "title": "Name", "description": "Gives the name of the species; the **name** value MUST be unique in the `species` list.", - "x-optimade-support": "must", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "must" }, "chemical_symbols": { "items": { @@ -3320,8 +3320,8 @@ "type": "array", "title": "Chemical Symbols", "description": "MUST be a list of strings of all chemical elements composing this species. Each item of the list MUST be one of the following:\n\n- a valid chemical-element symbol, or\n- the special value `\"X\"` to represent a non-chemical element, or\n- the special value `\"vacancy\"` to represent that this site has a non-zero probability of having a vacancy (the respective probability is indicated in the `concentration` list, see below).\n\nIf any one entry in the `species` list has a `chemical_symbols` list that is longer than 1 element, the correct flag MUST be set in the list `structure_features`.", - "x-optimade-support": "must", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "must" }, "concentration": { "items": { @@ -3330,8 +3330,8 @@ "type": "array", "title": "Concentration", "description": "MUST be a list of floats, with same length as `chemical_symbols`. The numbers represent the relative concentration of the corresponding chemical symbol in this species. The numbers SHOULD sum to one. Cases in which the numbers do not sum to one typically fall only in the following two categories:\n\n- Numerical errors when representing float numbers in fixed precision, e.g. for two chemical symbols with concentrations `1/3` and `2/3`, the concentration might look something like `[0.33333333333, 0.66666666666]`. If the client is aware that the sum is not one because of numerical precision, it can renormalize the values so that the sum is exactly one.\n- Experimental errors in the data present in the database. In this case, it is the responsibility of the client to decide how to process the data.\n\nNote that concentrations are uncorrelated between different site (even of the same species).", - "x-optimade-support": "must", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "must" }, "mass": { "items": { @@ -3340,16 +3340,16 @@ "type": "array", "title": "Mass", "description": "If present MUST be a list of floats expressed in a.m.u.\nElements denoting vacancies MUST have masses equal to 0.", - "x-optimade-unit": "a.m.u.", "x-optimade-queryable": "optional", + "x-optimade-unit": "a.m.u.", "x-optimade-support": "optional" }, "original_name": { "type": "string", "title": "Original Name", "description": "Can be any valid Unicode string, and SHOULD contain (if specified) the name of the species that is used internally in the source database.\n\nNote: With regards to \"source database\", we refer to the immediate source being queried via the OPTIMADE API implementation.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "attached": { "items": { @@ -3358,8 +3358,8 @@ "type": "array", "title": "Attached", "description": "If provided MUST be a list of length 1 or more of strings of chemical symbols for the elements attached to this site, or \"X\" for a non-chemical element.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "nattached": { "items": { @@ -3368,8 +3368,8 @@ "type": "array", "title": "Nattached", "description": "If provided MUST be a list of length 1 or more of integers indicating the number of attached atoms of the kind specified in the value of the :field:`attached` key.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" } }, "type": "object", @@ -3438,8 +3438,8 @@ "type": "string", "title": "Id", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "type": { "type": "string", @@ -3447,8 +3447,8 @@ "title": "Type", "description": "The name of the type of an entry.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - MUST be an existing entry type.\n - The entry of type `` and ID `` MUST be returned in response to a request for `//` under the versioned base URL.\n\n- **Examples**:\n - `\"structures\"`", "default": "structures", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "links": { "allOf": [ @@ -3496,17 +3496,17 @@ "type": "string", "title": "Immutable Id", "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", - "x-optimade-support": "optional", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "optional" }, "last_modified": { "type": "string", "format": "date-time", "title": "Last Modified", "description": "Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n - As part of JSON response format: `\"2007-04-05T14:30:20Z\"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)", - "x-optimade-support": "should", + "nullable": true, "x-optimade-queryable": "must", - "nullable": true + "x-optimade-support": "should" }, "elements": { "items": { @@ -3515,17 +3515,17 @@ "type": "array", "title": "Elements", "description": "The chemical symbols of the different elements present in the structure.\n\n- **Type**: list of strings.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - The strings are the chemical symbols, i.e., either a single uppercase letter or an uppercase letter followed by a number of lowercase letters.\n - The order MUST be alphabetical.\n - MUST refer to the same elements in the same order, and therefore be of the same length, as `elements_ratios`, if the latter is provided.\n - Note: This property SHOULD NOT contain the string \"X\" to indicate non-chemical elements or \"vacancy\" to indicate vacancies (in contrast to the field `chemical_symbols` for the `species` property).\n\n- **Examples**:\n - `[\"Si\"]`\n - `[\"Al\",\"O\",\"Si\"]`\n\n- **Query examples**:\n - A filter that matches all records of structures that contain Si, Al **and** O, and possibly other elements: `elements HAS ALL \"Si\", \"Al\", \"O\"`.\n - To match structures with exactly these three elements, use `elements HAS ALL \"Si\", \"Al\", \"O\" AND elements LENGTH 3`.\n - Note: length queries on this property can be equivalently formulated by filtering on the `nelements`_ property directly.", - "x-optimade-support": "should", + "nullable": true, "x-optimade-queryable": "must", - "nullable": true + "x-optimade-support": "should" }, "nelements": { "type": "integer", "title": "Nelements", "description": "Number of different elements in the structure as an integer.\n\n- **Type**: integer\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - MUST be equal to the lengths of the list properties `elements` and `elements_ratios`, if they are provided.\n\n- **Examples**:\n - `3`\n\n- **Querying**:\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`.", - "x-optimade-support": "should", + "nullable": true, "x-optimade-queryable": "must", - "nullable": true + "x-optimade-support": "should" }, "elements_ratios": { "items": { @@ -3534,43 +3534,43 @@ "type": "array", "title": "Elements Ratios", "description": "Relative proportions of different elements in the structure.\n\n- **Type**: list of floats\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - Composed by the proportions of elements in the structure as a list of floating point numbers.\n - The sum of the numbers MUST be 1.0 (within floating point accuracy)\n - MUST refer to the same elements in the same order, and therefore be of the same length, as `elements`, if the latter is provided.\n\n- **Examples**:\n - `[1.0]`\n - `[0.3333333333333333, 0.2222222222222222, 0.4444444444444444]`\n\n- **Query examples**:\n - Note: Useful filters can be formulated using the set operator syntax for correlated values.\n However, since the values are floating point values, the use of equality comparisons is generally inadvisable.\n - OPTIONAL: a filter that matches structures where approximately 1/3 of the atoms in the structure are the element Al is: `elements:elements_ratios HAS ALL \"Al\":>0.3333, \"Al\":<0.3334`.", - "x-optimade-support": "should", + "nullable": true, "x-optimade-queryable": "must", - "nullable": true + "x-optimade-support": "should" }, "chemical_formula_descriptive": { "type": "string", "title": "Chemical Formula Descriptive", "description": "The chemical formula for a structure as a string in a form chosen by the API implementation.\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - The chemical formula is given as a string consisting of properly capitalized element symbols followed by integers or decimal numbers, balanced parentheses, square, and curly brackets `(`,`)`, `[`,`]`, `{`, `}`, commas, the `+`, `-`, `:` and `=` symbols. The parentheses are allowed to be followed by a number. Spaces are allowed anywhere except within chemical symbols. The order of elements and any groupings indicated by parentheses or brackets are chosen freely by the API implementation.\n - The string SHOULD be arithmetically consistent with the element ratios in the `chemical_formula_reduced` property.\n - It is RECOMMENDED, but not mandatory, that symbols, parentheses and brackets, if used, are used with the meanings prescribed by [IUPAC's Nomenclature of Organic Chemistry](https://www.qmul.ac.uk/sbcs/iupac/bibliog/blue.html).\n\n- **Examples**:\n - `\"(H2O)2 Na\"`\n - `\"NaCl\"`\n - `\"CaCO3\"`\n - `\"CCaO3\"`\n - `\"(CH3)3N+ - [CH2]2-OH = Me3N+ - CH2 - CH2OH\"`\n\n- **Query examples**:\n - Note: the free-form nature of this property is likely to make queries on it across different databases inconsistent.\n - A filter that matches an exactly given formula: `chemical_formula_descriptive=\"(H2O)2 Na\"`.\n - A filter that does a partial match: `chemical_formula_descriptive CONTAINS \"H2O\"`.", - "x-optimade-support": "should", + "nullable": true, "x-optimade-queryable": "must", - "nullable": true + "x-optimade-support": "should" }, "chemical_formula_reduced": { "type": "string", "pattern": "(^$)|^([A-Z][a-z]?([2-9]|[1-9]\\d+)?)+$", "title": "Chemical Formula Reduced", "description": "The reduced chemical formula for a structure as a string with element symbols and integer chemical proportion numbers.\nThe proportion number MUST be omitted if it is 1.\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property.\n However, support for filters using partial string matching with this property is OPTIONAL (i.e., BEGINS WITH, ENDS WITH, and CONTAINS).\n Intricate queries on formula components are instead suggested to be formulated using set-type filter operators on the multi valued `elements` and `elements_ratios` properties.\n - Element symbols MUST have proper capitalization (e.g., `\"Si\"`, not `\"SI\"` for \"silicon\").\n - Elements MUST be placed in alphabetical order, followed by their integer chemical proportion number.\n - For structures with no partial occupation, the chemical proportion numbers are the smallest integers for which the chemical proportion is exactly correct.\n - For structures with partial occupation, the chemical proportion numbers are integers that within reasonable approximation indicate the correct chemical proportions. The precise details of how to perform the rounding is chosen by the API implementation.\n - No spaces or separators are allowed.\n\n- **Examples**:\n - `\"H2NaO\"`\n - `\"ClNa\"`\n - `\"CCaO3\"`\n\n- **Query examples**:\n - A filter that matches an exactly given formula is `chemical_formula_reduced=\"H2NaO\"`.", - "x-optimade-support": "should", + "nullable": true, "x-optimade-queryable": "must", - "nullable": true + "x-optimade-support": "should" }, "chemical_formula_hill": { "type": "string", "pattern": "(^$)|^([A-Z][a-z]?([2-9]|[1-9]\\d+)?)+$", "title": "Chemical Formula Hill", "description": "The chemical formula for a structure in [Hill form](https://dx.doi.org/10.1021/ja02046a005) with element symbols followed by integer chemical proportion numbers. The proportion number MUST be omitted if it is 1.\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, only a subset of the filter features MAY be supported.\n - The overall scale factor of the chemical proportions is chosen such that the resulting values are integers that indicate the most chemically relevant unit of which the system is composed.\n For example, if the structure is a repeating unit cell with four hydrogens and four oxygens that represents two hydroperoxide molecules, `chemical_formula_hill` is `\"H2O2\"` (i.e., not `\"HO\"`, nor `\"H4O4\"`).\n - If the chemical insight needed to ascribe a Hill formula to the system is not present, the property MUST be handled as unset.\n - Element symbols MUST have proper capitalization (e.g., `\"Si\"`, not `\"SI\"` for \"silicon\").\n - Elements MUST be placed in [Hill order](https://dx.doi.org/10.1021/ja02046a005), followed by their integer chemical proportion number.\n Hill order means: if carbon is present, it is placed first, and if also present, hydrogen is placed second.\n After that, all other elements are ordered alphabetically.\n If carbon is not present, all elements are ordered alphabetically.\n - If the system has sites with partial occupation and the total occupations of each element do not all sum up to integers, then the Hill formula SHOULD be handled as unset.\n - No spaces or separators are allowed.\n\n- **Examples**:\n - `\"H2O2\"`\n\n- **Query examples**:\n - A filter that matches an exactly given formula is `chemical_formula_hill=\"H2O2\"`.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "chemical_formula_anonymous": { "type": "string", "pattern": "(^$)|^([A-Z][a-z]?([2-9]|[1-9]\\d+)?)+$", "title": "Chemical Formula Anonymous", "description": "The anonymous formula is the `chemical_formula_reduced`, but where the elements are instead first ordered by their chemical proportion number, and then, in order left to right, replaced by anonymous symbols A, B, C, ..., Z, Aa, Ba, ..., Za, Ab, Bb, ... and so on.\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property.\n However, support for filters using partial string matching with this property is OPTIONAL (i.e., BEGINS WITH, ENDS WITH, and CONTAINS).\n\n- **Examples**:\n - `\"A2B\"`\n - `\"A42B42C16D12E10F9G5\"`\n\n- **Querying**:\n - A filter that matches an exactly given formula is `chemical_formula_anonymous=\"A2B\"`.", - "x-optimade-support": "should", + "nullable": true, "x-optimade-queryable": "must", - "nullable": true + "x-optimade-support": "should" }, "dimension_types": { "items": { @@ -3581,17 +3581,17 @@ "minItems": 3, "title": "Dimension Types", "description": "List of three integers.\nFor each of the three directions indicated by the three lattice vectors (see property `lattice_vectors`), this list indicates if the direction is periodic (value `1`) or non-periodic (value `0`).\nNote: the elements in this list each refer to the direction of the corresponding entry in `lattice_vectors` and *not* the Cartesian x, y, z directions.\n\n- **Type**: list of integers.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - MUST be a list of length 3.\n - Each integer element MUST assume only the value 0 or 1.\n\n- **Examples**:\n - For a molecule: `[0, 0, 0]`\n - For a wire along the direction specified by the third lattice vector: `[0, 0, 1]`\n - For a 2D surface/slab, periodic on the plane defined by the first and third lattice vectors: `[1, 0, 1]`\n - For a bulk 3D system: `[1, 1, 1]`", - "x-optimade-support": "should", "x-optimade-queryable": "optional", + "x-optimade-support": "should", "nullable": true }, "nperiodic_dimensions": { "type": "integer", "title": "Nperiodic Dimensions", "description": "An integer specifying the number of periodic dimensions in the structure, equivalent to the number of non-zero entries in `dimension_types`.\n\n- **Type**: integer\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - The integer value MUST be between 0 and 3 inclusive and MUST be equal to the sum of the items in the `dimension_types` property.\n - This property only reflects the treatment of the lattice vectors provided for the structure, and not any physical interpretation of the dimensionality of its contents.\n\n- **Examples**:\n - `2` should be indicated in cases where `dimension_types` is any of `[1, 1, 0]`, `[1, 0, 1]`, `[0, 1, 1]`.\n\n- **Query examples**:\n - Match only structures with exactly 3 periodic dimensions: `nperiodic_dimensions=3`\n - Match all structures with 2 or fewer periodic dimensions: `nperiodic_dimensions<=2`", - "x-optimade-support": "should", + "nullable": true, "x-optimade-queryable": "must", - "nullable": true + "x-optimade-support": "should" }, "lattice_vectors": { "items": { @@ -3607,23 +3607,42 @@ "minItems": 3, "title": "Lattice Vectors", "description": "The three lattice vectors in Cartesian coordinates, in \u00e5ngstr\u00f6m (\u00c5).\n\n- **Type**: list of list of floats or unknown values.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - MUST be a list of three vectors *a*, *b*, and *c*, where each of the vectors MUST BE a list of the vector's coordinates along the x, y, and z Cartesian coordinates.\n (Therefore, the first index runs over the three lattice vectors and the second index runs over the x, y, z Cartesian coordinates).\n - For databases that do not define an absolute Cartesian system (e.g., only defining the length and angles between vectors), the first lattice vector SHOULD be set along *x* and the second on the *xy*-plane.\n - MUST always contain three vectors of three coordinates each, independently of the elements of property `dimension_types`.\n The vectors SHOULD by convention be chosen so the determinant of the `lattice_vectors` matrix is different from zero.\n The vectors in the non-periodic directions have no significance beyond fulfilling these requirements.\n - The coordinates of the lattice vectors of non-periodic dimensions (i.e., those dimensions for which `dimension_types` is `0`) MAY be given as a list of all `null` values.\n If a lattice vector contains the value `null`, all coordinates of that lattice vector MUST be `null`.\n\n- **Examples**:\n - `[[4.0,0.0,0.0],[0.0,4.0,0.0],[0.0,1.0,4.0]]` represents a cell, where the first vector is `(4, 0, 0)`, i.e., a vector aligned along the `x` axis of length 4 \u00c5; the second vector is `(0, 4, 0)`; and the third vector is `(0, 1, 4)`.", - "nullable": true, + "x-optimade-queryable": "optional", "x-optimade-unit": "\u00c5", + "x-optimade-support": "should", + "nullable": true + }, + "space_group_symmetry_operations_xyz": { + "items": { + "type": "string", + "pattern": "^([-+]? [xyz] ([-+][xyz])? ([-+] (1/2|[12]/3|[1-3]/4|[1-5]/6) )?|[-+]? (1/2|[12]/3|[1-3]/4|[1-5]/6) ([-+] [xyz] ([-+][xyz])? )?),([-+]? [xyz] ([-+][xyz])? ([-+] (1/2|[12]/3|[1-3]/4|[1-5]/6) )?|[-+]? (1/2|[12]/3|[1-3]/4|[1-5]/6) ([-+] [xyz] ([-+][xyz])? )?),([-+]? [xyz] ([-+][xyz])? ([-+] (1/2|[12]/3|[1-3]/4|[1-5]/6) )?|[-+]? (1/2|[12]/3|[1-3]/4|[1-5]/6) ([-+] [xyz] ([-+][xyz])? )?)$" + }, + "type": "array", + "pattern": "^([-+]? [xyz] ([-+][xyz])? ([-+] (1/2|[12]/3|[1-3]/4|[1-5]/6) )?|[-+]? (1/2|[12]/3|[1-3]/4|[1-5]/6) ([-+] [xyz] ([-+][xyz])? )?),([-+]? [xyz] ([-+][xyz])? ([-+] (1/2|[12]/3|[1-3]/4|[1-5]/6) )?|[-+]? (1/2|[12]/3|[1-3]/4|[1-5]/6) ([-+] [xyz] ([-+][xyz])? )?),([-+]? [xyz] ([-+][xyz])? ([-+] (1/2|[12]/3|[1-3]/4|[1-5]/6) )?|[-+]? (1/2|[12]/3|[1-3]/4|[1-5]/6) ([-+] [xyz] ([-+][xyz])? )?)$", + "title": "Space Group Symmetry Operations Xyz", + "description": "A list of symmetry operations given as general position x, y and z coordinates in algebraic form.\n\nEach symmetry operation is described by a string that gives that symmetry operation in Jones' faithful representation (Bradley & Cracknell, 1972: pp. 35-37), adapted for computer string notation.\nThe letters x, y and z that are typesetted with overbars in printed text represent coordinate values multiplied by -1 and are encoded as -x, -y and -z, respectively.\nThe syntax of the strings representing symmetry operations MUST conform to regular expressions given in appendix The Symmetry Operation String Regular Expressions.\nThe interpretation of the strings MUST follow the conventions of the IUCr CIF core dictionary (IUCr, 2023).\nIn particular, this property MUST explicitly provide all symmetry operations needed to generate all the atoms in the unit cell from the atoms in the asymmetric unit, for the setting used.\nThis symmetry operation set MUST always include the `\"x,y,z\"` identity operation.\nThe symmetry operations are to be applied to fractional atom coordinates.\nIn case only Cartesian coordinates are available, these Cartesian coordinates must be converted to fractional coordinates before the application of the provided symmetry operations.\nIf the symmetry operation list is present, it MUST be compatible with other space group specifications (e.g. the ITC space group number, the Hall symbol, the Hermann-Mauguin symbol) if these are present.\n\n- **Type**: list of strings\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n However, the property is RECOMMENDED if coordinates are returned in a form to which these operations can or must be applied (e.g. fractional atom coordinates of an asymmetric unit).\n Moreover, the property is REQUIRED if symmetry operations are necessary to reconstruct the full model of the material and no other symmetry information (e.g., the Hall symbol) is provided that would allow the user to derive symmetry operations unambiguously.\n - MUST be null if `nperiodic_dimensions` is equal to 0.\n\n- **Examples**:\n - Space group operations for the space group with ITC number 3 (H-M symbol: P 2, extended H-M symbol: P 1 2 1, Hall symbol P 2y):\n ```\n [\"x,y,z\", \"-x,y,-z\"]\n ```\n - Space group operations for the space group with ITC number 5 (H-M symbol C 2, extended H-M symbol: C 1 2 1, Hall symbol C 2y):\n ```\n [\"x,y,z\", \"-x,y,-z\", \"x+1/2,y+1/2,z\", \"-x+1/2,y+1/2,-z\"]\n ```\n\n- **Notes**:\n The list of space group symmetry operations applies to the whole periodic array of atoms and together with the lattice translations given in the `lattice_vectors` property provides the necessary information to reconstruct all atom site positions of the periodic material.\n Thus, the symmetry operations described in this property are only applicable to material models with at least one periodic dimension.\n This property is not meant to represent arbitrary symmetries of molecules, non-periodic (finite) collections of atoms or non-crystallographic symmetry.\n\n- **Bibliographic References**:\n\n Bradley, C. J. and Cracknell, A. P. (1972) The Mathematical Theory of Symmetry in Solids. Oxford, Clarendon Press (paperback edition 2010) 745 p. ISBN 978-0-19-958258-7.\n\n IUCr (2023) Core dictionary (coreCIF) version 2.4.5; data name _space_group_symop_operation_xyz. Available from: https://www.iucr.org/__data/iucr/cifdic_html/1/cif_core.dic/Ispace_group_symop_operation_xyz.html [Accessed 2023-06-18T16:46+03:00].", "x-optimade-queryable": "optional", - "x-optimade-support": "should" + "x-optimade-support": "optional" }, "space_group_hall": { + "type": "string", "title": "Space Group Hall", + "description": "A Hall space group symbol representing the symmetry of the structure as defined in (Hall, 1981, 1981a).\nThe change-of-basis operations are used as defined in the International Tables of Crystallography (ITC) Vol. B, Sect. 1.4, Appendix A1.4.2 (IUCr, 2001).\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - Each component of the Hall symbol MUST be separated by a single space symbol.\n - If there exists a standard Hall symbol which represents the symmetry it SHOULD be used.\n - MUST be null if `nperiodic_dimensions` is not equal to 3.\n\n- **Bibliographic References**:\n\n Hall, S. R. (1981) Space-group notation with an explicit origin. Acta Crystallographica Section A, 37, 517-525, International Union of Crystallography (IUCr), DOI: https://doi.org/10.1107/s0567739481001228\n\n Hall, S. R. (1981a) Space-group notation with an explicit origin; erratum. Acta Crystallographica Section A, 37, 921-921, International Union of Crystallography (IUCr), DOI: https://doi.org/10.1107/s0567739481001976\n\n IUCr (2001). International Tables for Crystallography vol. B. Reciprocal Space. Ed. U. Shmueli. 2-nd edition. Dordrecht/Boston/London, Kluwer Academic Publishers.", + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" + }, + "space_group_symbol_hermann_mauguin": { "type": "string", - "description": "A Hall space group symbol representing the symmetry of the structure as defined in Hall, S. R. (1981), Acta Cryst. A37, 517-525 and erratum (1981), A37, 921.\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - Each component of the Hall symbol MUST be separated by a single space symbol.\n - If there exists a standard Hall symbol which represents the symmetry it SHOULD be used.\n - MUST be null if `nperiodic_dimensions` is not equal to 3.", + "title": "Space Group Symbol Hermann Mauguin", + "description": "A human- and machine-readable string containing the short Hermann-Mauguin (H-M) symbol which specifies the space group of the structure in the response.\nThe H-M symbol SHOULD aim to convey the closest representation of the symmetry information that can be specified using the short format used in the International Tables for Crystallography vol. A (IUCr, 2005), Table 4.3.2.1 as described in the accompanying text.\nThe symbol MAY be a non-standard short H-M symbol.\nThe H-M symbol does not unambiguously communicate the axis, cell, and origin choice, and the given symbol SHOULD NOT be amended to convey this information.\n\nTo encode as character strings, the following adaptations MUST be made when representing H-M symbols given in their typesetted form:\n - the overbar above the numbers MUST be changed to the minus sign in front of the digit (e.g. '-2');\n - subscripts that denote screw axes are written as digits immediately after the axis designator without a space (e.g. 'P 32')\n - the space group generators MUST be separated by a single space (e.g. 'P 21 21 2');\n - there MUST be no spaces in the space group generator designation (i.e. use 'P 21/m', not the 'P 21 / m');\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n\n- **Examples**:\n - `C 2`\n - `P 21 21 21`\n\n- **Bibliographic References**:\n\nIUCr (2005). International Tables for Crystallography vol. A. Space-Group Symmetry. Ed. Theo Hahn. 5-th edition. Dordrecht, Springer.", "x-optimade-queryable": "optional", "x-optimade-support": "optional" }, "space_group_it_number": { - "title": "Space Group It Number", + "type": "integer", "maximum": 230.0, "minimum": 1.0, - "type": "integer", + "title": "Space Group It Number", "description": "Space group number for the structure assigned by the International Tables for Crystallography Vol. A.\n- **Type**: integer\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - The integer value MUST be between 1 and 230.\n - MUST be null if `nperiodic_dimensions` is not equal to 3.", "x-optimade-queryable": "optional", "x-optimade-support": "optional" @@ -3640,18 +3659,18 @@ "type": "array", "title": "Cartesian Site Positions", "description": "Cartesian positions of each site in the structure.\nA site is usually used to describe positions of atoms; what atoms can be encountered at a given site is conveyed by the `species_at_sites` property, and the species themselves are described in the `species` property.\n\n- **Type**: list of list of floats\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - It MUST be a list of length equal to the number of sites in the structure, where every element is a list of the three Cartesian coordinates of a site expressed as float values in the unit angstrom (\u00c5).\n - An entry MAY have multiple sites at the same Cartesian position (for a relevant use of this, see e.g., the property `assemblies`).\n\n- **Examples**:\n - `[[0,0,0],[0,0,2]]` indicates a structure with two sites, one sitting at the origin and one along the (positive) *z*-axis, 2 \u00c5 away from the origin.", - "nullable": true, - "x-optimade-unit": "\u00c5", "x-optimade-queryable": "optional", - "x-optimade-support": "should" + "x-optimade-unit": "\u00c5", + "x-optimade-support": "should", + "nullable": true }, "nsites": { "type": "integer", "title": "Nsites", "description": "An integer specifying the length of the `cartesian_site_positions` property.\n\n- **Type**: integer\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `42`\n\n- **Query examples**:\n - Match only structures with exactly 4 sites: `nsites=4`\n - Match structures that have between 2 and 7 sites: `nsites>=2 AND nsites<=7`", - "x-optimade-support": "should", + "nullable": true, "x-optimade-queryable": "must", - "nullable": true + "x-optimade-support": "should" }, "species": { "items": { @@ -3660,9 +3679,9 @@ "type": "array", "title": "Species", "description": "A list describing the species of the sites of this structure.\nSpecies can represent pure chemical elements, virtual-crystal atoms representing a statistical occupation of a given site by multiple chemical elements, and/or a location to which there are attached atoms, i.e., atoms whose precise location are unknown beyond that they are attached to that position (frequently used to indicate hydrogen atoms attached to another element, e.g., a carbon with three attached hydrogens might represent a methyl group, -CH3).\n\n- **Type**: list of dictionary with keys:\n - `name`: string (REQUIRED)\n - `chemical_symbols`: list of strings (REQUIRED)\n - `concentration`: list of float (REQUIRED)\n - `attached`: list of strings (REQUIRED)\n - `nattached`: list of integers (OPTIONAL)\n - `mass`: list of floats (OPTIONAL)\n - `original_name`: string (OPTIONAL).\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - Each list member MUST be a dictionary with the following keys:\n - **name**: REQUIRED; gives the name of the species; the **name** value MUST be unique in the `species` list;\n - **chemical_symbols**: REQUIRED; MUST be a list of strings of all chemical elements composing this species.\n Each item of the list MUST be one of the following:\n - a valid chemical-element symbol, or\n - the special value `\"X\"` to represent a non-chemical element, or\n - the special value `\"vacancy\"` to represent that this site has a non-zero probability of having a vacancy (the respective probability is indicated in the `concentration` list, see below).\n\n If any one entry in the `species` list has a `chemical_symbols` list that is longer than 1 element, the correct flag MUST be set in the list `structure_features`.\n\n - **concentration**: REQUIRED; MUST be a list of floats, with same length as `chemical_symbols`.\n The numbers represent the relative concentration of the corresponding chemical symbol in this species.\n The numbers SHOULD sum to one. Cases in which the numbers do not sum to one typically fall only in the following two categories:\n\n - Numerical errors when representing float numbers in fixed precision, e.g. for two chemical symbols with concentrations `1/3` and `2/3`, the concentration might look something like `[0.33333333333, 0.66666666666]`. If the client is aware that the sum is not one because of numerical precision, it can renormalize the values so that the sum is exactly one.\n - Experimental errors in the data present in the database. In this case, it is the responsibility of the client to decide how to process the data.\n\n Note that concentrations are uncorrelated between different sites (even of the same species).\n\n - **attached**: OPTIONAL; if provided MUST be a list of length 1 or more of strings of chemical symbols for the elements attached to this site, or \"X\" for a non-chemical element.\n\n - **nattached**: OPTIONAL; if provided MUST be a list of length 1 or more of integers indicating the number of attached atoms of the kind specified in the value of the `attached` key.\n\n The implementation MUST include either both or none of the `attached` and `nattached` keys, and if they are provided, they MUST be of the same length.\n Furthermore, if they are provided, the `structure_features` property MUST include the string `site_attachments`.\n\n - **mass**: OPTIONAL. If present MUST be a list of floats, with the same length as `chemical_symbols`, providing element masses expressed in a.m.u.\n Elements denoting vacancies MUST have masses equal to 0.\n\n - **original_name**: OPTIONAL. Can be any valid Unicode string, and SHOULD contain (if specified) the name of the species that is used internally in the source database.\n\n Note: With regards to \"source database\", we refer to the immediate source being queried via the OPTIMADE API implementation.\n\n The main use of this field is for source databases that use species names, containing characters that are not allowed (see description of the list property `species_at_sites`).\n\n - For systems that have only species formed by a single chemical symbol, and that have at most one species per chemical symbol, SHOULD use the chemical symbol as species name (e.g., `\"Ti\"` for titanium, `\"O\"` for oxygen, etc.)\n However, note that this is OPTIONAL, and client implementations MUST NOT assume that the key corresponds to a chemical symbol, nor assume that if the species name is a valid chemical symbol, that it represents a species with that chemical symbol.\n This means that a species `{\"name\": \"C\", \"chemical_symbols\": [\"Ti\"], \"concentration\": [1.0]}` is valid and represents a titanium species (and *not* a carbon species).\n - It is NOT RECOMMENDED that a structure includes species that do not have at least one corresponding site.\n\n- **Examples**:\n - `[ {\"name\": \"Ti\", \"chemical_symbols\": [\"Ti\"], \"concentration\": [1.0]} ]`: any site with this species is occupied by a Ti atom.\n - `[ {\"name\": \"Ti\", \"chemical_symbols\": [\"Ti\", \"vacancy\"], \"concentration\": [0.9, 0.1]} ]`: any site with this species is occupied by a Ti atom with 90 % probability, and has a vacancy with 10 % probability.\n - `[ {\"name\": \"BaCa\", \"chemical_symbols\": [\"vacancy\", \"Ba\", \"Ca\"], \"concentration\": [0.05, 0.45, 0.5], \"mass\": [0.0, 137.327, 40.078]} ]`: any site with this species is occupied by a Ba atom with 45 % probability, a Ca atom with 50 % probability, and by a vacancy with 5 % probability. The mass of this site is (on average) 88.5 a.m.u.\n - `[ {\"name\": \"C12\", \"chemical_symbols\": [\"C\"], \"concentration\": [1.0], \"mass\": [12.0]} ]`: any site with this species is occupied by a carbon isotope with mass 12.\n - `[ {\"name\": \"C13\", \"chemical_symbols\": [\"C\"], \"concentration\": [1.0], \"mass\": [13.0]} ]`: any site with this species is occupied by a carbon isotope with mass 13.\n - `[ {\"name\": \"CH3\", \"chemical_symbols\": [\"C\"], \"concentration\": [1.0], \"attached\": [\"H\"], \"nattached\": [3]} ]`: any site with this species is occupied by a methyl group, -CH3, which is represented without specifying precise positions of the hydrogen atoms.", - "x-optimade-support": "should", + "nullable": true, "x-optimade-queryable": "optional", - "nullable": true + "x-optimade-support": "should" }, "species_at_sites": { "items": { @@ -3671,9 +3690,9 @@ "type": "array", "title": "Species At Sites", "description": "Name of the species at each site (where values for sites are specified with the same order of the property `cartesian_site_positions`).\nThe properties of the species are found in the property `species`.\n\n- **Type**: list of strings.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - MUST have length equal to the number of sites in the structure (first dimension of the list property `cartesian_site_positions`).\n - Each species name mentioned in the `species_at_sites` list MUST be described in the list property `species` (i.e. for each value in the `species_at_sites` list there MUST exist exactly one dictionary in the `species` list with the `name` attribute equal to the corresponding `species_at_sites` value).\n - Each site MUST be associated only to a single species.\n **Note**: However, species can represent mixtures of atoms, and multiple species MAY be defined for the same chemical element.\n This latter case is useful when different atoms of the same type need to be grouped or distinguished, for instance in simulation codes to assign different initial spin states.\n\n- **Examples**:\n - `[\"Ti\",\"O2\"]` indicates that the first site is hosting a species labeled `\"Ti\"` and the second a species labeled `\"O2\"`.\n - `[\"Ac\", \"Ac\", \"Ag\", \"Ir\"]` indicating the first two sites contains the `\"Ac\"` species, while the third and fourth sites contain the `\"Ag\"` and `\"Ir\"` species, respectively.", - "x-optimade-support": "should", + "nullable": true, "x-optimade-queryable": "optional", - "nullable": true + "x-optimade-support": "should" }, "assemblies": { "items": { @@ -3682,8 +3701,8 @@ "type": "array", "title": "Assemblies", "description": "A description of groups of sites that are statistically correlated.\n\n- **Type**: list of dictionary with keys:\n - `sites_in_groups`: list of list of integers (REQUIRED)\n - `group_probabilities`: list of floats (REQUIRED)\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - The property SHOULD be `null` for entries that have no partial occupancies.\n - If present, the correct flag MUST be set in the list `structure_features`.\n - Client implementations MUST check its presence (as its presence changes the interpretation of the structure).\n - If present, it MUST be a list of dictionaries, each of which represents an assembly and MUST have the following two keys:\n - **sites_in_groups**: Index of the sites (0-based) that belong to each group for each assembly.\n\n Example: `[[1], [2]]`: two groups, one with the second site, one with the third.\n Example: `[[1,2], [3]]`: one group with the second and third site, one with the fourth.\n\n - **group_probabilities**: Statistical probability of each group. It MUST have the same length as `sites_in_groups`.\n It SHOULD sum to one.\n See below for examples of how to specify the probability of the occurrence of a vacancy.\n The possible reasons for the values not to sum to one are the same as already specified above for the `concentration` of each `species`.\n\n - If a site is not present in any group, it means that it is present with 100 % probability (as if no assembly was specified).\n - A site MUST NOT appear in more than one group.\n\n- **Examples** (for each entry of the assemblies list):\n - `{\"sites_in_groups\": [[0], [1]], \"group_probabilities: [0.3, 0.7]}`: the first site and the second site never occur at the same time in the unit cell.\n Statistically, 30 % of the times the first site is present, while 70 % of the times the second site is present.\n - `{\"sites_in_groups\": [[1,2], [3]], \"group_probabilities: [0.3, 0.7]}`: the second and third site are either present together or not present; they form the first group of atoms for this assembly.\n The second group is formed by the fourth site.\n Sites of the first group (the second and the third) are never present at the same time as the fourth site.\n 30 % of times sites 1 and 2 are present (and site 3 is absent); 70 % of times site 3 is present (and sites 1 and 2 are absent).\n\n- **Notes**:\n - Assemblies are essential to represent, for instance, the situation where an atom can statistically occupy two different positions (sites).\n\n - By defining groups, it is possible to represent, e.g., the case where a functional molecule (and not just one atom) is either present or absent (or the case where it it is present in two conformations)\n\n - Considerations on virtual alloys and on vacancies: In the special case of a virtual alloy, these specifications allow two different, equivalent ways of specifying them.\n For instance, for a site at the origin with 30 % probability of being occupied by Si, 50 % probability of being occupied by Ge, and 20 % of being a vacancy, the following two representations are possible:\n\n - Using a single species:\n ```json\n {\n \"cartesian_site_positions\": [[0,0,0]],\n \"species_at_sites\": [\"SiGe-vac\"],\n \"species\": [\n {\n \"name\": \"SiGe-vac\",\n \"chemical_symbols\": [\"Si\", \"Ge\", \"vacancy\"],\n \"concentration\": [0.3, 0.5, 0.2]\n }\n ]\n // ...\n }\n ```\n\n - Using multiple species and the assemblies:\n ```json\n {\n \"cartesian_site_positions\": [ [0,0,0], [0,0,0], [0,0,0] ],\n \"species_at_sites\": [\"Si\", \"Ge\", \"vac\"],\n \"species\": [\n { \"name\": \"Si\", \"chemical_symbols\": [\"Si\"], \"concentration\": [1.0] },\n { \"name\": \"Ge\", \"chemical_symbols\": [\"Ge\"], \"concentration\": [1.0] },\n { \"name\": \"vac\", \"chemical_symbols\": [\"vacancy\"], \"concentration\": [1.0] }\n ],\n \"assemblies\": [\n {\n \"sites_in_groups\": [ [0], [1], [2] ],\n \"group_probabilities\": [0.3, 0.5, 0.2]\n }\n ]\n // ...\n }\n ```\n\n - It is up to the database provider to decide which representation to use, typically depending on the internal format in which the structure is stored.\n However, given a structure identified by a unique ID, the API implementation MUST always provide the same representation for it.\n\n - The probabilities of occurrence of different assemblies are uncorrelated.\n So, for instance in the following case with two assemblies:\n ```json\n {\n \"assemblies\": [\n {\n \"sites_in_groups\": [ [0], [1] ],\n \"group_probabilities\": [0.2, 0.8],\n },\n {\n \"sites_in_groups\": [ [2], [3] ],\n \"group_probabilities\": [0.3, 0.7]\n }\n ]\n }\n ```\n\n Site 0 is present with a probability of 20 % and site 1 with a probability of 80 %. These two sites are correlated (either site 0 or 1 is present). Similarly, site 2 is present with a probability of 30 % and site 3 with a probability of 70 %.\n These two sites are correlated (either site 2 or 3 is present).\n However, the presence or absence of sites 0 and 1 is not correlated with the presence or absence of sites 2 and 3 (in the specific example, the pair of sites (0, 2) can occur with 0.2*0.3 = 6 % probability; the pair (0, 3) with 0.2*0.7 = 14 % probability; the pair (1, 2) with 0.8*0.3 = 24 % probability; and the pair (1, 3) with 0.8*0.7 = 56 % probability).", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "structure_features": { "items": { @@ -3692,8 +3711,8 @@ "type": "array", "title": "Structure Features", "description": "A list of strings that flag which special features are used by the structure.\n\n- **Type**: list of strings\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property.\n Filters on the list MUST support all mandatory HAS-type queries.\n Filter operators for comparisons on the string components MUST support equality, support for other comparison operators are OPTIONAL.\n - MUST be an empty list if no special features are used.\n - MUST be sorted alphabetically.\n - If a special feature listed below is used, the list MUST contain the corresponding string.\n - If a special feature listed below is not used, the list MUST NOT contain the corresponding string.\n - **List of strings used to indicate special structure features**:\n - `disorder`: this flag MUST be present if any one entry in the `species` list has a `chemical_symbols` list that is longer than 1 element.\n - `implicit_atoms`: this flag MUST be present if the structure contains atoms that are not assigned to sites via the property `species_at_sites` (e.g., because their positions are unknown).\n When this flag is present, the properties related to the chemical formula will likely not match the type and count of atoms represented by the `species_at_sites`, `species` and `assemblies` properties.\n - `site_attachments`: this flag MUST be present if any one entry in the `species` list includes `attached` and `nattached`.\n - `assemblies`: this flag MUST be present if the property `assemblies` is present.\n\n- **Examples**: A structure having implicit atoms and using assemblies: `[\"assemblies\", \"implicit_atoms\"]`", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" } }, "type": "object", diff --git a/optimade/models/structures.py b/optimade/models/structures.py index 537063741..a9b819500 100644 --- a/optimade/models/structures.py +++ b/optimade/models/structures.py @@ -12,6 +12,7 @@ CHEMICAL_FORMULA_REGEXP, CHEMICAL_SYMBOLS, EXTRA_SYMBOLS, + SPACE_GROUP_SYMMETRY_OPERATION_REGEX, OptimadeField, StrictField, SupportLevel, @@ -523,9 +524,57 @@ class StructureResourceAttributes(EntryResourceAttributes): queryable=SupportLevel.OPTIONAL, ) + space_group_symmetry_operations_xyz: Optional[list[str]] = OptimadeField( + None, + description="""A list of symmetry operations given as general position x, y and z coordinates in algebraic form. + +Each symmetry operation is described by a string that gives that symmetry operation in Jones' faithful representation (Bradley & Cracknell, 1972: pp. 35-37), adapted for computer string notation. +The letters x, y and z that are typesetted with overbars in printed text represent coordinate values multiplied by -1 and are encoded as -x, -y and -z, respectively. +The syntax of the strings representing symmetry operations MUST conform to regular expressions given in appendix The Symmetry Operation String Regular Expressions. +The interpretation of the strings MUST follow the conventions of the IUCr CIF core dictionary (IUCr, 2023). +In particular, this property MUST explicitly provide all symmetry operations needed to generate all the atoms in the unit cell from the atoms in the asymmetric unit, for the setting used. +This symmetry operation set MUST always include the `"x,y,z"` identity operation. +The symmetry operations are to be applied to fractional atom coordinates. +In case only Cartesian coordinates are available, these Cartesian coordinates must be converted to fractional coordinates before the application of the provided symmetry operations. +If the symmetry operation list is present, it MUST be compatible with other space group specifications (e.g. the ITC space group number, the Hall symbol, the Hermann-Mauguin symbol) if these are present. + +- **Type**: list of strings + +- **Requirements/Conventions**: + - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`. + However, the property is RECOMMENDED if coordinates are returned in a form to which these operations can or must be applied (e.g. fractional atom coordinates of an asymmetric unit). + Moreover, the property is REQUIRED if symmetry operations are necessary to reconstruct the full model of the material and no other symmetry information (e.g., the Hall symbol) is provided that would allow the user to derive symmetry operations unambiguously. + - MUST be null if `nperiodic_dimensions` is equal to 0. + +- **Examples**: + - Space group operations for the space group with ITC number 3 (H-M symbol: P 2, extended H-M symbol: P 1 2 1, Hall symbol P 2y): + ``` + ["x,y,z", "-x,y,-z"] + ``` + - Space group operations for the space group with ITC number 5 (H-M symbol C 2, extended H-M symbol: C 1 2 1, Hall symbol C 2y): + ``` + ["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 `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. + +- **Bibliographic References**: + + Bradley, C. J. and Cracknell, A. P. (1972) The Mathematical Theory of Symmetry in Solids. Oxford, Clarendon Press (paperback edition 2010) 745 p. ISBN 978-0-19-958258-7. + + IUCr (2023) Core dictionary (coreCIF) version 2.4.5; data name _space_group_symop_operation_xyz. Available from: https://www.iucr.org/__data/iucr/cifdic_html/1/cif_core.dic/Ispace_group_symop_operation_xyz.html [Accessed 2023-06-18T16:46+03:00].""", + support=SupportLevel.OPTIONAL, + queryable=SupportLevel.OPTIONAL, + regex=SPACE_GROUP_SYMMETRY_OPERATION_REGEX, + ) + space_group_hall: Optional[str] = OptimadeField( None, - description="""A Hall space group symbol representing the symmetry of the structure as defined in Hall, S. R. (1981), Acta Cryst. A37, 517-525 and erratum (1981), A37, 921. + description="""A Hall space group symbol representing the symmetry of the structure as defined in (Hall, 1981, 1981a). +The change-of-basis operations are used as defined in the International Tables of Crystallography (ITC) Vol. B, Sect. 1.4, Appendix A1.4.2 (IUCr, 2001). - **Type**: string @@ -534,7 +583,45 @@ class StructureResourceAttributes(EntryResourceAttributes): - **Query**: Support for queries on this property is OPTIONAL. - Each component of the Hall symbol MUST be separated by a single space symbol. - If there exists a standard Hall symbol which represents the symmetry it SHOULD be used. - - MUST be null if `nperiodic_dimensions` is not equal to 3.""", + - MUST be null if `nperiodic_dimensions` is not equal to 3. + +- **Bibliographic References**: + + Hall, S. R. (1981) Space-group notation with an explicit origin. Acta Crystallographica Section A, 37, 517-525, International Union of Crystallography (IUCr), DOI: https://doi.org/10.1107/s0567739481001228 + + Hall, S. R. (1981a) Space-group notation with an explicit origin; erratum. Acta Crystallographica Section A, 37, 921-921, International Union of Crystallography (IUCr), DOI: https://doi.org/10.1107/s0567739481001976 + + IUCr (2001). International Tables for Crystallography vol. B. Reciprocal Space. Ed. U. Shmueli. 2-nd edition. Dordrecht/Boston/London, Kluwer Academic Publishers.""", + support=SupportLevel.OPTIONAL, + queryable=SupportLevel.OPTIONAL, + ) + + space_group_symbol_hermann_mauguin: Optional[str] = OptimadeField( + None, + description="""A human- and machine-readable string containing the short Hermann-Mauguin (H-M) symbol which specifies the space group of the structure in the response. +The H-M symbol SHOULD aim to convey the closest representation of the symmetry information that can be specified using the short format used in the International Tables for Crystallography vol. A (IUCr, 2005), Table 4.3.2.1 as described in the accompanying text. +The symbol MAY be a non-standard short H-M symbol. +The H-M symbol does not unambiguously communicate the axis, cell, and origin choice, and the given symbol SHOULD NOT be amended to convey this information. + +To encode as character strings, the following adaptations MUST be made when representing H-M symbols given in their typesetted form: + - the overbar above the numbers MUST be changed to the minus sign in front of the digit (e.g. '-2'); + - subscripts that denote screw axes are written as digits immediately after the axis designator without a space (e.g. 'P 32') + - the space group generators MUST be separated by a single space (e.g. 'P 21 21 2'); + - there MUST be no spaces in the space group generator designation (i.e. use 'P 21/m', not the 'P 21 / m'); + +- **Type**: string + +- **Requirements/Conventions**: + - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`. + - **Query**: Support for queries on this property is OPTIONAL. + +- **Examples**: + - `C 2` + - `P 21 21 21` + +- **Bibliographic References**: + +IUCr (2005). International Tables for Crystallography vol. A. Space-Group Symmetry. Ed. Theo Hahn. 5-th edition. Dordrecht, Springer.""", support=SupportLevel.OPTIONAL, queryable=SupportLevel.OPTIONAL, ) diff --git a/optimade/models/utils.py b/optimade/models/utils.py index 99a0c04c6..cc15d5758 100644 --- a/optimade/models/utils.py +++ b/optimade/models/utils.py @@ -418,3 +418,9 @@ def reduce_formula(formula: str) -> str: ATOMIC_NUMBERS = {} for Z, symbol in enumerate(CHEMICAL_SYMBOLS): ATOMIC_NUMBERS[symbol] = Z + 1 + +translation = "1/2|[12]/3|[1-3]/4|[1-5]/6" +translation_appended = f"[-+]? [xyz] ([-+][xyz])? ([-+] ({translation}) )?" +translation_prepended = f"[-+]? ({translation}) ([-+] [xyz] ([-+][xyz])? )?" +symop = f"({translation_appended}|{translation_prepended})" +SPACE_GROUP_SYMMETRY_OPERATION_REGEX = f"^{symop},{symop},{symop}$" diff --git a/tests/models/test_utils.py b/tests/models/test_utils.py index 57de92030..410127c3c 100644 --- a/tests/models/test_utils.py +++ b/tests/models/test_utils.py @@ -1,3 +1,4 @@ +import re from typing import Callable import pytest @@ -138,3 +139,12 @@ def test_anonymize_formula(): assert anonymize_formula("Si1 O2") == "A2B" assert anonymize_formula("Si11 O2") == "A11B2" assert anonymize_formula("Si10 O2C4") == "A5B2C" + + +@pytest.mark.parametrize( + "symops", ["x,y,z", "-x,y,-z", "x+1/2,y+1/2,z", "-x+1/2,y+1/2,-z"] +) +def test_symop_regex(symops): + from optimade.models.utils import SPACE_GROUP_SYMMETRY_OPERATION_REGEX + + assert re.match(SPACE_GROUP_SYMMETRY_OPERATION_REGEX, symops) From 6b9e36a999cad629273ec114e7bd48c51938b339 Mon Sep 17 00:00:00 2001 From: Matthew Evans Date: Sat, 23 Dec 2023 13:16:51 +0000 Subject: [PATCH 03/19] Use constr for pydantic v1 instead of field regexp --- openapi/index_openapi.json | 20 +-- openapi/openapi.json | 279 +++++++++++++++++----------------- optimade/models/structures.py | 6 +- 3 files changed, 152 insertions(+), 153 deletions(-) diff --git a/openapi/index_openapi.json b/openapi/index_openapi.json index 337e33d09..62c29ef4a 100644 --- a/openapi/index_openapi.json +++ b/openapi/index_openapi.json @@ -498,15 +498,15 @@ "type": "string", "title": "Id", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "type": { "type": "string", "title": "Type", "description": "The name of the type of an entry.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - MUST be an existing entry type.\n - The entry of type `` and ID `` MUST be returned in response to a request for `//` under the versioned base URL.\n\n- **Example**: `\"structures\"`", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "links": { "allOf": [ @@ -560,16 +560,16 @@ "type": "string", "title": "Immutable Id", "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", - "x-optimade-queryable": "must", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "must" }, "last_modified": { "type": "string", "format": "date-time", "title": "Last Modified", "description": "Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n - As part of JSON response format: `\"2007-04-05T14:30:20Z\"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)", - "x-optimade-queryable": "must", - "x-optimade-support": "should" + "x-optimade-support": "should", + "x-optimade-queryable": "must" } }, "type": "object", @@ -1107,8 +1107,8 @@ "type": "string", "title": "Id", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "type": { "type": "string", diff --git a/openapi/openapi.json b/openapi/openapi.json index db5e5d79b..55ae3d7e5 100644 --- a/openapi/openapi.json +++ b/openapi/openapi.json @@ -1335,8 +1335,8 @@ "type": "array", "title": "Sites In Groups", "description": "Index of the sites (0-based) that belong to each group for each assembly.\n\n- **Examples**:\n - `[[1], [2]]`: two groups, one with the second site, one with the third.\n - `[[1,2], [3]]`: one group with the second and third site, one with the fourth.", - "x-optimade-queryable": "optional", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "optional" }, "group_probabilities": { "items": { @@ -1345,8 +1345,8 @@ "type": "array", "title": "Group Probabilities", "description": "Statistical probability of each group. It MUST have the same length as `sites_in_groups`.\nIt SHOULD sum to one.\nSee below for examples of how to specify the probability of the occurrence of a vacancy.\nThe possible reasons for the values not to sum to one are the same as already specified above for the `concentration` of each `species`.", - "x-optimade-queryable": "optional", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "optional" } }, "type": "object", @@ -1748,15 +1748,15 @@ "type": "string", "title": "Id", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "type": { "type": "string", "title": "Type", "description": "The name of the type of an entry.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - MUST be an existing entry type.\n - The entry of type `` and ID `` MUST be returned in response to a request for `//` under the versioned base URL.\n\n- **Example**: `\"structures\"`", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "links": { "allOf": [ @@ -1810,16 +1810,16 @@ "type": "string", "title": "Immutable Id", "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", - "x-optimade-queryable": "must", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "must" }, "last_modified": { "type": "string", "format": "date-time", "title": "Last Modified", "description": "Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n - As part of JSON response format: `\"2007-04-05T14:30:20Z\"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)", - "x-optimade-queryable": "must", - "x-optimade-support": "should" + "x-optimade-support": "should", + "x-optimade-queryable": "must" } }, "type": "object", @@ -2216,8 +2216,8 @@ "type": "string", "title": "Id", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "type": { "type": "string", @@ -2517,22 +2517,22 @@ "type": "string", "title": "Name", "description": "Full name of the person, REQUIRED.", - "x-optimade-queryable": "optional", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "optional" }, "firstname": { "type": "string", "title": "Firstname", "description": "First name of the person.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "lastname": { "type": "string", "title": "Lastname", "description": "Last name of the person.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" } }, "type": "object", @@ -2632,8 +2632,8 @@ "type": "string", "title": "Id", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "type": { "type": "string", @@ -2641,8 +2641,8 @@ "title": "Type", "description": "The name of the type of an entry.\n- **Type**: string.\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - MUST be an existing entry type.\n - The entry of type and ID MUST be returned in response to a request for `//` under the versioned base URL.\n- **Example**: `\"structures\"`", "default": "references", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "links": { "allOf": [ @@ -2690,16 +2690,16 @@ "type": "string", "title": "Immutable Id", "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", - "x-optimade-queryable": "must", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "must" }, "last_modified": { "type": "string", "format": "date-time", "title": "Last Modified", "description": "Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n - As part of JSON response format: `\"2007-04-05T14:30:20Z\"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)", - "x-optimade-queryable": "must", - "x-optimade-support": "should" + "x-optimade-support": "should", + "x-optimade-queryable": "must" }, "authors": { "items": { @@ -2708,8 +2708,8 @@ "type": "array", "title": "Authors", "description": "List of person objects containing the authors of the reference.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "editors": { "items": { @@ -2718,15 +2718,15 @@ "type": "array", "title": "Editors", "description": "List of person objects containing the editors of the reference.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "doi": { "type": "string", "title": "Doi", "description": "The digital object identifier of the reference.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "url": { "type": "string", @@ -2735,162 +2735,162 @@ "format": "uri", "title": "Url", "description": "The URL of the reference.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "address": { "type": "string", "title": "Address", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "annote": { "type": "string", "title": "Annote", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "booktitle": { "type": "string", "title": "Booktitle", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "chapter": { "type": "string", "title": "Chapter", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "crossref": { "type": "string", "title": "Crossref", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "edition": { "type": "string", "title": "Edition", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "howpublished": { "type": "string", "title": "Howpublished", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "institution": { "type": "string", "title": "Institution", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "journal": { "type": "string", "title": "Journal", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "key": { "type": "string", "title": "Key", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "month": { "type": "string", "title": "Month", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "note": { "type": "string", "title": "Note", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "number": { "type": "string", "title": "Number", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "organization": { "type": "string", "title": "Organization", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "pages": { "type": "string", "title": "Pages", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "publisher": { "type": "string", "title": "Publisher", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "school": { "type": "string", "title": "School", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "series": { "type": "string", "title": "Series", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "title": { "type": "string", "title": "Title", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "bib_type": { "type": "string", "title": "Bib Type", "description": "Type of the reference, corresponding to the **type** property in the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "volume": { "type": "string", "title": "Volume", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "year": { "type": "string", "title": "Year", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" } }, "type": "object", @@ -3310,8 +3310,8 @@ "type": "string", "title": "Name", "description": "Gives the name of the species; the **name** value MUST be unique in the `species` list.", - "x-optimade-queryable": "optional", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "optional" }, "chemical_symbols": { "items": { @@ -3320,8 +3320,8 @@ "type": "array", "title": "Chemical Symbols", "description": "MUST be a list of strings of all chemical elements composing this species. Each item of the list MUST be one of the following:\n\n- a valid chemical-element symbol, or\n- the special value `\"X\"` to represent a non-chemical element, or\n- the special value `\"vacancy\"` to represent that this site has a non-zero probability of having a vacancy (the respective probability is indicated in the `concentration` list, see below).\n\nIf any one entry in the `species` list has a `chemical_symbols` list that is longer than 1 element, the correct flag MUST be set in the list `structure_features`.", - "x-optimade-queryable": "optional", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "optional" }, "concentration": { "items": { @@ -3330,8 +3330,8 @@ "type": "array", "title": "Concentration", "description": "MUST be a list of floats, with same length as `chemical_symbols`. The numbers represent the relative concentration of the corresponding chemical symbol in this species. The numbers SHOULD sum to one. Cases in which the numbers do not sum to one typically fall only in the following two categories:\n\n- Numerical errors when representing float numbers in fixed precision, e.g. for two chemical symbols with concentrations `1/3` and `2/3`, the concentration might look something like `[0.33333333333, 0.66666666666]`. If the client is aware that the sum is not one because of numerical precision, it can renormalize the values so that the sum is exactly one.\n- Experimental errors in the data present in the database. In this case, it is the responsibility of the client to decide how to process the data.\n\nNote that concentrations are uncorrelated between different site (even of the same species).", - "x-optimade-queryable": "optional", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "optional" }, "mass": { "items": { @@ -3340,16 +3340,16 @@ "type": "array", "title": "Mass", "description": "If present MUST be a list of floats expressed in a.m.u.\nElements denoting vacancies MUST have masses equal to 0.", + "x-optimade-support": "optional", "x-optimade-queryable": "optional", - "x-optimade-unit": "a.m.u.", - "x-optimade-support": "optional" + "x-optimade-unit": "a.m.u." }, "original_name": { "type": "string", "title": "Original Name", "description": "Can be any valid Unicode string, and SHOULD contain (if specified) the name of the species that is used internally in the source database.\n\nNote: With regards to \"source database\", we refer to the immediate source being queried via the OPTIMADE API implementation.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "attached": { "items": { @@ -3358,8 +3358,8 @@ "type": "array", "title": "Attached", "description": "If provided MUST be a list of length 1 or more of strings of chemical symbols for the elements attached to this site, or \"X\" for a non-chemical element.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "nattached": { "items": { @@ -3368,8 +3368,8 @@ "type": "array", "title": "Nattached", "description": "If provided MUST be a list of length 1 or more of integers indicating the number of attached atoms of the kind specified in the value of the :field:`attached` key.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" } }, "type": "object", @@ -3438,8 +3438,8 @@ "type": "string", "title": "Id", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "type": { "type": "string", @@ -3447,8 +3447,8 @@ "title": "Type", "description": "The name of the type of an entry.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - MUST be an existing entry type.\n - The entry of type `` and ID `` MUST be returned in response to a request for `//` under the versioned base URL.\n\n- **Examples**:\n - `\"structures\"`", "default": "structures", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "links": { "allOf": [ @@ -3496,8 +3496,8 @@ "type": "string", "title": "Immutable Id", "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", - "x-optimade-queryable": "must", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "must" }, "last_modified": { "type": "string", @@ -3505,8 +3505,8 @@ "title": "Last Modified", "description": "Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n - As part of JSON response format: `\"2007-04-05T14:30:20Z\"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)", "nullable": true, - "x-optimade-queryable": "must", - "x-optimade-support": "should" + "x-optimade-support": "should", + "x-optimade-queryable": "must" }, "elements": { "items": { @@ -3516,16 +3516,16 @@ "title": "Elements", "description": "The chemical symbols of the different elements present in the structure.\n\n- **Type**: list of strings.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - The strings are the chemical symbols, i.e., either a single uppercase letter or an uppercase letter followed by a number of lowercase letters.\n - The order MUST be alphabetical.\n - MUST refer to the same elements in the same order, and therefore be of the same length, as `elements_ratios`, if the latter is provided.\n - Note: This property SHOULD NOT contain the string \"X\" to indicate non-chemical elements or \"vacancy\" to indicate vacancies (in contrast to the field `chemical_symbols` for the `species` property).\n\n- **Examples**:\n - `[\"Si\"]`\n - `[\"Al\",\"O\",\"Si\"]`\n\n- **Query examples**:\n - A filter that matches all records of structures that contain Si, Al **and** O, and possibly other elements: `elements HAS ALL \"Si\", \"Al\", \"O\"`.\n - To match structures with exactly these three elements, use `elements HAS ALL \"Si\", \"Al\", \"O\" AND elements LENGTH 3`.\n - Note: length queries on this property can be equivalently formulated by filtering on the `nelements`_ property directly.", "nullable": true, - "x-optimade-queryable": "must", - "x-optimade-support": "should" + "x-optimade-support": "should", + "x-optimade-queryable": "must" }, "nelements": { "type": "integer", "title": "Nelements", "description": "Number of different elements in the structure as an integer.\n\n- **Type**: integer\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - MUST be equal to the lengths of the list properties `elements` and `elements_ratios`, if they are provided.\n\n- **Examples**:\n - `3`\n\n- **Querying**:\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`.", "nullable": true, - "x-optimade-queryable": "must", - "x-optimade-support": "should" + "x-optimade-support": "should", + "x-optimade-queryable": "must" }, "elements_ratios": { "items": { @@ -3535,16 +3535,16 @@ "title": "Elements Ratios", "description": "Relative proportions of different elements in the structure.\n\n- **Type**: list of floats\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - Composed by the proportions of elements in the structure as a list of floating point numbers.\n - The sum of the numbers MUST be 1.0 (within floating point accuracy)\n - MUST refer to the same elements in the same order, and therefore be of the same length, as `elements`, if the latter is provided.\n\n- **Examples**:\n - `[1.0]`\n - `[0.3333333333333333, 0.2222222222222222, 0.4444444444444444]`\n\n- **Query examples**:\n - Note: Useful filters can be formulated using the set operator syntax for correlated values.\n However, since the values are floating point values, the use of equality comparisons is generally inadvisable.\n - OPTIONAL: a filter that matches structures where approximately 1/3 of the atoms in the structure are the element Al is: `elements:elements_ratios HAS ALL \"Al\":>0.3333, \"Al\":<0.3334`.", "nullable": true, - "x-optimade-queryable": "must", - "x-optimade-support": "should" + "x-optimade-support": "should", + "x-optimade-queryable": "must" }, "chemical_formula_descriptive": { "type": "string", "title": "Chemical Formula Descriptive", "description": "The chemical formula for a structure as a string in a form chosen by the API implementation.\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - The chemical formula is given as a string consisting of properly capitalized element symbols followed by integers or decimal numbers, balanced parentheses, square, and curly brackets `(`,`)`, `[`,`]`, `{`, `}`, commas, the `+`, `-`, `:` and `=` symbols. The parentheses are allowed to be followed by a number. Spaces are allowed anywhere except within chemical symbols. The order of elements and any groupings indicated by parentheses or brackets are chosen freely by the API implementation.\n - The string SHOULD be arithmetically consistent with the element ratios in the `chemical_formula_reduced` property.\n - It is RECOMMENDED, but not mandatory, that symbols, parentheses and brackets, if used, are used with the meanings prescribed by [IUPAC's Nomenclature of Organic Chemistry](https://www.qmul.ac.uk/sbcs/iupac/bibliog/blue.html).\n\n- **Examples**:\n - `\"(H2O)2 Na\"`\n - `\"NaCl\"`\n - `\"CaCO3\"`\n - `\"CCaO3\"`\n - `\"(CH3)3N+ - [CH2]2-OH = Me3N+ - CH2 - CH2OH\"`\n\n- **Query examples**:\n - Note: the free-form nature of this property is likely to make queries on it across different databases inconsistent.\n - A filter that matches an exactly given formula: `chemical_formula_descriptive=\"(H2O)2 Na\"`.\n - A filter that does a partial match: `chemical_formula_descriptive CONTAINS \"H2O\"`.", "nullable": true, - "x-optimade-queryable": "must", - "x-optimade-support": "should" + "x-optimade-support": "should", + "x-optimade-queryable": "must" }, "chemical_formula_reduced": { "type": "string", @@ -3552,16 +3552,16 @@ "title": "Chemical Formula Reduced", "description": "The reduced chemical formula for a structure as a string with element symbols and integer chemical proportion numbers.\nThe proportion number MUST be omitted if it is 1.\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property.\n However, support for filters using partial string matching with this property is OPTIONAL (i.e., BEGINS WITH, ENDS WITH, and CONTAINS).\n Intricate queries on formula components are instead suggested to be formulated using set-type filter operators on the multi valued `elements` and `elements_ratios` properties.\n - Element symbols MUST have proper capitalization (e.g., `\"Si\"`, not `\"SI\"` for \"silicon\").\n - Elements MUST be placed in alphabetical order, followed by their integer chemical proportion number.\n - For structures with no partial occupation, the chemical proportion numbers are the smallest integers for which the chemical proportion is exactly correct.\n - For structures with partial occupation, the chemical proportion numbers are integers that within reasonable approximation indicate the correct chemical proportions. The precise details of how to perform the rounding is chosen by the API implementation.\n - No spaces or separators are allowed.\n\n- **Examples**:\n - `\"H2NaO\"`\n - `\"ClNa\"`\n - `\"CCaO3\"`\n\n- **Query examples**:\n - A filter that matches an exactly given formula is `chemical_formula_reduced=\"H2NaO\"`.", "nullable": true, - "x-optimade-queryable": "must", - "x-optimade-support": "should" + "x-optimade-support": "should", + "x-optimade-queryable": "must" }, "chemical_formula_hill": { "type": "string", "pattern": "(^$)|^([A-Z][a-z]?([2-9]|[1-9]\\d+)?)+$", "title": "Chemical Formula Hill", "description": "The chemical formula for a structure in [Hill form](https://dx.doi.org/10.1021/ja02046a005) with element symbols followed by integer chemical proportion numbers. The proportion number MUST be omitted if it is 1.\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, only a subset of the filter features MAY be supported.\n - The overall scale factor of the chemical proportions is chosen such that the resulting values are integers that indicate the most chemically relevant unit of which the system is composed.\n For example, if the structure is a repeating unit cell with four hydrogens and four oxygens that represents two hydroperoxide molecules, `chemical_formula_hill` is `\"H2O2\"` (i.e., not `\"HO\"`, nor `\"H4O4\"`).\n - If the chemical insight needed to ascribe a Hill formula to the system is not present, the property MUST be handled as unset.\n - Element symbols MUST have proper capitalization (e.g., `\"Si\"`, not `\"SI\"` for \"silicon\").\n - Elements MUST be placed in [Hill order](https://dx.doi.org/10.1021/ja02046a005), followed by their integer chemical proportion number.\n Hill order means: if carbon is present, it is placed first, and if also present, hydrogen is placed second.\n After that, all other elements are ordered alphabetically.\n If carbon is not present, all elements are ordered alphabetically.\n - If the system has sites with partial occupation and the total occupations of each element do not all sum up to integers, then the Hill formula SHOULD be handled as unset.\n - No spaces or separators are allowed.\n\n- **Examples**:\n - `\"H2O2\"`\n\n- **Query examples**:\n - A filter that matches an exactly given formula is `chemical_formula_hill=\"H2O2\"`.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "chemical_formula_anonymous": { "type": "string", @@ -3569,8 +3569,8 @@ "title": "Chemical Formula Anonymous", "description": "The anonymous formula is the `chemical_formula_reduced`, but where the elements are instead first ordered by their chemical proportion number, and then, in order left to right, replaced by anonymous symbols A, B, C, ..., Z, Aa, Ba, ..., Za, Ab, Bb, ... and so on.\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property.\n However, support for filters using partial string matching with this property is OPTIONAL (i.e., BEGINS WITH, ENDS WITH, and CONTAINS).\n\n- **Examples**:\n - `\"A2B\"`\n - `\"A42B42C16D12E10F9G5\"`\n\n- **Querying**:\n - A filter that matches an exactly given formula is `chemical_formula_anonymous=\"A2B\"`.", "nullable": true, - "x-optimade-queryable": "must", - "x-optimade-support": "should" + "x-optimade-support": "should", + "x-optimade-queryable": "must" }, "dimension_types": { "items": { @@ -3581,8 +3581,8 @@ "minItems": 3, "title": "Dimension Types", "description": "List of three integers.\nFor each of the three directions indicated by the three lattice vectors (see property `lattice_vectors`), this list indicates if the direction is periodic (value `1`) or non-periodic (value `0`).\nNote: the elements in this list each refer to the direction of the corresponding entry in `lattice_vectors` and *not* the Cartesian x, y, z directions.\n\n- **Type**: list of integers.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - MUST be a list of length 3.\n - Each integer element MUST assume only the value 0 or 1.\n\n- **Examples**:\n - For a molecule: `[0, 0, 0]`\n - For a wire along the direction specified by the third lattice vector: `[0, 0, 1]`\n - For a 2D surface/slab, periodic on the plane defined by the first and third lattice vectors: `[1, 0, 1]`\n - For a bulk 3D system: `[1, 1, 1]`", - "x-optimade-queryable": "optional", "x-optimade-support": "should", + "x-optimade-queryable": "optional", "nullable": true }, "nperiodic_dimensions": { @@ -3590,8 +3590,8 @@ "title": "Nperiodic Dimensions", "description": "An integer specifying the number of periodic dimensions in the structure, equivalent to the number of non-zero entries in `dimension_types`.\n\n- **Type**: integer\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - The integer value MUST be between 0 and 3 inclusive and MUST be equal to the sum of the items in the `dimension_types` property.\n - This property only reflects the treatment of the lattice vectors provided for the structure, and not any physical interpretation of the dimensionality of its contents.\n\n- **Examples**:\n - `2` should be indicated in cases where `dimension_types` is any of `[1, 1, 0]`, `[1, 0, 1]`, `[0, 1, 1]`.\n\n- **Query examples**:\n - Match only structures with exactly 3 periodic dimensions: `nperiodic_dimensions=3`\n - Match all structures with 2 or fewer periodic dimensions: `nperiodic_dimensions<=2`", "nullable": true, - "x-optimade-queryable": "must", - "x-optimade-support": "should" + "x-optimade-support": "should", + "x-optimade-queryable": "must" }, "lattice_vectors": { "items": { @@ -3607,9 +3607,9 @@ "minItems": 3, "title": "Lattice Vectors", "description": "The three lattice vectors in Cartesian coordinates, in \u00e5ngstr\u00f6m (\u00c5).\n\n- **Type**: list of list of floats or unknown values.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - MUST be a list of three vectors *a*, *b*, and *c*, where each of the vectors MUST BE a list of the vector's coordinates along the x, y, and z Cartesian coordinates.\n (Therefore, the first index runs over the three lattice vectors and the second index runs over the x, y, z Cartesian coordinates).\n - For databases that do not define an absolute Cartesian system (e.g., only defining the length and angles between vectors), the first lattice vector SHOULD be set along *x* and the second on the *xy*-plane.\n - MUST always contain three vectors of three coordinates each, independently of the elements of property `dimension_types`.\n The vectors SHOULD by convention be chosen so the determinant of the `lattice_vectors` matrix is different from zero.\n The vectors in the non-periodic directions have no significance beyond fulfilling these requirements.\n - The coordinates of the lattice vectors of non-periodic dimensions (i.e., those dimensions for which `dimension_types` is `0`) MAY be given as a list of all `null` values.\n If a lattice vector contains the value `null`, all coordinates of that lattice vector MUST be `null`.\n\n- **Examples**:\n - `[[4.0,0.0,0.0],[0.0,4.0,0.0],[0.0,1.0,4.0]]` represents a cell, where the first vector is `(4, 0, 0)`, i.e., a vector aligned along the `x` axis of length 4 \u00c5; the second vector is `(0, 4, 0)`; and the third vector is `(0, 1, 4)`.", + "x-optimade-support": "should", "x-optimade-queryable": "optional", "x-optimade-unit": "\u00c5", - "x-optimade-support": "should", "nullable": true }, "space_group_symmetry_operations_xyz": { @@ -3618,25 +3618,24 @@ "pattern": "^([-+]? [xyz] ([-+][xyz])? ([-+] (1/2|[12]/3|[1-3]/4|[1-5]/6) )?|[-+]? (1/2|[12]/3|[1-3]/4|[1-5]/6) ([-+] [xyz] ([-+][xyz])? )?),([-+]? [xyz] ([-+][xyz])? ([-+] (1/2|[12]/3|[1-3]/4|[1-5]/6) )?|[-+]? (1/2|[12]/3|[1-3]/4|[1-5]/6) ([-+] [xyz] ([-+][xyz])? )?),([-+]? [xyz] ([-+][xyz])? ([-+] (1/2|[12]/3|[1-3]/4|[1-5]/6) )?|[-+]? (1/2|[12]/3|[1-3]/4|[1-5]/6) ([-+] [xyz] ([-+][xyz])? )?)$" }, "type": "array", - "pattern": "^([-+]? [xyz] ([-+][xyz])? ([-+] (1/2|[12]/3|[1-3]/4|[1-5]/6) )?|[-+]? (1/2|[12]/3|[1-3]/4|[1-5]/6) ([-+] [xyz] ([-+][xyz])? )?),([-+]? [xyz] ([-+][xyz])? ([-+] (1/2|[12]/3|[1-3]/4|[1-5]/6) )?|[-+]? (1/2|[12]/3|[1-3]/4|[1-5]/6) ([-+] [xyz] ([-+][xyz])? )?),([-+]? [xyz] ([-+][xyz])? ([-+] (1/2|[12]/3|[1-3]/4|[1-5]/6) )?|[-+]? (1/2|[12]/3|[1-3]/4|[1-5]/6) ([-+] [xyz] ([-+][xyz])? )?)$", "title": "Space Group Symmetry Operations Xyz", "description": "A list of symmetry operations given as general position x, y and z coordinates in algebraic form.\n\nEach symmetry operation is described by a string that gives that symmetry operation in Jones' faithful representation (Bradley & Cracknell, 1972: pp. 35-37), adapted for computer string notation.\nThe letters x, y and z that are typesetted with overbars in printed text represent coordinate values multiplied by -1 and are encoded as -x, -y and -z, respectively.\nThe syntax of the strings representing symmetry operations MUST conform to regular expressions given in appendix The Symmetry Operation String Regular Expressions.\nThe interpretation of the strings MUST follow the conventions of the IUCr CIF core dictionary (IUCr, 2023).\nIn particular, this property MUST explicitly provide all symmetry operations needed to generate all the atoms in the unit cell from the atoms in the asymmetric unit, for the setting used.\nThis symmetry operation set MUST always include the `\"x,y,z\"` identity operation.\nThe symmetry operations are to be applied to fractional atom coordinates.\nIn case only Cartesian coordinates are available, these Cartesian coordinates must be converted to fractional coordinates before the application of the provided symmetry operations.\nIf the symmetry operation list is present, it MUST be compatible with other space group specifications (e.g. the ITC space group number, the Hall symbol, the Hermann-Mauguin symbol) if these are present.\n\n- **Type**: list of strings\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n However, the property is RECOMMENDED if coordinates are returned in a form to which these operations can or must be applied (e.g. fractional atom coordinates of an asymmetric unit).\n Moreover, the property is REQUIRED if symmetry operations are necessary to reconstruct the full model of the material and no other symmetry information (e.g., the Hall symbol) is provided that would allow the user to derive symmetry operations unambiguously.\n - MUST be null if `nperiodic_dimensions` is equal to 0.\n\n- **Examples**:\n - Space group operations for the space group with ITC number 3 (H-M symbol: P 2, extended H-M symbol: P 1 2 1, Hall symbol P 2y):\n ```\n [\"x,y,z\", \"-x,y,-z\"]\n ```\n - Space group operations for the space group with ITC number 5 (H-M symbol C 2, extended H-M symbol: C 1 2 1, Hall symbol C 2y):\n ```\n [\"x,y,z\", \"-x,y,-z\", \"x+1/2,y+1/2,z\", \"-x+1/2,y+1/2,-z\"]\n ```\n\n- **Notes**:\n The list of space group symmetry operations applies to the whole periodic array of atoms and together with the lattice translations given in the `lattice_vectors` property provides the necessary information to reconstruct all atom site positions of the periodic material.\n Thus, the symmetry operations described in this property are only applicable to material models with at least one periodic dimension.\n This property is not meant to represent arbitrary symmetries of molecules, non-periodic (finite) collections of atoms or non-crystallographic symmetry.\n\n- **Bibliographic References**:\n\n Bradley, C. J. and Cracknell, A. P. (1972) The Mathematical Theory of Symmetry in Solids. Oxford, Clarendon Press (paperback edition 2010) 745 p. ISBN 978-0-19-958258-7.\n\n IUCr (2023) Core dictionary (coreCIF) version 2.4.5; data name _space_group_symop_operation_xyz. Available from: https://www.iucr.org/__data/iucr/cifdic_html/1/cif_core.dic/Ispace_group_symop_operation_xyz.html [Accessed 2023-06-18T16:46+03:00].", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "space_group_hall": { "type": "string", "title": "Space Group Hall", "description": "A Hall space group symbol representing the symmetry of the structure as defined in (Hall, 1981, 1981a).\nThe change-of-basis operations are used as defined in the International Tables of Crystallography (ITC) Vol. B, Sect. 1.4, Appendix A1.4.2 (IUCr, 2001).\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - Each component of the Hall symbol MUST be separated by a single space symbol.\n - If there exists a standard Hall symbol which represents the symmetry it SHOULD be used.\n - MUST be null if `nperiodic_dimensions` is not equal to 3.\n\n- **Bibliographic References**:\n\n Hall, S. R. (1981) Space-group notation with an explicit origin. Acta Crystallographica Section A, 37, 517-525, International Union of Crystallography (IUCr), DOI: https://doi.org/10.1107/s0567739481001228\n\n Hall, S. R. (1981a) Space-group notation with an explicit origin; erratum. Acta Crystallographica Section A, 37, 921-921, International Union of Crystallography (IUCr), DOI: https://doi.org/10.1107/s0567739481001976\n\n IUCr (2001). International Tables for Crystallography vol. B. Reciprocal Space. Ed. U. Shmueli. 2-nd edition. Dordrecht/Boston/London, Kluwer Academic Publishers.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "space_group_symbol_hermann_mauguin": { "type": "string", "title": "Space Group Symbol Hermann Mauguin", "description": "A human- and machine-readable string containing the short Hermann-Mauguin (H-M) symbol which specifies the space group of the structure in the response.\nThe H-M symbol SHOULD aim to convey the closest representation of the symmetry information that can be specified using the short format used in the International Tables for Crystallography vol. A (IUCr, 2005), Table 4.3.2.1 as described in the accompanying text.\nThe symbol MAY be a non-standard short H-M symbol.\nThe H-M symbol does not unambiguously communicate the axis, cell, and origin choice, and the given symbol SHOULD NOT be amended to convey this information.\n\nTo encode as character strings, the following adaptations MUST be made when representing H-M symbols given in their typesetted form:\n - the overbar above the numbers MUST be changed to the minus sign in front of the digit (e.g. '-2');\n - subscripts that denote screw axes are written as digits immediately after the axis designator without a space (e.g. 'P 32')\n - the space group generators MUST be separated by a single space (e.g. 'P 21 21 2');\n - there MUST be no spaces in the space group generator designation (i.e. use 'P 21/m', not the 'P 21 / m');\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n\n- **Examples**:\n - `C 2`\n - `P 21 21 21`\n\n- **Bibliographic References**:\n\nIUCr (2005). International Tables for Crystallography vol. A. Space-Group Symmetry. Ed. Theo Hahn. 5-th edition. Dordrecht, Springer.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "space_group_it_number": { "type": "integer", @@ -3644,8 +3643,8 @@ "minimum": 1.0, "title": "Space Group It Number", "description": "Space group number for the structure assigned by the International Tables for Crystallography Vol. A.\n- **Type**: integer\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - The integer value MUST be between 1 and 230.\n - MUST be null if `nperiodic_dimensions` is not equal to 3.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "cartesian_site_positions": { "items": { @@ -3659,9 +3658,9 @@ "type": "array", "title": "Cartesian Site Positions", "description": "Cartesian positions of each site in the structure.\nA site is usually used to describe positions of atoms; what atoms can be encountered at a given site is conveyed by the `species_at_sites` property, and the species themselves are described in the `species` property.\n\n- **Type**: list of list of floats\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - It MUST be a list of length equal to the number of sites in the structure, where every element is a list of the three Cartesian coordinates of a site expressed as float values in the unit angstrom (\u00c5).\n - An entry MAY have multiple sites at the same Cartesian position (for a relevant use of this, see e.g., the property `assemblies`).\n\n- **Examples**:\n - `[[0,0,0],[0,0,2]]` indicates a structure with two sites, one sitting at the origin and one along the (positive) *z*-axis, 2 \u00c5 away from the origin.", + "x-optimade-support": "should", "x-optimade-queryable": "optional", "x-optimade-unit": "\u00c5", - "x-optimade-support": "should", "nullable": true }, "nsites": { @@ -3669,8 +3668,8 @@ "title": "Nsites", "description": "An integer specifying the length of the `cartesian_site_positions` property.\n\n- **Type**: integer\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `42`\n\n- **Query examples**:\n - Match only structures with exactly 4 sites: `nsites=4`\n - Match structures that have between 2 and 7 sites: `nsites>=2 AND nsites<=7`", "nullable": true, - "x-optimade-queryable": "must", - "x-optimade-support": "should" + "x-optimade-support": "should", + "x-optimade-queryable": "must" }, "species": { "items": { @@ -3680,8 +3679,8 @@ "title": "Species", "description": "A list describing the species of the sites of this structure.\nSpecies can represent pure chemical elements, virtual-crystal atoms representing a statistical occupation of a given site by multiple chemical elements, and/or a location to which there are attached atoms, i.e., atoms whose precise location are unknown beyond that they are attached to that position (frequently used to indicate hydrogen atoms attached to another element, e.g., a carbon with three attached hydrogens might represent a methyl group, -CH3).\n\n- **Type**: list of dictionary with keys:\n - `name`: string (REQUIRED)\n - `chemical_symbols`: list of strings (REQUIRED)\n - `concentration`: list of float (REQUIRED)\n - `attached`: list of strings (REQUIRED)\n - `nattached`: list of integers (OPTIONAL)\n - `mass`: list of floats (OPTIONAL)\n - `original_name`: string (OPTIONAL).\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - Each list member MUST be a dictionary with the following keys:\n - **name**: REQUIRED; gives the name of the species; the **name** value MUST be unique in the `species` list;\n - **chemical_symbols**: REQUIRED; MUST be a list of strings of all chemical elements composing this species.\n Each item of the list MUST be one of the following:\n - a valid chemical-element symbol, or\n - the special value `\"X\"` to represent a non-chemical element, or\n - the special value `\"vacancy\"` to represent that this site has a non-zero probability of having a vacancy (the respective probability is indicated in the `concentration` list, see below).\n\n If any one entry in the `species` list has a `chemical_symbols` list that is longer than 1 element, the correct flag MUST be set in the list `structure_features`.\n\n - **concentration**: REQUIRED; MUST be a list of floats, with same length as `chemical_symbols`.\n The numbers represent the relative concentration of the corresponding chemical symbol in this species.\n The numbers SHOULD sum to one. Cases in which the numbers do not sum to one typically fall only in the following two categories:\n\n - Numerical errors when representing float numbers in fixed precision, e.g. for two chemical symbols with concentrations `1/3` and `2/3`, the concentration might look something like `[0.33333333333, 0.66666666666]`. If the client is aware that the sum is not one because of numerical precision, it can renormalize the values so that the sum is exactly one.\n - Experimental errors in the data present in the database. In this case, it is the responsibility of the client to decide how to process the data.\n\n Note that concentrations are uncorrelated between different sites (even of the same species).\n\n - **attached**: OPTIONAL; if provided MUST be a list of length 1 or more of strings of chemical symbols for the elements attached to this site, or \"X\" for a non-chemical element.\n\n - **nattached**: OPTIONAL; if provided MUST be a list of length 1 or more of integers indicating the number of attached atoms of the kind specified in the value of the `attached` key.\n\n The implementation MUST include either both or none of the `attached` and `nattached` keys, and if they are provided, they MUST be of the same length.\n Furthermore, if they are provided, the `structure_features` property MUST include the string `site_attachments`.\n\n - **mass**: OPTIONAL. If present MUST be a list of floats, with the same length as `chemical_symbols`, providing element masses expressed in a.m.u.\n Elements denoting vacancies MUST have masses equal to 0.\n\n - **original_name**: OPTIONAL. Can be any valid Unicode string, and SHOULD contain (if specified) the name of the species that is used internally in the source database.\n\n Note: With regards to \"source database\", we refer to the immediate source being queried via the OPTIMADE API implementation.\n\n The main use of this field is for source databases that use species names, containing characters that are not allowed (see description of the list property `species_at_sites`).\n\n - For systems that have only species formed by a single chemical symbol, and that have at most one species per chemical symbol, SHOULD use the chemical symbol as species name (e.g., `\"Ti\"` for titanium, `\"O\"` for oxygen, etc.)\n However, note that this is OPTIONAL, and client implementations MUST NOT assume that the key corresponds to a chemical symbol, nor assume that if the species name is a valid chemical symbol, that it represents a species with that chemical symbol.\n This means that a species `{\"name\": \"C\", \"chemical_symbols\": [\"Ti\"], \"concentration\": [1.0]}` is valid and represents a titanium species (and *not* a carbon species).\n - It is NOT RECOMMENDED that a structure includes species that do not have at least one corresponding site.\n\n- **Examples**:\n - `[ {\"name\": \"Ti\", \"chemical_symbols\": [\"Ti\"], \"concentration\": [1.0]} ]`: any site with this species is occupied by a Ti atom.\n - `[ {\"name\": \"Ti\", \"chemical_symbols\": [\"Ti\", \"vacancy\"], \"concentration\": [0.9, 0.1]} ]`: any site with this species is occupied by a Ti atom with 90 % probability, and has a vacancy with 10 % probability.\n - `[ {\"name\": \"BaCa\", \"chemical_symbols\": [\"vacancy\", \"Ba\", \"Ca\"], \"concentration\": [0.05, 0.45, 0.5], \"mass\": [0.0, 137.327, 40.078]} ]`: any site with this species is occupied by a Ba atom with 45 % probability, a Ca atom with 50 % probability, and by a vacancy with 5 % probability. The mass of this site is (on average) 88.5 a.m.u.\n - `[ {\"name\": \"C12\", \"chemical_symbols\": [\"C\"], \"concentration\": [1.0], \"mass\": [12.0]} ]`: any site with this species is occupied by a carbon isotope with mass 12.\n - `[ {\"name\": \"C13\", \"chemical_symbols\": [\"C\"], \"concentration\": [1.0], \"mass\": [13.0]} ]`: any site with this species is occupied by a carbon isotope with mass 13.\n - `[ {\"name\": \"CH3\", \"chemical_symbols\": [\"C\"], \"concentration\": [1.0], \"attached\": [\"H\"], \"nattached\": [3]} ]`: any site with this species is occupied by a methyl group, -CH3, which is represented without specifying precise positions of the hydrogen atoms.", "nullable": true, - "x-optimade-queryable": "optional", - "x-optimade-support": "should" + "x-optimade-support": "should", + "x-optimade-queryable": "optional" }, "species_at_sites": { "items": { @@ -3691,8 +3690,8 @@ "title": "Species At Sites", "description": "Name of the species at each site (where values for sites are specified with the same order of the property `cartesian_site_positions`).\nThe properties of the species are found in the property `species`.\n\n- **Type**: list of strings.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - MUST have length equal to the number of sites in the structure (first dimension of the list property `cartesian_site_positions`).\n - Each species name mentioned in the `species_at_sites` list MUST be described in the list property `species` (i.e. for each value in the `species_at_sites` list there MUST exist exactly one dictionary in the `species` list with the `name` attribute equal to the corresponding `species_at_sites` value).\n - Each site MUST be associated only to a single species.\n **Note**: However, species can represent mixtures of atoms, and multiple species MAY be defined for the same chemical element.\n This latter case is useful when different atoms of the same type need to be grouped or distinguished, for instance in simulation codes to assign different initial spin states.\n\n- **Examples**:\n - `[\"Ti\",\"O2\"]` indicates that the first site is hosting a species labeled `\"Ti\"` and the second a species labeled `\"O2\"`.\n - `[\"Ac\", \"Ac\", \"Ag\", \"Ir\"]` indicating the first two sites contains the `\"Ac\"` species, while the third and fourth sites contain the `\"Ag\"` and `\"Ir\"` species, respectively.", "nullable": true, - "x-optimade-queryable": "optional", - "x-optimade-support": "should" + "x-optimade-support": "should", + "x-optimade-queryable": "optional" }, "assemblies": { "items": { @@ -3701,8 +3700,8 @@ "type": "array", "title": "Assemblies", "description": "A description of groups of sites that are statistically correlated.\n\n- **Type**: list of dictionary with keys:\n - `sites_in_groups`: list of list of integers (REQUIRED)\n - `group_probabilities`: list of floats (REQUIRED)\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - The property SHOULD be `null` for entries that have no partial occupancies.\n - If present, the correct flag MUST be set in the list `structure_features`.\n - Client implementations MUST check its presence (as its presence changes the interpretation of the structure).\n - If present, it MUST be a list of dictionaries, each of which represents an assembly and MUST have the following two keys:\n - **sites_in_groups**: Index of the sites (0-based) that belong to each group for each assembly.\n\n Example: `[[1], [2]]`: two groups, one with the second site, one with the third.\n Example: `[[1,2], [3]]`: one group with the second and third site, one with the fourth.\n\n - **group_probabilities**: Statistical probability of each group. It MUST have the same length as `sites_in_groups`.\n It SHOULD sum to one.\n See below for examples of how to specify the probability of the occurrence of a vacancy.\n The possible reasons for the values not to sum to one are the same as already specified above for the `concentration` of each `species`.\n\n - If a site is not present in any group, it means that it is present with 100 % probability (as if no assembly was specified).\n - A site MUST NOT appear in more than one group.\n\n- **Examples** (for each entry of the assemblies list):\n - `{\"sites_in_groups\": [[0], [1]], \"group_probabilities: [0.3, 0.7]}`: the first site and the second site never occur at the same time in the unit cell.\n Statistically, 30 % of the times the first site is present, while 70 % of the times the second site is present.\n - `{\"sites_in_groups\": [[1,2], [3]], \"group_probabilities: [0.3, 0.7]}`: the second and third site are either present together or not present; they form the first group of atoms for this assembly.\n The second group is formed by the fourth site.\n Sites of the first group (the second and the third) are never present at the same time as the fourth site.\n 30 % of times sites 1 and 2 are present (and site 3 is absent); 70 % of times site 3 is present (and sites 1 and 2 are absent).\n\n- **Notes**:\n - Assemblies are essential to represent, for instance, the situation where an atom can statistically occupy two different positions (sites).\n\n - By defining groups, it is possible to represent, e.g., the case where a functional molecule (and not just one atom) is either present or absent (or the case where it it is present in two conformations)\n\n - Considerations on virtual alloys and on vacancies: In the special case of a virtual alloy, these specifications allow two different, equivalent ways of specifying them.\n For instance, for a site at the origin with 30 % probability of being occupied by Si, 50 % probability of being occupied by Ge, and 20 % of being a vacancy, the following two representations are possible:\n\n - Using a single species:\n ```json\n {\n \"cartesian_site_positions\": [[0,0,0]],\n \"species_at_sites\": [\"SiGe-vac\"],\n \"species\": [\n {\n \"name\": \"SiGe-vac\",\n \"chemical_symbols\": [\"Si\", \"Ge\", \"vacancy\"],\n \"concentration\": [0.3, 0.5, 0.2]\n }\n ]\n // ...\n }\n ```\n\n - Using multiple species and the assemblies:\n ```json\n {\n \"cartesian_site_positions\": [ [0,0,0], [0,0,0], [0,0,0] ],\n \"species_at_sites\": [\"Si\", \"Ge\", \"vac\"],\n \"species\": [\n { \"name\": \"Si\", \"chemical_symbols\": [\"Si\"], \"concentration\": [1.0] },\n { \"name\": \"Ge\", \"chemical_symbols\": [\"Ge\"], \"concentration\": [1.0] },\n { \"name\": \"vac\", \"chemical_symbols\": [\"vacancy\"], \"concentration\": [1.0] }\n ],\n \"assemblies\": [\n {\n \"sites_in_groups\": [ [0], [1], [2] ],\n \"group_probabilities\": [0.3, 0.5, 0.2]\n }\n ]\n // ...\n }\n ```\n\n - It is up to the database provider to decide which representation to use, typically depending on the internal format in which the structure is stored.\n However, given a structure identified by a unique ID, the API implementation MUST always provide the same representation for it.\n\n - The probabilities of occurrence of different assemblies are uncorrelated.\n So, for instance in the following case with two assemblies:\n ```json\n {\n \"assemblies\": [\n {\n \"sites_in_groups\": [ [0], [1] ],\n \"group_probabilities\": [0.2, 0.8],\n },\n {\n \"sites_in_groups\": [ [2], [3] ],\n \"group_probabilities\": [0.3, 0.7]\n }\n ]\n }\n ```\n\n Site 0 is present with a probability of 20 % and site 1 with a probability of 80 %. These two sites are correlated (either site 0 or 1 is present). Similarly, site 2 is present with a probability of 30 % and site 3 with a probability of 70 %.\n These two sites are correlated (either site 2 or 3 is present).\n However, the presence or absence of sites 0 and 1 is not correlated with the presence or absence of sites 2 and 3 (in the specific example, the pair of sites (0, 2) can occur with 0.2*0.3 = 6 % probability; the pair (0, 3) with 0.2*0.7 = 14 % probability; the pair (1, 2) with 0.8*0.3 = 24 % probability; and the pair (1, 3) with 0.8*0.7 = 56 % probability).", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "structure_features": { "items": { @@ -3711,8 +3710,8 @@ "type": "array", "title": "Structure Features", "description": "A list of strings that flag which special features are used by the structure.\n\n- **Type**: list of strings\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property.\n Filters on the list MUST support all mandatory HAS-type queries.\n Filter operators for comparisons on the string components MUST support equality, support for other comparison operators are OPTIONAL.\n - MUST be an empty list if no special features are used.\n - MUST be sorted alphabetically.\n - If a special feature listed below is used, the list MUST contain the corresponding string.\n - If a special feature listed below is not used, the list MUST NOT contain the corresponding string.\n - **List of strings used to indicate special structure features**:\n - `disorder`: this flag MUST be present if any one entry in the `species` list has a `chemical_symbols` list that is longer than 1 element.\n - `implicit_atoms`: this flag MUST be present if the structure contains atoms that are not assigned to sites via the property `species_at_sites` (e.g., because their positions are unknown).\n When this flag is present, the properties related to the chemical formula will likely not match the type and count of atoms represented by the `species_at_sites`, `species` and `assemblies` properties.\n - `site_attachments`: this flag MUST be present if any one entry in the `species` list includes `attached` and `nattached`.\n - `assemblies`: this flag MUST be present if the property `assemblies` is present.\n\n- **Examples**: A structure having implicit atoms and using assemblies: `[\"assemblies\", \"implicit_atoms\"]`", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" } }, "type": "object", diff --git a/optimade/models/structures.py b/optimade/models/structures.py index a9b819500..f71aa071f 100644 --- a/optimade/models/structures.py +++ b/optimade/models/structures.py @@ -4,7 +4,7 @@ from enum import Enum, IntEnum from typing import Optional, Union -from pydantic import BaseModel, conint, conlist, root_validator, validator +from pydantic import BaseModel, conint, conlist, constr, root_validator, validator from optimade.models.entries import EntryResource, EntryResourceAttributes from optimade.models.utils import ( @@ -40,6 +40,7 @@ Vector3D = conlist(float, min_items=3, max_items=3) Vector3D_unknown = conlist(Union[float, None], min_items=3, max_items=3) +SymOp = constr(regex=SPACE_GROUP_SYMMETRY_OPERATION_REGEX) class Periodicity(IntEnum): @@ -524,7 +525,7 @@ class StructureResourceAttributes(EntryResourceAttributes): queryable=SupportLevel.OPTIONAL, ) - space_group_symmetry_operations_xyz: Optional[list[str]] = OptimadeField( + space_group_symmetry_operations_xyz: Optional[list[SymOp]] = OptimadeField( # type: ignore[valid-type] None, description="""A list of symmetry operations given as general position x, y and z coordinates in algebraic form. @@ -568,7 +569,6 @@ class StructureResourceAttributes(EntryResourceAttributes): IUCr (2023) Core dictionary (coreCIF) version 2.4.5; data name _space_group_symop_operation_xyz. Available from: https://www.iucr.org/__data/iucr/cifdic_html/1/cif_core.dic/Ispace_group_symop_operation_xyz.html [Accessed 2023-06-18T16:46+03:00].""", support=SupportLevel.OPTIONAL, queryable=SupportLevel.OPTIONAL, - regex=SPACE_GROUP_SYMMETRY_OPERATION_REGEX, ) space_group_hall: Optional[str] = OptimadeField( From b883af784a20d2c40117626d1f02133cc680e769 Mon Sep 17 00:00:00 2001 From: Matthew Evans Date: Tue, 6 Dec 2022 23:03:26 +0000 Subject: [PATCH 04/19] Add test cases for fuzzy list comparison in grammar --- tests/filterparser/test_filterparser.py | 43 +++++++++++++------------ 1 file changed, 23 insertions(+), 20 deletions(-) diff --git a/tests/filterparser/test_filterparser.py b/tests/filterparser/test_filterparser.py index 5a01130b9..127825ea2 100644 --- a/tests/filterparser/test_filterparser.py +++ b/tests/filterparser/test_filterparser.py @@ -271,23 +271,26 @@ class TestParserV1_2_0(TestParserV1_0_0): version = (1, 2, 0) variant = "develop" - def test_boolean_values(self): - assert isinstance( - self.parse("_exmpl_element_counts = TRUE"), - Tree, - ) - - assert isinstance( - self.parse("_exmpl_element_counts = FALSE"), - Tree, - ) - - assert isinstance( - self.parse("_exmpl_element_counts != FALSE"), - Tree, - ) - - assert isinstance( - self.parse("NOT _exmpl_element_counts = TRUE"), - Tree, - ) + @pytest.mark.parametrize( + "case", + [ + "_exmpl_element_counts = TRUE", + "_exmpl_element_counts = FALSE", + "_exmpl_element_counts != FALSE", + "_exmpl_element_counts != FALSE", + "NOT _exmpl_element_counts = TRUE", + ], + ) + def test_good_boolean_value_queries(self, case): + assert isinstance(self.parse(case), Tree) + + @pytest.mark.parametrize( + "case", + [ + 'name:surname HAS STARTS WITH "J":CONTAINS "Doe"', + 'title HAS ENDS WITH "MOF"', + 'elements HAS ALL STARTS WITH "S"', + ], + ) + def test_fuzzy_list_comparisons(self, case): + assert isinstance(self.parse(case), Tree) From 6a8726f4d57660fcb33aa015cc89091efee65b56 Mon Sep 17 00:00:00 2001 From: Matthew Evans Date: Tue, 6 Dec 2022 22:45:54 +0000 Subject: [PATCH 05/19] Initial implementation of recursive JSONSchema-based property definitions --- openapi/index_openapi.json | 20 +- openapi/openapi.json | 623 ++++++++++++++++++++++--------- optimade/models/entries.py | 283 +++++++++++++- optimade/models/optimade_json.py | 11 + optimade/models/utils.py | 7 + 5 files changed, 749 insertions(+), 195 deletions(-) diff --git a/openapi/index_openapi.json b/openapi/index_openapi.json index 62c29ef4a..337e33d09 100644 --- a/openapi/index_openapi.json +++ b/openapi/index_openapi.json @@ -498,15 +498,15 @@ "type": "string", "title": "Id", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "type": { "type": "string", "title": "Type", "description": "The name of the type of an entry.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - MUST be an existing entry type.\n - The entry of type `` and ID `` MUST be returned in response to a request for `//` under the versioned base URL.\n\n- **Example**: `\"structures\"`", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "links": { "allOf": [ @@ -560,16 +560,16 @@ "type": "string", "title": "Immutable Id", "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", - "x-optimade-support": "optional", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "optional" }, "last_modified": { "type": "string", "format": "date-time", "title": "Last Modified", "description": "Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n - As part of JSON response format: `\"2007-04-05T14:30:20Z\"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)", - "x-optimade-support": "should", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "should" } }, "type": "object", @@ -1107,8 +1107,8 @@ "type": "string", "title": "Id", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "type": { "type": "string", diff --git a/openapi/openapi.json b/openapi/openapi.json index 55ae3d7e5..2919f7313 100644 --- a/openapi/openapi.json +++ b/openapi/openapi.json @@ -1323,6 +1323,18 @@ "title": "Aggregate", "description": "Enumeration of aggregate values" }, + "AllowedJSONSchemaDataType": { + "enum": [ + "boolean", + "object", + "array", + "number", + "string", + "integer" + ], + "title": "AllowedJSONSchemaDataType", + "description": "The allowed values for `type` in the Property Definition restricted JSON Schema syntax." + }, "Assembly": { "properties": { "sites_in_groups": { @@ -1335,8 +1347,8 @@ "type": "array", "title": "Sites In Groups", "description": "Index of the sites (0-based) that belong to each group for each assembly.\n\n- **Examples**:\n - `[[1], [2]]`: two groups, one with the second site, one with the third.\n - `[[1,2], [3]]`: one group with the second and third site, one with the fourth.", - "x-optimade-support": "must", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "must" }, "group_probabilities": { "items": { @@ -1345,8 +1357,8 @@ "type": "array", "title": "Group Probabilities", "description": "Statistical probability of each group. It MUST have the same length as `sites_in_groups`.\nIt SHOULD sum to one.\nSee below for examples of how to specify the probability of the occurrence of a vacancy.\nThe possible reasons for the values not to sum to one are the same as already specified above for the `concentration` of each `species`.", - "x-optimade-support": "must", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "must" } }, "type": "object", @@ -1561,50 +1573,93 @@ "title": "BaseRelationshipResource", "description": "Minimum requirements to represent a relationship resource" }, - "DataType": { - "enum": [ - "string", - "integer", - "float", - "boolean", - "timestamp", - "list", - "dictionary", - "unknown" - ], - "title": "DataType", - "description": "Optimade Data Types\n\nSee the section \"Data types\" in the OPTIMADE API specification for more information." - }, "EntryInfoProperty": { "properties": { + "title": { + "type": "string", + "title": "Title", + "description": "A short single-line human-readable explanation of the defined property appropriate to show as part of a user interface." + }, "description": { "type": "string", "title": "Description", - "description": "A human-readable description of the entry property" + "description": "A human-readable multi-line description that explains the purpose, requirements, and conventions of the defined property.\n\nThe 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.\nFormatting in the text SHOULD use Markdown in the CommonMark v0.3 format." }, - "unit": { + "x-optimade-property": { + "allOf": [ + { + "$ref": "#/components/schemas/OptimadePropertyDefinition" + } + ], + "title": "X-Optimade-Property", + "description": "Additional information to define the property that is not covered by fields in the JSON Schema standard." + }, + "x-optimade-unit": { "type": "string", - "title": "Unit", - "description": "The physical unit of the entry property.\nThis MUST be a valid representation of units according to version 2.1 of [The Unified Code for Units of Measure](https://unitsofmeasure.org/ucum.html).\nIt is RECOMMENDED that non-standard (non-SI) units are described in the description for the property." + "title": "X-Optimade-Unit", + "description": "A (compound) symbol for the physical unit in which the value of the defined property is given or one of the strings `dimensionless` or `inapplicable`." }, - "sortable": { - "type": "boolean", - "title": "Sortable", - "description": "Defines whether the entry property can be used for sorting with the \"sort\" parameter.\nIf the entry listing endpoint supports sorting, this key MUST be present for sortable properties with value `true`." + "x-optimade-implementation": { + "allOf": [ + { + "$ref": "#/components/schemas/PropertyImplementationInfo" + } + ], + "title": "X-Optimade-Implementation", + "description": "A dictionary describing the level of OPTIMADE API functionality provided by the present implementation.\nIf an implementation omits this field in its response, a client interacting with that implementation SHOULD NOT make any assumptions about the availability of these features." }, - "type": { + "x-optimade-requirements": { "allOf": [ { - "$ref": "#/components/schemas/DataType" + "$ref": "#/components/schemas/PropertyRequirementsInfo" + } + ], + "title": "X-Optimade-Requirements", + "description": "A dictionary describing the level of OPTIMADE API functionality required by all implementations of this property.\nOmitting this field means the corresponding functionality is OPTIONAL." + }, + "type": { + "anyOf": [ + { + "$ref": "#/components/schemas/AllowedJSONSchemaDataType" + }, + { + "items": { + "$ref": "#/components/schemas/AllowedJSONSchemaDataType" + }, + "type": "array" } ], "title": "Type", - "description": "The type of the property's value.\nThis MUST be any of the types defined in the Data types section.\nFor the purpose of compatibility with future versions of this specification, a client MUST accept values that are not `string` values specifying any of the OPTIMADE Data types, but MUST then also disregard the `type` field.\nNote, if the value is a nested type, only the outermost type should be reported.\nE.g., for the entry resource `structures`, the `species` property is defined as a list of dictionaries, hence its `type` value would be `list`." + "description": "A string or list that specifies the type of the defined property.\nIt MUST be one of:\n\n- One of the strings `\"boolean\"`, `\"object\"` (refers to an OPTIMADE dictionary), `\"array\"` (refers to an OPTIMADE list), `\"number\"` (refers to an OPTIMADE float), `\"string\"`, or `\"integer\"`.\n- A list where the first item MUST be one of the strings above, and the second item MUST be the string `\"null\"`." + }, + "deprecated": { + "type": "boolean", + "title": "Deprecated", + "description": " If `TRUE`, implementations SHOULD not use the defined property, and it MAY be removed in the future.\nIf `FALSE`, the defined property is not deprecated.\nThe field not being present means `FALSE`." + }, + "enum": { + "items": {}, + "type": "array", + "title": "Enum", + "description": "The defined property MUST take one of the values given in the provided list.\nThe 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.\nIf 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\"`." + }, + "examples": { + "items": {}, + "type": "array", + "title": "Examples", + "description": "A list of example values that the defined property can have.\nThese examples MUST all be of a data type that matches the `type` field and otherwise adhere to the rest of the Property Description." } }, "type": "object", "required": [ - "description" + "title", + "description", + "x-optimade-property", + "x-optimade-implementation", + "x-optimade-requirements", + "deprecated", + "enum", + "examples" ], "title": "EntryInfoProperty" }, @@ -1748,15 +1803,15 @@ "type": "string", "title": "Id", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "type": { "type": "string", "title": "Type", "description": "The name of the type of an entry.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - MUST be an existing entry type.\n - The entry of type `` and ID `` MUST be returned in response to a request for `//` under the versioned base URL.\n\n- **Example**: `\"structures\"`", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "links": { "allOf": [ @@ -1810,16 +1865,16 @@ "type": "string", "title": "Immutable Id", "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", - "x-optimade-support": "optional", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "optional" }, "last_modified": { "type": "string", "format": "date-time", "title": "Last Modified", "description": "Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n - As part of JSON response format: `\"2007-04-05T14:30:20Z\"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)", - "x-optimade-support": "should", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "should" } }, "type": "object", @@ -2216,8 +2271,8 @@ "type": "string", "title": "Id", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "type": { "type": "string", @@ -2440,6 +2495,15 @@ "title": "Meta", "description": "Non-standard meta-information that can not be represented as an attribute or relationship." }, + "OptimadeAllowedUnitStandard": { + "enum": [ + "gnu units", + "ucum", + "qudt" + ], + "title": "OptimadeAllowedUnitStandard", + "description": "An enumeration." + }, "OptimadeError": { "properties": { "id": { @@ -2502,6 +2566,101 @@ "title": "OptimadeError", "description": "detail MUST be present" }, + "OptimadePropertyDefinition": { + "properties": { + "property-uri": { + "type": "string", + "title": "Property-Uri", + "description": "A static URI identifier that is a URN or URL representing the specific version of the property.\nIt SHOULD NOT be changed as long as the property definition remains the same, and SHOULD be changed when the property definition changes.\n(If it is a URL, clients SHOULD NOT assign any interpretation to the response when resolving that URL.)" + }, + "version": { + "type": "string", + "title": "Version", + "description": "This string indicates the version of the property definition.\nThe string SHOULD be in the format described by the [semantic versioning v2](https://semver.org/spec/v2.0.0.html) standard." + }, + "unit-definitions": { + "items": { + "$ref": "#/components/schemas/OptimadeUnitDefinition" + }, + "type": "array", + "title": "Unit-Definitions", + "description": "A list of definitions of the symbols used in the Property Definition (including its nested levels) for physical units given as values of the `x-optimade-unit` field.\nThis field MUST be included if the defined property, at any level, includes an `x-optimade-unit` with a value that is not `dimensionless` or `inapplicable`." + }, + "resource-uris": { + "items": { + "$ref": "#/components/schemas/PropertyRemoteResource" + }, + "type": "array", + "title": "Resource-Uris", + "description": "A list of dictionaries that references remote resources that describe the property." + } + }, + "type": "object", + "required": [ + "property-uri", + "version", + "unit-definitions", + "resource-uris" + ], + "title": "OptimadePropertyDefinition" + }, + "OptimadeUnitDefinition": { + "properties": { + "symbol": { + "type": "string", + "title": "Symbol" + }, + "title": { + "type": "string", + "title": "Title" + }, + "description": { + "type": "string", + "title": "Description" + }, + "standard": { + "$ref": "#/components/schemas/OptimadeUnitStandard" + }, + "resource-uris": { + "items": { + "$ref": "#/components/schemas/UnitResourceURIs" + }, + "type": "array", + "title": "Resource-Uris" + } + }, + "type": "object", + "required": [ + "symbol", + "title", + "description", + "standard", + "resource-uris" + ], + "title": "OptimadeUnitDefinition" + }, + "OptimadeUnitStandard": { + "properties": { + "name": { + "$ref": "#/components/schemas/OptimadeAllowedUnitStandard" + }, + "version": { + "type": "string", + "title": "Version" + }, + "symbol": { + "type": "string", + "title": "Symbol" + } + }, + "type": "object", + "required": [ + "name", + "version", + "symbol" + ], + "title": "OptimadeUnitStandard" + }, "Periodicity": { "type": "integer", "enum": [ @@ -2517,22 +2676,22 @@ "type": "string", "title": "Name", "description": "Full name of the person, REQUIRED.", - "x-optimade-support": "must", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "must" }, "firstname": { "type": "string", "title": "Firstname", "description": "First name of the person.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "lastname": { "type": "string", "title": "Lastname", "description": "Last name of the person.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" } }, "type": "object", @@ -2542,6 +2701,99 @@ "title": "Person", "description": "A person, i.e., an author, editor or other." }, + "PropertyImplementationInfo": { + "properties": { + "sortable": { + "type": "boolean", + "title": "Sortable", + "description": "If `TRUE`, specifies that results can be sorted on this property.\n If `FALSE`, specifies that results cannot be sorted on this property.\n Omitting the field is equivalent to `FALSE`." + }, + "query-support": { + "allOf": [ + { + "$ref": "#/components/schemas/QuerySupport" + } + ], + "description": "Defines a required level of support in formulating queries on this field.\n\n The string MUST be one of the following:\n\n - `all mandatory`: the defined property MUST be queryable using the OPTIMADE filter language with support for all mandatory filter features.\n - `equality only`: the defined property MUST be queryable using the OPTIMADE filter language equality and inequality operators. Other filter language features do not need to be available.\n - `partial`: the defined property MUST be queryable with support for a subset of the filter language operators as specified by the field `query-support-operators`.\n - `none`: the defined property does not need to be queryable with any features of the filter language." + }, + "query-support-operators": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Query-Support-Operators", + "description": "Defines the filter language features supported on this property.\n\nEach string in the list MUST be one of `<`, `<=`, `>`, `>=`, `=`, `!=`, `CONTAINS`, `STARTS WITH`, `ENDS WITH`:, `HAS`, `HAS ALL`, `HAS ANY`, `HAS ONLY`, `IS KNOWN`, `IS UNKNOWN` with the following meanings:\n\n- `<`, `<=`, `>`, `>=`, `=`, `!=`: indicating support for filtering this property using the respective operator.\n If the property is of Boolean type, support for `=` also designates support for boolean comparisons with the property being true that omit \":filter-fragment:`= TRUE`\", e.g., specifying that filtering for \"`is_yellow = TRUE`\" is supported also implies support for \"`is_yellow`\" (which means the same thing).\n Support for \"`NOT is_yellow`\" also follows.\n\n- `CONTAINS`, `STARTS WITH`, `ENDS WITH`: indicating support for substring filtering of this property using the respective operator. MUST NOT appear if the property is not of type String.\n\n- `HAS`, `HAS ALL`, `HAS ANY`: indicating support of the MANDATORY features for list property comparison using the respective operator. MUST NOT appear if the property is not of type List.\n\n- `HAS ONLY`: indicating support for list property comparison with all or a subset of the OPTIONAL constructs using this operator. MUST NOT appear if the property is not of type List.\n\n- `IS KNOWN`, `IS UNKNOWN`: indicating support for filtering this property on unknown values using the respective operator." + } + }, + "type": "object", + "required": [ + "sortable", + "query-support", + "query-support-operators" + ], + "title": "PropertyImplementationInfo" + }, + "PropertyRemoteResource": { + "properties": { + "relation": { + "type": "string", + "title": "Relation", + "description": "A human-readable description of the relationship between the property and the remote resource, e.g., a 'natural language description'." + }, + "uri": { + "type": "string", + "title": "Uri", + "description": "A URI of the external resource (which MAY be a resolvable URL)." + } + }, + "type": "object", + "required": [ + "relation", + "uri" + ], + "title": "PropertyRemoteResource" + }, + "PropertyRequirementsInfo": { + "properties": { + "sortable": { + "type": "boolean", + "title": "Sortable", + "description": "If `TRUE`, specifies that results can be sorted on this property.\n If `FALSE`, specifies that results cannot be sorted on this property.\n Omitting the field is equivalent to `FALSE`." + }, + "query-support": { + "allOf": [ + { + "$ref": "#/components/schemas/QuerySupport" + } + ], + "description": "Defines a required level of support in formulating queries on this field.\n\n The string MUST be one of the following:\n\n - `all mandatory`: the defined property MUST be queryable using the OPTIMADE filter language with support for all mandatory filter features.\n - `equality only`: the defined property MUST be queryable using the OPTIMADE filter language equality and inequality operators. Other filter language features do not need to be available.\n - `partial`: the defined property MUST be queryable with support for a subset of the filter language operators as specified by the field `query-support-operators`.\n - `none`: the defined property does not need to be queryable with any features of the filter language." + }, + "query-support-operators": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Query-Support-Operators", + "description": "Defines the filter language features supported on this property.\n\nEach string in the list MUST be one of `<`, `<=`, `>`, `>=`, `=`, `!=`, `CONTAINS`, `STARTS WITH`, `ENDS WITH`:, `HAS`, `HAS ALL`, `HAS ANY`, `HAS ONLY`, `IS KNOWN`, `IS UNKNOWN` with the following meanings:\n\n- `<`, `<=`, `>`, `>=`, `=`, `!=`: indicating support for filtering this property using the respective operator.\n If the property is of Boolean type, support for `=` also designates support for boolean comparisons with the property being true that omit \":filter-fragment:`= TRUE`\", e.g., specifying that filtering for \"`is_yellow = TRUE`\" is supported also implies support for \"`is_yellow`\" (which means the same thing).\n Support for \"`NOT is_yellow`\" also follows.\n\n- `CONTAINS`, `STARTS WITH`, `ENDS WITH`: indicating support for substring filtering of this property using the respective operator. MUST NOT appear if the property is not of type String.\n\n- `HAS`, `HAS ALL`, `HAS ANY`: indicating support of the MANDATORY features for list property comparison using the respective operator. MUST NOT appear if the property is not of type List.\n\n- `HAS ONLY`: indicating support for list property comparison with all or a subset of the OPTIONAL constructs using this operator. MUST NOT appear if the property is not of type List.\n\n- `IS KNOWN`, `IS UNKNOWN`: indicating support for filtering this property on unknown values using the respective operator." + }, + "support": { + "allOf": [ + { + "$ref": "#/components/schemas/SupportLevel" + } + ], + "description": "Describes the minimal required level of support for the Property by an implementation.\n\n This field SHOULD only appear in a `x-optimade-requirements` that is at the outermost level of a Property Definition, as the meaning of its inclusion on other levels is not defined.\n The string MUST be one of the following:\n\n - `must`: the defined property MUST be recognized by the implementation (e.g., in filter strings) and MUST NOT be `null`.\n - `should`: the defined property MUST be recognized by the implementation (e.g., in filter strings) and SHOULD NOT be `null`.\n - `may`: it is OPTIONAL for the implementation to recognize the defined property and it MAY be equal to `null`." + } + }, + "type": "object", + "required": [ + "sortable", + "query-support", + "query-support-operators", + "support" + ], + "title": "PropertyRequirementsInfo" + }, "Provider": { "properties": { "name": { @@ -2585,6 +2837,16 @@ "title": "Provider", "description": "Information on the database provider of the implementation." }, + "QuerySupport": { + "enum": [ + "all mandatory", + "equality only", + "partial", + "none" + ], + "title": "QuerySupport", + "description": "An enumeration." + }, "ReferenceRelationship": { "properties": { "links": { @@ -2632,8 +2894,8 @@ "type": "string", "title": "Id", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "type": { "type": "string", @@ -2641,8 +2903,8 @@ "title": "Type", "description": "The name of the type of an entry.\n- **Type**: string.\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - MUST be an existing entry type.\n - The entry of type and ID MUST be returned in response to a request for `//` under the versioned base URL.\n- **Example**: `\"structures\"`", "default": "references", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "links": { "allOf": [ @@ -2690,16 +2952,16 @@ "type": "string", "title": "Immutable Id", "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", - "x-optimade-support": "optional", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "optional" }, "last_modified": { "type": "string", "format": "date-time", "title": "Last Modified", "description": "Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n - As part of JSON response format: `\"2007-04-05T14:30:20Z\"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)", - "x-optimade-support": "should", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "should" }, "authors": { "items": { @@ -2708,8 +2970,8 @@ "type": "array", "title": "Authors", "description": "List of person objects containing the authors of the reference.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "editors": { "items": { @@ -2718,15 +2980,15 @@ "type": "array", "title": "Editors", "description": "List of person objects containing the editors of the reference.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "doi": { "type": "string", "title": "Doi", "description": "The digital object identifier of the reference.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "url": { "type": "string", @@ -2735,162 +2997,162 @@ "format": "uri", "title": "Url", "description": "The URL of the reference.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "address": { "type": "string", "title": "Address", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "annote": { "type": "string", "title": "Annote", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "booktitle": { "type": "string", "title": "Booktitle", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "chapter": { "type": "string", "title": "Chapter", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "crossref": { "type": "string", "title": "Crossref", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "edition": { "type": "string", "title": "Edition", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "howpublished": { "type": "string", "title": "Howpublished", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "institution": { "type": "string", "title": "Institution", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "journal": { "type": "string", "title": "Journal", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "key": { "type": "string", "title": "Key", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "month": { "type": "string", "title": "Month", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "note": { "type": "string", "title": "Note", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "number": { "type": "string", "title": "Number", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "organization": { "type": "string", "title": "Organization", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "pages": { "type": "string", "title": "Pages", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "publisher": { "type": "string", "title": "Publisher", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "school": { "type": "string", "title": "School", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "series": { "type": "string", "title": "Series", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "title": { "type": "string", "title": "Title", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "bib_type": { "type": "string", "title": "Bib Type", "description": "Type of the reference, corresponding to the **type** property in the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "volume": { "type": "string", "title": "Volume", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "year": { "type": "string", "title": "Year", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" } }, "type": "object", @@ -3310,8 +3572,8 @@ "type": "string", "title": "Name", "description": "Gives the name of the species; the **name** value MUST be unique in the `species` list.", - "x-optimade-support": "must", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "must" }, "chemical_symbols": { "items": { @@ -3320,8 +3582,8 @@ "type": "array", "title": "Chemical Symbols", "description": "MUST be a list of strings of all chemical elements composing this species. Each item of the list MUST be one of the following:\n\n- a valid chemical-element symbol, or\n- the special value `\"X\"` to represent a non-chemical element, or\n- the special value `\"vacancy\"` to represent that this site has a non-zero probability of having a vacancy (the respective probability is indicated in the `concentration` list, see below).\n\nIf any one entry in the `species` list has a `chemical_symbols` list that is longer than 1 element, the correct flag MUST be set in the list `structure_features`.", - "x-optimade-support": "must", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "must" }, "concentration": { "items": { @@ -3330,8 +3592,8 @@ "type": "array", "title": "Concentration", "description": "MUST be a list of floats, with same length as `chemical_symbols`. The numbers represent the relative concentration of the corresponding chemical symbol in this species. The numbers SHOULD sum to one. Cases in which the numbers do not sum to one typically fall only in the following two categories:\n\n- Numerical errors when representing float numbers in fixed precision, e.g. for two chemical symbols with concentrations `1/3` and `2/3`, the concentration might look something like `[0.33333333333, 0.66666666666]`. If the client is aware that the sum is not one because of numerical precision, it can renormalize the values so that the sum is exactly one.\n- Experimental errors in the data present in the database. In this case, it is the responsibility of the client to decide how to process the data.\n\nNote that concentrations are uncorrelated between different site (even of the same species).", - "x-optimade-support": "must", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "must" }, "mass": { "items": { @@ -3340,16 +3602,16 @@ "type": "array", "title": "Mass", "description": "If present MUST be a list of floats expressed in a.m.u.\nElements denoting vacancies MUST have masses equal to 0.", - "x-optimade-support": "optional", "x-optimade-queryable": "optional", + "x-optimade-support": "optional", "x-optimade-unit": "a.m.u." }, "original_name": { "type": "string", "title": "Original Name", "description": "Can be any valid Unicode string, and SHOULD contain (if specified) the name of the species that is used internally in the source database.\n\nNote: With regards to \"source database\", we refer to the immediate source being queried via the OPTIMADE API implementation.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "attached": { "items": { @@ -3358,8 +3620,8 @@ "type": "array", "title": "Attached", "description": "If provided MUST be a list of length 1 or more of strings of chemical symbols for the elements attached to this site, or \"X\" for a non-chemical element.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "nattached": { "items": { @@ -3368,8 +3630,8 @@ "type": "array", "title": "Nattached", "description": "If provided MUST be a list of length 1 or more of integers indicating the number of attached atoms of the kind specified in the value of the :field:`attached` key.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" } }, "type": "object", @@ -3438,8 +3700,8 @@ "type": "string", "title": "Id", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "type": { "type": "string", @@ -3447,8 +3709,8 @@ "title": "Type", "description": "The name of the type of an entry.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - MUST be an existing entry type.\n - The entry of type `` and ID `` MUST be returned in response to a request for `//` under the versioned base URL.\n\n- **Examples**:\n - `\"structures\"`", "default": "structures", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "links": { "allOf": [ @@ -3496,17 +3758,17 @@ "type": "string", "title": "Immutable Id", "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", - "x-optimade-support": "optional", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "optional" }, "last_modified": { "type": "string", "format": "date-time", "title": "Last Modified", "description": "Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n - As part of JSON response format: `\"2007-04-05T14:30:20Z\"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)", + "x-optimade-queryable": "must", "nullable": true, - "x-optimade-support": "should", - "x-optimade-queryable": "must" + "x-optimade-support": "should" }, "elements": { "items": { @@ -3515,17 +3777,17 @@ "type": "array", "title": "Elements", "description": "The chemical symbols of the different elements present in the structure.\n\n- **Type**: list of strings.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - The strings are the chemical symbols, i.e., either a single uppercase letter or an uppercase letter followed by a number of lowercase letters.\n - The order MUST be alphabetical.\n - MUST refer to the same elements in the same order, and therefore be of the same length, as `elements_ratios`, if the latter is provided.\n - Note: This property SHOULD NOT contain the string \"X\" to indicate non-chemical elements or \"vacancy\" to indicate vacancies (in contrast to the field `chemical_symbols` for the `species` property).\n\n- **Examples**:\n - `[\"Si\"]`\n - `[\"Al\",\"O\",\"Si\"]`\n\n- **Query examples**:\n - A filter that matches all records of structures that contain Si, Al **and** O, and possibly other elements: `elements HAS ALL \"Si\", \"Al\", \"O\"`.\n - To match structures with exactly these three elements, use `elements HAS ALL \"Si\", \"Al\", \"O\" AND elements LENGTH 3`.\n - Note: length queries on this property can be equivalently formulated by filtering on the `nelements`_ property directly.", + "x-optimade-queryable": "must", "nullable": true, - "x-optimade-support": "should", - "x-optimade-queryable": "must" + "x-optimade-support": "should" }, "nelements": { "type": "integer", "title": "Nelements", "description": "Number of different elements in the structure as an integer.\n\n- **Type**: integer\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - MUST be equal to the lengths of the list properties `elements` and `elements_ratios`, if they are provided.\n\n- **Examples**:\n - `3`\n\n- **Querying**:\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`.", + "x-optimade-queryable": "must", "nullable": true, - "x-optimade-support": "should", - "x-optimade-queryable": "must" + "x-optimade-support": "should" }, "elements_ratios": { "items": { @@ -3534,43 +3796,43 @@ "type": "array", "title": "Elements Ratios", "description": "Relative proportions of different elements in the structure.\n\n- **Type**: list of floats\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - Composed by the proportions of elements in the structure as a list of floating point numbers.\n - The sum of the numbers MUST be 1.0 (within floating point accuracy)\n - MUST refer to the same elements in the same order, and therefore be of the same length, as `elements`, if the latter is provided.\n\n- **Examples**:\n - `[1.0]`\n - `[0.3333333333333333, 0.2222222222222222, 0.4444444444444444]`\n\n- **Query examples**:\n - Note: Useful filters can be formulated using the set operator syntax for correlated values.\n However, since the values are floating point values, the use of equality comparisons is generally inadvisable.\n - OPTIONAL: a filter that matches structures where approximately 1/3 of the atoms in the structure are the element Al is: `elements:elements_ratios HAS ALL \"Al\":>0.3333, \"Al\":<0.3334`.", + "x-optimade-queryable": "must", "nullable": true, - "x-optimade-support": "should", - "x-optimade-queryable": "must" + "x-optimade-support": "should" }, "chemical_formula_descriptive": { "type": "string", "title": "Chemical Formula Descriptive", "description": "The chemical formula for a structure as a string in a form chosen by the API implementation.\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - The chemical formula is given as a string consisting of properly capitalized element symbols followed by integers or decimal numbers, balanced parentheses, square, and curly brackets `(`,`)`, `[`,`]`, `{`, `}`, commas, the `+`, `-`, `:` and `=` symbols. The parentheses are allowed to be followed by a number. Spaces are allowed anywhere except within chemical symbols. The order of elements and any groupings indicated by parentheses or brackets are chosen freely by the API implementation.\n - The string SHOULD be arithmetically consistent with the element ratios in the `chemical_formula_reduced` property.\n - It is RECOMMENDED, but not mandatory, that symbols, parentheses and brackets, if used, are used with the meanings prescribed by [IUPAC's Nomenclature of Organic Chemistry](https://www.qmul.ac.uk/sbcs/iupac/bibliog/blue.html).\n\n- **Examples**:\n - `\"(H2O)2 Na\"`\n - `\"NaCl\"`\n - `\"CaCO3\"`\n - `\"CCaO3\"`\n - `\"(CH3)3N+ - [CH2]2-OH = Me3N+ - CH2 - CH2OH\"`\n\n- **Query examples**:\n - Note: the free-form nature of this property is likely to make queries on it across different databases inconsistent.\n - A filter that matches an exactly given formula: `chemical_formula_descriptive=\"(H2O)2 Na\"`.\n - A filter that does a partial match: `chemical_formula_descriptive CONTAINS \"H2O\"`.", + "x-optimade-queryable": "must", "nullable": true, - "x-optimade-support": "should", - "x-optimade-queryable": "must" + "x-optimade-support": "should" }, "chemical_formula_reduced": { "type": "string", "pattern": "(^$)|^([A-Z][a-z]?([2-9]|[1-9]\\d+)?)+$", "title": "Chemical Formula Reduced", "description": "The reduced chemical formula for a structure as a string with element symbols and integer chemical proportion numbers.\nThe proportion number MUST be omitted if it is 1.\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property.\n However, support for filters using partial string matching with this property is OPTIONAL (i.e., BEGINS WITH, ENDS WITH, and CONTAINS).\n Intricate queries on formula components are instead suggested to be formulated using set-type filter operators on the multi valued `elements` and `elements_ratios` properties.\n - Element symbols MUST have proper capitalization (e.g., `\"Si\"`, not `\"SI\"` for \"silicon\").\n - Elements MUST be placed in alphabetical order, followed by their integer chemical proportion number.\n - For structures with no partial occupation, the chemical proportion numbers are the smallest integers for which the chemical proportion is exactly correct.\n - For structures with partial occupation, the chemical proportion numbers are integers that within reasonable approximation indicate the correct chemical proportions. The precise details of how to perform the rounding is chosen by the API implementation.\n - No spaces or separators are allowed.\n\n- **Examples**:\n - `\"H2NaO\"`\n - `\"ClNa\"`\n - `\"CCaO3\"`\n\n- **Query examples**:\n - A filter that matches an exactly given formula is `chemical_formula_reduced=\"H2NaO\"`.", + "x-optimade-queryable": "must", "nullable": true, - "x-optimade-support": "should", - "x-optimade-queryable": "must" + "x-optimade-support": "should" }, "chemical_formula_hill": { "type": "string", "pattern": "(^$)|^([A-Z][a-z]?([2-9]|[1-9]\\d+)?)+$", "title": "Chemical Formula Hill", "description": "The chemical formula for a structure in [Hill form](https://dx.doi.org/10.1021/ja02046a005) with element symbols followed by integer chemical proportion numbers. The proportion number MUST be omitted if it is 1.\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, only a subset of the filter features MAY be supported.\n - The overall scale factor of the chemical proportions is chosen such that the resulting values are integers that indicate the most chemically relevant unit of which the system is composed.\n For example, if the structure is a repeating unit cell with four hydrogens and four oxygens that represents two hydroperoxide molecules, `chemical_formula_hill` is `\"H2O2\"` (i.e., not `\"HO\"`, nor `\"H4O4\"`).\n - If the chemical insight needed to ascribe a Hill formula to the system is not present, the property MUST be handled as unset.\n - Element symbols MUST have proper capitalization (e.g., `\"Si\"`, not `\"SI\"` for \"silicon\").\n - Elements MUST be placed in [Hill order](https://dx.doi.org/10.1021/ja02046a005), followed by their integer chemical proportion number.\n Hill order means: if carbon is present, it is placed first, and if also present, hydrogen is placed second.\n After that, all other elements are ordered alphabetically.\n If carbon is not present, all elements are ordered alphabetically.\n - If the system has sites with partial occupation and the total occupations of each element do not all sum up to integers, then the Hill formula SHOULD be handled as unset.\n - No spaces or separators are allowed.\n\n- **Examples**:\n - `\"H2O2\"`\n\n- **Query examples**:\n - A filter that matches an exactly given formula is `chemical_formula_hill=\"H2O2\"`.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "chemical_formula_anonymous": { "type": "string", "pattern": "(^$)|^([A-Z][a-z]?([2-9]|[1-9]\\d+)?)+$", "title": "Chemical Formula Anonymous", "description": "The anonymous formula is the `chemical_formula_reduced`, but where the elements are instead first ordered by their chemical proportion number, and then, in order left to right, replaced by anonymous symbols A, B, C, ..., Z, Aa, Ba, ..., Za, Ab, Bb, ... and so on.\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property.\n However, support for filters using partial string matching with this property is OPTIONAL (i.e., BEGINS WITH, ENDS WITH, and CONTAINS).\n\n- **Examples**:\n - `\"A2B\"`\n - `\"A42B42C16D12E10F9G5\"`\n\n- **Querying**:\n - A filter that matches an exactly given formula is `chemical_formula_anonymous=\"A2B\"`.", + "x-optimade-queryable": "must", "nullable": true, - "x-optimade-support": "should", - "x-optimade-queryable": "must" + "x-optimade-support": "should" }, "dimension_types": { "items": { @@ -3581,17 +3843,17 @@ "minItems": 3, "title": "Dimension Types", "description": "List of three integers.\nFor each of the three directions indicated by the three lattice vectors (see property `lattice_vectors`), this list indicates if the direction is periodic (value `1`) or non-periodic (value `0`).\nNote: the elements in this list each refer to the direction of the corresponding entry in `lattice_vectors` and *not* the Cartesian x, y, z directions.\n\n- **Type**: list of integers.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - MUST be a list of length 3.\n - Each integer element MUST assume only the value 0 or 1.\n\n- **Examples**:\n - For a molecule: `[0, 0, 0]`\n - For a wire along the direction specified by the third lattice vector: `[0, 0, 1]`\n - For a 2D surface/slab, periodic on the plane defined by the first and third lattice vectors: `[1, 0, 1]`\n - For a bulk 3D system: `[1, 1, 1]`", - "x-optimade-support": "should", "x-optimade-queryable": "optional", - "nullable": true + "nullable": true, + "x-optimade-support": "should" }, "nperiodic_dimensions": { "type": "integer", "title": "Nperiodic Dimensions", "description": "An integer specifying the number of periodic dimensions in the structure, equivalent to the number of non-zero entries in `dimension_types`.\n\n- **Type**: integer\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - The integer value MUST be between 0 and 3 inclusive and MUST be equal to the sum of the items in the `dimension_types` property.\n - This property only reflects the treatment of the lattice vectors provided for the structure, and not any physical interpretation of the dimensionality of its contents.\n\n- **Examples**:\n - `2` should be indicated in cases where `dimension_types` is any of `[1, 1, 0]`, `[1, 0, 1]`, `[0, 1, 1]`.\n\n- **Query examples**:\n - Match only structures with exactly 3 periodic dimensions: `nperiodic_dimensions=3`\n - Match all structures with 2 or fewer periodic dimensions: `nperiodic_dimensions<=2`", + "x-optimade-queryable": "must", "nullable": true, - "x-optimade-support": "should", - "x-optimade-queryable": "must" + "x-optimade-support": "should" }, "lattice_vectors": { "items": { @@ -3607,10 +3869,10 @@ "minItems": 3, "title": "Lattice Vectors", "description": "The three lattice vectors in Cartesian coordinates, in \u00e5ngstr\u00f6m (\u00c5).\n\n- **Type**: list of list of floats or unknown values.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - MUST be a list of three vectors *a*, *b*, and *c*, where each of the vectors MUST BE a list of the vector's coordinates along the x, y, and z Cartesian coordinates.\n (Therefore, the first index runs over the three lattice vectors and the second index runs over the x, y, z Cartesian coordinates).\n - For databases that do not define an absolute Cartesian system (e.g., only defining the length and angles between vectors), the first lattice vector SHOULD be set along *x* and the second on the *xy*-plane.\n - MUST always contain three vectors of three coordinates each, independently of the elements of property `dimension_types`.\n The vectors SHOULD by convention be chosen so the determinant of the `lattice_vectors` matrix is different from zero.\n The vectors in the non-periodic directions have no significance beyond fulfilling these requirements.\n - The coordinates of the lattice vectors of non-periodic dimensions (i.e., those dimensions for which `dimension_types` is `0`) MAY be given as a list of all `null` values.\n If a lattice vector contains the value `null`, all coordinates of that lattice vector MUST be `null`.\n\n- **Examples**:\n - `[[4.0,0.0,0.0],[0.0,4.0,0.0],[0.0,1.0,4.0]]` represents a cell, where the first vector is `(4, 0, 0)`, i.e., a vector aligned along the `x` axis of length 4 \u00c5; the second vector is `(0, 4, 0)`; and the third vector is `(0, 1, 4)`.", - "x-optimade-support": "should", "x-optimade-queryable": "optional", "x-optimade-unit": "\u00c5", - "nullable": true + "nullable": true, + "x-optimade-support": "should" }, "space_group_symmetry_operations_xyz": { "items": { @@ -3620,22 +3882,22 @@ "type": "array", "title": "Space Group Symmetry Operations Xyz", "description": "A list of symmetry operations given as general position x, y and z coordinates in algebraic form.\n\nEach symmetry operation is described by a string that gives that symmetry operation in Jones' faithful representation (Bradley & Cracknell, 1972: pp. 35-37), adapted for computer string notation.\nThe letters x, y and z that are typesetted with overbars in printed text represent coordinate values multiplied by -1 and are encoded as -x, -y and -z, respectively.\nThe syntax of the strings representing symmetry operations MUST conform to regular expressions given in appendix The Symmetry Operation String Regular Expressions.\nThe interpretation of the strings MUST follow the conventions of the IUCr CIF core dictionary (IUCr, 2023).\nIn particular, this property MUST explicitly provide all symmetry operations needed to generate all the atoms in the unit cell from the atoms in the asymmetric unit, for the setting used.\nThis symmetry operation set MUST always include the `\"x,y,z\"` identity operation.\nThe symmetry operations are to be applied to fractional atom coordinates.\nIn case only Cartesian coordinates are available, these Cartesian coordinates must be converted to fractional coordinates before the application of the provided symmetry operations.\nIf the symmetry operation list is present, it MUST be compatible with other space group specifications (e.g. the ITC space group number, the Hall symbol, the Hermann-Mauguin symbol) if these are present.\n\n- **Type**: list of strings\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n However, the property is RECOMMENDED if coordinates are returned in a form to which these operations can or must be applied (e.g. fractional atom coordinates of an asymmetric unit).\n Moreover, the property is REQUIRED if symmetry operations are necessary to reconstruct the full model of the material and no other symmetry information (e.g., the Hall symbol) is provided that would allow the user to derive symmetry operations unambiguously.\n - MUST be null if `nperiodic_dimensions` is equal to 0.\n\n- **Examples**:\n - Space group operations for the space group with ITC number 3 (H-M symbol: P 2, extended H-M symbol: P 1 2 1, Hall symbol P 2y):\n ```\n [\"x,y,z\", \"-x,y,-z\"]\n ```\n - Space group operations for the space group with ITC number 5 (H-M symbol C 2, extended H-M symbol: C 1 2 1, Hall symbol C 2y):\n ```\n [\"x,y,z\", \"-x,y,-z\", \"x+1/2,y+1/2,z\", \"-x+1/2,y+1/2,-z\"]\n ```\n\n- **Notes**:\n The list of space group symmetry operations applies to the whole periodic array of atoms and together with the lattice translations given in the `lattice_vectors` property provides the necessary information to reconstruct all atom site positions of the periodic material.\n Thus, the symmetry operations described in this property are only applicable to material models with at least one periodic dimension.\n This property is not meant to represent arbitrary symmetries of molecules, non-periodic (finite) collections of atoms or non-crystallographic symmetry.\n\n- **Bibliographic References**:\n\n Bradley, C. J. and Cracknell, A. P. (1972) The Mathematical Theory of Symmetry in Solids. Oxford, Clarendon Press (paperback edition 2010) 745 p. ISBN 978-0-19-958258-7.\n\n IUCr (2023) Core dictionary (coreCIF) version 2.4.5; data name _space_group_symop_operation_xyz. Available from: https://www.iucr.org/__data/iucr/cifdic_html/1/cif_core.dic/Ispace_group_symop_operation_xyz.html [Accessed 2023-06-18T16:46+03:00].", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "space_group_hall": { "type": "string", "title": "Space Group Hall", "description": "A Hall space group symbol representing the symmetry of the structure as defined in (Hall, 1981, 1981a).\nThe change-of-basis operations are used as defined in the International Tables of Crystallography (ITC) Vol. B, Sect. 1.4, Appendix A1.4.2 (IUCr, 2001).\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - Each component of the Hall symbol MUST be separated by a single space symbol.\n - If there exists a standard Hall symbol which represents the symmetry it SHOULD be used.\n - MUST be null if `nperiodic_dimensions` is not equal to 3.\n\n- **Bibliographic References**:\n\n Hall, S. R. (1981) Space-group notation with an explicit origin. Acta Crystallographica Section A, 37, 517-525, International Union of Crystallography (IUCr), DOI: https://doi.org/10.1107/s0567739481001228\n\n Hall, S. R. (1981a) Space-group notation with an explicit origin; erratum. Acta Crystallographica Section A, 37, 921-921, International Union of Crystallography (IUCr), DOI: https://doi.org/10.1107/s0567739481001976\n\n IUCr (2001). International Tables for Crystallography vol. B. Reciprocal Space. Ed. U. Shmueli. 2-nd edition. Dordrecht/Boston/London, Kluwer Academic Publishers.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "space_group_symbol_hermann_mauguin": { "type": "string", "title": "Space Group Symbol Hermann Mauguin", "description": "A human- and machine-readable string containing the short Hermann-Mauguin (H-M) symbol which specifies the space group of the structure in the response.\nThe H-M symbol SHOULD aim to convey the closest representation of the symmetry information that can be specified using the short format used in the International Tables for Crystallography vol. A (IUCr, 2005), Table 4.3.2.1 as described in the accompanying text.\nThe symbol MAY be a non-standard short H-M symbol.\nThe H-M symbol does not unambiguously communicate the axis, cell, and origin choice, and the given symbol SHOULD NOT be amended to convey this information.\n\nTo encode as character strings, the following adaptations MUST be made when representing H-M symbols given in their typesetted form:\n - the overbar above the numbers MUST be changed to the minus sign in front of the digit (e.g. '-2');\n - subscripts that denote screw axes are written as digits immediately after the axis designator without a space (e.g. 'P 32')\n - the space group generators MUST be separated by a single space (e.g. 'P 21 21 2');\n - there MUST be no spaces in the space group generator designation (i.e. use 'P 21/m', not the 'P 21 / m');\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n\n- **Examples**:\n - `C 2`\n - `P 21 21 21`\n\n- **Bibliographic References**:\n\nIUCr (2005). International Tables for Crystallography vol. A. Space-Group Symmetry. Ed. Theo Hahn. 5-th edition. Dordrecht, Springer.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "space_group_it_number": { "type": "integer", @@ -3643,8 +3905,8 @@ "minimum": 1.0, "title": "Space Group It Number", "description": "Space group number for the structure assigned by the International Tables for Crystallography Vol. A.\n- **Type**: integer\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - The integer value MUST be between 1 and 230.\n - MUST be null if `nperiodic_dimensions` is not equal to 3.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "cartesian_site_positions": { "items": { @@ -3658,18 +3920,18 @@ "type": "array", "title": "Cartesian Site Positions", "description": "Cartesian positions of each site in the structure.\nA site is usually used to describe positions of atoms; what atoms can be encountered at a given site is conveyed by the `species_at_sites` property, and the species themselves are described in the `species` property.\n\n- **Type**: list of list of floats\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - It MUST be a list of length equal to the number of sites in the structure, where every element is a list of the three Cartesian coordinates of a site expressed as float values in the unit angstrom (\u00c5).\n - An entry MAY have multiple sites at the same Cartesian position (for a relevant use of this, see e.g., the property `assemblies`).\n\n- **Examples**:\n - `[[0,0,0],[0,0,2]]` indicates a structure with two sites, one sitting at the origin and one along the (positive) *z*-axis, 2 \u00c5 away from the origin.", - "x-optimade-support": "should", "x-optimade-queryable": "optional", "x-optimade-unit": "\u00c5", - "nullable": true + "nullable": true, + "x-optimade-support": "should" }, "nsites": { "type": "integer", "title": "Nsites", "description": "An integer specifying the length of the `cartesian_site_positions` property.\n\n- **Type**: integer\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `42`\n\n- **Query examples**:\n - Match only structures with exactly 4 sites: `nsites=4`\n - Match structures that have between 2 and 7 sites: `nsites>=2 AND nsites<=7`", + "x-optimade-queryable": "must", "nullable": true, - "x-optimade-support": "should", - "x-optimade-queryable": "must" + "x-optimade-support": "should" }, "species": { "items": { @@ -3678,9 +3940,9 @@ "type": "array", "title": "Species", "description": "A list describing the species of the sites of this structure.\nSpecies can represent pure chemical elements, virtual-crystal atoms representing a statistical occupation of a given site by multiple chemical elements, and/or a location to which there are attached atoms, i.e., atoms whose precise location are unknown beyond that they are attached to that position (frequently used to indicate hydrogen atoms attached to another element, e.g., a carbon with three attached hydrogens might represent a methyl group, -CH3).\n\n- **Type**: list of dictionary with keys:\n - `name`: string (REQUIRED)\n - `chemical_symbols`: list of strings (REQUIRED)\n - `concentration`: list of float (REQUIRED)\n - `attached`: list of strings (REQUIRED)\n - `nattached`: list of integers (OPTIONAL)\n - `mass`: list of floats (OPTIONAL)\n - `original_name`: string (OPTIONAL).\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - Each list member MUST be a dictionary with the following keys:\n - **name**: REQUIRED; gives the name of the species; the **name** value MUST be unique in the `species` list;\n - **chemical_symbols**: REQUIRED; MUST be a list of strings of all chemical elements composing this species.\n Each item of the list MUST be one of the following:\n - a valid chemical-element symbol, or\n - the special value `\"X\"` to represent a non-chemical element, or\n - the special value `\"vacancy\"` to represent that this site has a non-zero probability of having a vacancy (the respective probability is indicated in the `concentration` list, see below).\n\n If any one entry in the `species` list has a `chemical_symbols` list that is longer than 1 element, the correct flag MUST be set in the list `structure_features`.\n\n - **concentration**: REQUIRED; MUST be a list of floats, with same length as `chemical_symbols`.\n The numbers represent the relative concentration of the corresponding chemical symbol in this species.\n The numbers SHOULD sum to one. Cases in which the numbers do not sum to one typically fall only in the following two categories:\n\n - Numerical errors when representing float numbers in fixed precision, e.g. for two chemical symbols with concentrations `1/3` and `2/3`, the concentration might look something like `[0.33333333333, 0.66666666666]`. If the client is aware that the sum is not one because of numerical precision, it can renormalize the values so that the sum is exactly one.\n - Experimental errors in the data present in the database. In this case, it is the responsibility of the client to decide how to process the data.\n\n Note that concentrations are uncorrelated between different sites (even of the same species).\n\n - **attached**: OPTIONAL; if provided MUST be a list of length 1 or more of strings of chemical symbols for the elements attached to this site, or \"X\" for a non-chemical element.\n\n - **nattached**: OPTIONAL; if provided MUST be a list of length 1 or more of integers indicating the number of attached atoms of the kind specified in the value of the `attached` key.\n\n The implementation MUST include either both or none of the `attached` and `nattached` keys, and if they are provided, they MUST be of the same length.\n Furthermore, if they are provided, the `structure_features` property MUST include the string `site_attachments`.\n\n - **mass**: OPTIONAL. If present MUST be a list of floats, with the same length as `chemical_symbols`, providing element masses expressed in a.m.u.\n Elements denoting vacancies MUST have masses equal to 0.\n\n - **original_name**: OPTIONAL. Can be any valid Unicode string, and SHOULD contain (if specified) the name of the species that is used internally in the source database.\n\n Note: With regards to \"source database\", we refer to the immediate source being queried via the OPTIMADE API implementation.\n\n The main use of this field is for source databases that use species names, containing characters that are not allowed (see description of the list property `species_at_sites`).\n\n - For systems that have only species formed by a single chemical symbol, and that have at most one species per chemical symbol, SHOULD use the chemical symbol as species name (e.g., `\"Ti\"` for titanium, `\"O\"` for oxygen, etc.)\n However, note that this is OPTIONAL, and client implementations MUST NOT assume that the key corresponds to a chemical symbol, nor assume that if the species name is a valid chemical symbol, that it represents a species with that chemical symbol.\n This means that a species `{\"name\": \"C\", \"chemical_symbols\": [\"Ti\"], \"concentration\": [1.0]}` is valid and represents a titanium species (and *not* a carbon species).\n - It is NOT RECOMMENDED that a structure includes species that do not have at least one corresponding site.\n\n- **Examples**:\n - `[ {\"name\": \"Ti\", \"chemical_symbols\": [\"Ti\"], \"concentration\": [1.0]} ]`: any site with this species is occupied by a Ti atom.\n - `[ {\"name\": \"Ti\", \"chemical_symbols\": [\"Ti\", \"vacancy\"], \"concentration\": [0.9, 0.1]} ]`: any site with this species is occupied by a Ti atom with 90 % probability, and has a vacancy with 10 % probability.\n - `[ {\"name\": \"BaCa\", \"chemical_symbols\": [\"vacancy\", \"Ba\", \"Ca\"], \"concentration\": [0.05, 0.45, 0.5], \"mass\": [0.0, 137.327, 40.078]} ]`: any site with this species is occupied by a Ba atom with 45 % probability, a Ca atom with 50 % probability, and by a vacancy with 5 % probability. The mass of this site is (on average) 88.5 a.m.u.\n - `[ {\"name\": \"C12\", \"chemical_symbols\": [\"C\"], \"concentration\": [1.0], \"mass\": [12.0]} ]`: any site with this species is occupied by a carbon isotope with mass 12.\n - `[ {\"name\": \"C13\", \"chemical_symbols\": [\"C\"], \"concentration\": [1.0], \"mass\": [13.0]} ]`: any site with this species is occupied by a carbon isotope with mass 13.\n - `[ {\"name\": \"CH3\", \"chemical_symbols\": [\"C\"], \"concentration\": [1.0], \"attached\": [\"H\"], \"nattached\": [3]} ]`: any site with this species is occupied by a methyl group, -CH3, which is represented without specifying precise positions of the hydrogen atoms.", + "x-optimade-queryable": "optional", "nullable": true, - "x-optimade-support": "should", - "x-optimade-queryable": "optional" + "x-optimade-support": "should" }, "species_at_sites": { "items": { @@ -3689,9 +3951,9 @@ "type": "array", "title": "Species At Sites", "description": "Name of the species at each site (where values for sites are specified with the same order of the property `cartesian_site_positions`).\nThe properties of the species are found in the property `species`.\n\n- **Type**: list of strings.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - MUST have length equal to the number of sites in the structure (first dimension of the list property `cartesian_site_positions`).\n - Each species name mentioned in the `species_at_sites` list MUST be described in the list property `species` (i.e. for each value in the `species_at_sites` list there MUST exist exactly one dictionary in the `species` list with the `name` attribute equal to the corresponding `species_at_sites` value).\n - Each site MUST be associated only to a single species.\n **Note**: However, species can represent mixtures of atoms, and multiple species MAY be defined for the same chemical element.\n This latter case is useful when different atoms of the same type need to be grouped or distinguished, for instance in simulation codes to assign different initial spin states.\n\n- **Examples**:\n - `[\"Ti\",\"O2\"]` indicates that the first site is hosting a species labeled `\"Ti\"` and the second a species labeled `\"O2\"`.\n - `[\"Ac\", \"Ac\", \"Ag\", \"Ir\"]` indicating the first two sites contains the `\"Ac\"` species, while the third and fourth sites contain the `\"Ag\"` and `\"Ir\"` species, respectively.", + "x-optimade-queryable": "optional", "nullable": true, - "x-optimade-support": "should", - "x-optimade-queryable": "optional" + "x-optimade-support": "should" }, "assemblies": { "items": { @@ -3700,8 +3962,8 @@ "type": "array", "title": "Assemblies", "description": "A description of groups of sites that are statistically correlated.\n\n- **Type**: list of dictionary with keys:\n - `sites_in_groups`: list of list of integers (REQUIRED)\n - `group_probabilities`: list of floats (REQUIRED)\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - The property SHOULD be `null` for entries that have no partial occupancies.\n - If present, the correct flag MUST be set in the list `structure_features`.\n - Client implementations MUST check its presence (as its presence changes the interpretation of the structure).\n - If present, it MUST be a list of dictionaries, each of which represents an assembly and MUST have the following two keys:\n - **sites_in_groups**: Index of the sites (0-based) that belong to each group for each assembly.\n\n Example: `[[1], [2]]`: two groups, one with the second site, one with the third.\n Example: `[[1,2], [3]]`: one group with the second and third site, one with the fourth.\n\n - **group_probabilities**: Statistical probability of each group. It MUST have the same length as `sites_in_groups`.\n It SHOULD sum to one.\n See below for examples of how to specify the probability of the occurrence of a vacancy.\n The possible reasons for the values not to sum to one are the same as already specified above for the `concentration` of each `species`.\n\n - If a site is not present in any group, it means that it is present with 100 % probability (as if no assembly was specified).\n - A site MUST NOT appear in more than one group.\n\n- **Examples** (for each entry of the assemblies list):\n - `{\"sites_in_groups\": [[0], [1]], \"group_probabilities: [0.3, 0.7]}`: the first site and the second site never occur at the same time in the unit cell.\n Statistically, 30 % of the times the first site is present, while 70 % of the times the second site is present.\n - `{\"sites_in_groups\": [[1,2], [3]], \"group_probabilities: [0.3, 0.7]}`: the second and third site are either present together or not present; they form the first group of atoms for this assembly.\n The second group is formed by the fourth site.\n Sites of the first group (the second and the third) are never present at the same time as the fourth site.\n 30 % of times sites 1 and 2 are present (and site 3 is absent); 70 % of times site 3 is present (and sites 1 and 2 are absent).\n\n- **Notes**:\n - Assemblies are essential to represent, for instance, the situation where an atom can statistically occupy two different positions (sites).\n\n - By defining groups, it is possible to represent, e.g., the case where a functional molecule (and not just one atom) is either present or absent (or the case where it it is present in two conformations)\n\n - Considerations on virtual alloys and on vacancies: In the special case of a virtual alloy, these specifications allow two different, equivalent ways of specifying them.\n For instance, for a site at the origin with 30 % probability of being occupied by Si, 50 % probability of being occupied by Ge, and 20 % of being a vacancy, the following two representations are possible:\n\n - Using a single species:\n ```json\n {\n \"cartesian_site_positions\": [[0,0,0]],\n \"species_at_sites\": [\"SiGe-vac\"],\n \"species\": [\n {\n \"name\": \"SiGe-vac\",\n \"chemical_symbols\": [\"Si\", \"Ge\", \"vacancy\"],\n \"concentration\": [0.3, 0.5, 0.2]\n }\n ]\n // ...\n }\n ```\n\n - Using multiple species and the assemblies:\n ```json\n {\n \"cartesian_site_positions\": [ [0,0,0], [0,0,0], [0,0,0] ],\n \"species_at_sites\": [\"Si\", \"Ge\", \"vac\"],\n \"species\": [\n { \"name\": \"Si\", \"chemical_symbols\": [\"Si\"], \"concentration\": [1.0] },\n { \"name\": \"Ge\", \"chemical_symbols\": [\"Ge\"], \"concentration\": [1.0] },\n { \"name\": \"vac\", \"chemical_symbols\": [\"vacancy\"], \"concentration\": [1.0] }\n ],\n \"assemblies\": [\n {\n \"sites_in_groups\": [ [0], [1], [2] ],\n \"group_probabilities\": [0.3, 0.5, 0.2]\n }\n ]\n // ...\n }\n ```\n\n - It is up to the database provider to decide which representation to use, typically depending on the internal format in which the structure is stored.\n However, given a structure identified by a unique ID, the API implementation MUST always provide the same representation for it.\n\n - The probabilities of occurrence of different assemblies are uncorrelated.\n So, for instance in the following case with two assemblies:\n ```json\n {\n \"assemblies\": [\n {\n \"sites_in_groups\": [ [0], [1] ],\n \"group_probabilities\": [0.2, 0.8],\n },\n {\n \"sites_in_groups\": [ [2], [3] ],\n \"group_probabilities\": [0.3, 0.7]\n }\n ]\n }\n ```\n\n Site 0 is present with a probability of 20 % and site 1 with a probability of 80 %. These two sites are correlated (either site 0 or 1 is present). Similarly, site 2 is present with a probability of 30 % and site 3 with a probability of 70 %.\n These two sites are correlated (either site 2 or 3 is present).\n However, the presence or absence of sites 0 and 1 is not correlated with the presence or absence of sites 2 and 3 (in the specific example, the pair of sites (0, 2) can occur with 0.2*0.3 = 6 % probability; the pair (0, 3) with 0.2*0.7 = 14 % probability; the pair (1, 2) with 0.8*0.3 = 24 % probability; and the pair (1, 3) with 0.8*0.7 = 56 % probability).", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "structure_features": { "items": { @@ -3710,8 +3972,8 @@ "type": "array", "title": "Structure Features", "description": "A list of strings that flag which special features are used by the structure.\n\n- **Type**: list of strings\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property.\n Filters on the list MUST support all mandatory HAS-type queries.\n Filter operators for comparisons on the string components MUST support equality, support for other comparison operators are OPTIONAL.\n - MUST be an empty list if no special features are used.\n - MUST be sorted alphabetically.\n - If a special feature listed below is used, the list MUST contain the corresponding string.\n - If a special feature listed below is not used, the list MUST NOT contain the corresponding string.\n - **List of strings used to indicate special structure features**:\n - `disorder`: this flag MUST be present if any one entry in the `species` list has a `chemical_symbols` list that is longer than 1 element.\n - `implicit_atoms`: this flag MUST be present if the structure contains atoms that are not assigned to sites via the property `species_at_sites` (e.g., because their positions are unknown).\n When this flag is present, the properties related to the chemical formula will likely not match the type and count of atoms represented by the `species_at_sites`, `species` and `assemblies` properties.\n - `site_attachments`: this flag MUST be present if any one entry in the `species` list includes `attached` and `nattached`.\n - `assemblies`: this flag MUST be present if the property `assemblies` is present.\n\n- **Examples**: A structure having implicit atoms and using assemblies: `[\"assemblies\", \"implicit_atoms\"]`", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" } }, "type": "object", @@ -3896,6 +4158,15 @@ "title": "StructureResponseOne", "description": "errors are not allowed" }, + "SupportLevel": { + "enum": [ + "must", + "should", + "optional" + ], + "title": "SupportLevel", + "description": "OPTIMADE property/field support levels" + }, "ToplevelLinks": { "properties": { "self": { @@ -3993,6 +4264,24 @@ "title": "ToplevelLinks", "description": "A set of Links objects, possibly including pagination" }, + "UnitResourceURIs": { + "properties": { + "relation": { + "type": "string", + "title": "Relation" + }, + "uri": { + "type": "string", + "title": "Uri" + } + }, + "type": "object", + "required": [ + "relation", + "uri" + ], + "title": "UnitResourceURIs" + }, "Warnings": { "properties": { "id": { diff --git a/optimade/models/entries.py b/optimade/models/entries.py index 4bd10a29e..4922c8b66 100644 --- a/optimade/models/entries.py +++ b/optimade/models/entries.py @@ -1,12 +1,13 @@ # pylint: disable=line-too-long,no-self-argument from datetime import datetime -from typing import Optional +from enum import Enum +from typing import Dict, List, Optional, Union from pydantic import BaseModel, validator # pylint: disable=no-name-in-module from optimade.models.jsonapi import Attributes, Relationships, Resource -from optimade.models.optimade_json import DataType, Relationship -from optimade.models.utils import OptimadeField, StrictField, SupportLevel +from optimade.models.optimade_json import AllowedJSONSchemaDataType, Relationship +from optimade.models.utils import OptimadeField, QuerySupport, StrictField, SupportLevel __all__ = ( "EntryRelationships", @@ -17,8 +18,190 @@ ) +class OptimadeAllowedUnitStandard(Enum): + GNU_UNITS = "gnu units" + UCUM = "ucum" + QUDT = "qudt" + + +class UnitResourceURIs(BaseModel): + relation: str + uri: str + + +class OptimadeUnitStandard(BaseModel): + name: OptimadeAllowedUnitStandard + version: str + symbol: str + + +class OptimadeUnitDefinition(BaseModel): + symbol: str + title: str + description: str + standard: OptimadeUnitStandard + resource_uris: Optional[List[UnitResourceURIs]] = StrictField( + ..., alias="resource-uris" + ) + + +class JSONSchemaObject(BaseModel): + properties: Dict[str, "EntryInfoProperty"] = StrictField( + ..., + 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`.)""", + ) + + required: Optional[List[str]] = StrictField( + ..., + description="""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.""", + ) + maxProperties: Optional[int] + minProperties: Optional[int] + dependentRequired: Optional[Dict] + + +class JSONSchemaArray(BaseModel): + items: "EntryInfoProperty" = StrictField(...) + maxItems: Optional[int] + minItems: Optional[int] + uniqueItems: Optional[bool] + + +class JSONSchemaInteger(BaseModel): + multipleOf: Optional[int] + maximum: Optional[int] + exclusiveMaximum: Optional[int] + minimum: Optional[int] + exclusiveMinimum: Optional[int] + + +class JSONSchemaNumber(BaseModel): + multipleOf: Optional[float] + maximum: Optional[float] + exclusiveMaximum: Optional[float] + minimum: Optional[float] + exclusiveMinimum: Optional[float] + + +class JSONSchemaStringFormat(Enum): + DATETIME = "date-time" + DATE = "date" + TIME = "time" + DURATION = "duration" + EMAIL = "email" + URI = "uri" + + +class JSONSchemaString(BaseModel): + maxLength: Optional[int] + minLength: Optional[int] + format: Optional[JSONSchemaStringFormat] + + +class PropertyImplementationInfo(BaseModel): + sortable: Optional[bool] = StrictField( + ..., + description="""If `TRUE`, specifies that results can be sorted on this property. + If `FALSE`, specifies that results cannot be sorted on this property. + Omitting the field is equivalent to `FALSE`.""", + ) + + query_support: Optional[QuerySupport] = StrictField( + ..., + alias="query-support", + description="""Defines a required level of support in formulating queries on this field. + + The string MUST be one of the following: + + - `all mandatory`: the defined property MUST be queryable using the OPTIMADE filter language with support for all mandatory filter features. + - `equality only`: the defined property MUST be queryable using the OPTIMADE filter language equality and inequality operators. Other filter language features do not need to be available. + - `partial`: the defined property MUST be queryable with support for a subset of the filter language operators as specified by the field `query-support-operators`. + - `none`: the defined property does not need to be queryable with any features of the filter language.""", + ) + + query_support_operators: Optional[List[str]] = StrictField( + ..., + alias="query-support-operators", + description="""Defines the filter language features supported on this property. + +Each string in the list MUST be one of `<`, `<=`, `>`, `>=`, `=`, `!=`, `CONTAINS`, `STARTS WITH`, `ENDS WITH`:, `HAS`, `HAS ALL`, `HAS ANY`, `HAS ONLY`, `IS KNOWN`, `IS UNKNOWN` with the following meanings: + +- `<`, `<=`, `>`, `>=`, `=`, `!=`: indicating support for filtering this property using the respective operator. + If the property is of Boolean type, support for `=` also designates support for boolean comparisons with the property being true that omit ":filter-fragment:`= TRUE`", e.g., specifying that filtering for "`is_yellow = TRUE`" is supported also implies support for "`is_yellow`" (which means the same thing). + Support for "`NOT is_yellow`" also follows. + +- `CONTAINS`, `STARTS WITH`, `ENDS WITH`: indicating support for substring filtering of this property using the respective operator. MUST NOT appear if the property is not of type String. + +- `HAS`, `HAS ALL`, `HAS ANY`: indicating support of the MANDATORY features for list property comparison using the respective operator. MUST NOT appear if the property is not of type List. + +- `HAS ONLY`: indicating support for list property comparison with all or a subset of the OPTIONAL constructs using this operator. MUST NOT appear if the property is not of type List. + +- `IS KNOWN`, `IS UNKNOWN`: indicating support for filtering this property on unknown values using the respective operator.""", + ) + + +class PropertyRequirementsInfo(PropertyImplementationInfo): + support: SupportLevel = StrictField( + ..., + description="""Describes the minimal required level of support for the Property by an implementation. + + This field SHOULD only appear in a `x-optimade-requirements` that is at the outermost level of a Property Definition, as the meaning of its inclusion on other levels is not defined. + 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`: it is OPTIONAL for the implementation to recognize the defined property and it MAY be equal to `null`.""", + ) + + +class PropertyRemoteResource(BaseModel): + relation: str = StrictField( + ..., + description="A human-readable description of the relationship between the property and the remote resource, e.g., a 'natural language description'.", + ) + + uri: str = StrictField( + ..., + description="A URI of the external resource (which MAY be a resolvable URL).", + ) + + +class OptimadePropertyDefinition(BaseModel): + property_uri: str = StrictField( + ..., + alias="property-uri", + description="""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.)""", + ) + + version: Optional[str] = StrictField( + ..., + description="""This string indicates the version of the property definition. +The string SHOULD be in the format described by the [semantic versioning v2](https://semver.org/spec/v2.0.0.html) standard.""", + ) + + unit_definitions: Optional[List[OptimadeUnitDefinition]] = StrictField( + ..., + alias="unit-definitions", + description="""A list of definitions of the symbols used in the Property Definition (including its nested levels) for physical units given as values of the `x-optimade-unit` field. +This field MUST be included if the defined property, at any level, includes an `x-optimade-unit` with a value that is not `dimensionless` or `inapplicable`.""", + ) + + resource_uris: Optional[List[PropertyRemoteResource]] = StrictField( + ..., + alias="resource-uris", + description="A list of dictionaries that references remote resources that describe the property.", + ) + + class TypedRelationship(Relationship): - # This may be updated when moving to Python 3.8 @validator("data") def check_rel_type(cls, data): if not isinstance(data, list): @@ -155,33 +338,97 @@ class EntryResource(Resource): class EntryInfoProperty(BaseModel): + title: str = StrictField( + ..., + description="A short single-line human-readable explanation of the defined property appropriate to show as part of a user interface.", + ) + description: str = StrictField( - ..., description="A human-readable description of the entry property" + ..., + 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.""", + ) + + property: OptimadePropertyDefinition = StrictField( + ..., + alias="x-optimade-property", + description="Additional information to define the property that is not covered by fields in the JSON Schema standard.", ) unit: Optional[str] = StrictField( None, - description="""The physical unit of the entry property. -This MUST be a valid representation of units according to version 2.1 of [The Unified Code for Units of Measure](https://unitsofmeasure.org/ucum.html). -It is RECOMMENDED that non-standard (non-SI) units are described in the description for the property.""", + alias="x-optimade-unit", + description="A (compound) symbol for the physical unit in which the value of the defined property is given or one of the strings `dimensionless` or `inapplicable`.", ) - sortable: Optional[bool] = StrictField( - None, - description="""Defines whether the entry property can be used for sorting with the "sort" parameter. -If the entry listing endpoint supports sorting, this key MUST be present for sortable properties with value `true`.""", + implementation: Optional[PropertyImplementationInfo] = StrictField( + ..., + alias="x-optimade-implementation", + description="""A dictionary describing the level of OPTIMADE API functionality provided by the present implementation. +If an implementation omits this field in its response, a client interacting with that implementation SHOULD NOT make any assumptions about the availability of these features.""", ) - type: Optional[DataType] = StrictField( + requirements: Optional[PropertyRequirementsInfo] = StrictField( + ..., + alias="x-optimade-requirements", + description="""A dictionary describing the level of OPTIMADE API functionality required by all implementations of this property. +Omitting this field means the corresponding functionality is OPTIONAL.""", + ) + + type: Union[ + AllowedJSONSchemaDataType, List[AllowedJSONSchemaDataType] + ] = StrictField( None, title="Type", - description="""The type of the property's value. -This MUST be any of the types defined in the Data types section. -For the purpose of compatibility with future versions of this specification, a client MUST accept values that are not `string` values specifying any of the OPTIMADE Data types, but MUST then also disregard the `type` field. -Note, if the value is a nested type, only the outermost type should be reported. -E.g., for the entry resource `structures`, the `species` property is defined as a list of dictionaries, hence its `type` value would be `list`.""", + description="""A string or list that specifies the type of the defined property. +It MUST be one of: + +- One of the strings `"boolean"`, `"object"` (refers to an OPTIMADE dictionary), `"array"` (refers to an OPTIMADE list), `"number"` (refers to an OPTIMADE float), `"string"`, or `"integer"`. +- A list where the first item MUST be one of the strings above, and the second item MUST be the string `"null"`.""", + ) + + deprecated: Optional[bool] = StrictField( + ..., + 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`.""", + ) + + enum: Optional[List] = StrictField( + ..., + description="""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"`.""", ) + examples: Optional[List] = StrictField( + ..., + description="""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.""", + ) + + +class EntryInfoPropertyObject(EntryInfoProperty, JSONSchemaObject): + ... + + +class EntryInfoPropertyArray(EntryInfoProperty, JSONSchemaArray): + ... + + +class EntryInfoPropertyNumber(EntryInfoProperty, JSONSchemaInteger): + ... + + +class EntryInfoPropertyString(EntryInfoProperty, JSONSchemaString): + ... + + +class EntryInfoPropertyInteger(EntryInfoProperty, JSONSchemaInteger): + ... + class EntryInfoResource(BaseModel): formats: list[str] = StrictField( diff --git a/optimade/models/optimade_json.py b/optimade/models/optimade_json.py index 2af6ab53a..2ad7f4d0b 100644 --- a/optimade/models/optimade_json.py +++ b/optimade/models/optimade_json.py @@ -121,6 +121,17 @@ def from_json_type(cls, json_type: str): return mapping.get(json_type, None) +class AllowedJSONSchemaDataType(Enum): + """The allowed values for `type` in the Property Definition restricted JSON Schema syntax.""" + + BOOLEAN = "boolean" + OBJECT = "object" + ARRAY = "array" + NUMBER = "number" + STRING = "string" + INTEGER = "integer" + + class OptimadeError(jsonapi.Error): """detail MUST be present""" diff --git a/optimade/models/utils.py b/optimade/models/utils.py index cc15d5758..4e72ea3d2 100644 --- a/optimade/models/utils.py +++ b/optimade/models/utils.py @@ -36,6 +36,13 @@ class SupportLevel(Enum): OPTIONAL = "optional" +class QuerySupport(Enum): + ALL_MANDATORY = "all mandatory" + EQUALITY_ONLY = "equality only" + PARTIAL = "partial" + NONE = "none" + + class StrictFieldInfo(FieldInfo): """Wraps the standard pydantic `FieldInfo` in order to prefix any custom keys from `StrictField`. From 27736fa78ec393218e069191dba14df3bedc7267 Mon Sep 17 00:00:00 2001 From: Matthew Evans Date: Tue, 6 Dec 2022 21:32:52 +0000 Subject: [PATCH 06/19] Add `license` and `available_licenses` info fields. --- optimade/models/baseinfo.py | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/optimade/models/baseinfo.py b/optimade/models/baseinfo.py index 36c47695e..9c4b7a588 100644 --- a/optimade/models/baseinfo.py +++ b/optimade/models/baseinfo.py @@ -1,10 +1,10 @@ # pylint: disable=no-self-argument,no-name-in-module import re -from typing import Optional +from typing import Dict, List, Optional, Union from pydantic import AnyHttpUrl, BaseModel, Field, root_validator, validator -from optimade.models.jsonapi import Resource +from optimade.models.jsonapi import Link, Resource from optimade.models.utils import SemanticVersion, StrictField __all__ = ("AvailableApiVersion", "BaseInfoAttributes", "BaseInfoResource") @@ -78,6 +78,21 @@ class BaseInfoAttributes(BaseModel): entry_types_by_format: dict[str, list[str]] = StrictField( ..., description="Available entry endpoints as a function of output formats." ) + license: Union[Link, AnyHttpUrl] = StrictField( + ..., + description="""A [JSON API links object](http://jsonapi.org/format/1.0/#document-links) giving a URL to a web page containing a human-readable text describing the license (or licensing options if there are multiple) covering all the data and metadata provided by this database. +Clients are advised not to try automated parsing of this link or its content, but rather rely on the field `available_licenses` instead.""", + ) + available_licenses: Optional[List[str]] = StrictField( + ..., + description="""List of [SPDX license identifiers](https://spdx.org/licenses/) specifying a set of alternative licenses under which the client is granted access to all the data and metadata in this database. + +If the data and metadata is available under multiple alternative licenses, identifiers of these multiple licenses SHOULD be provided to let clients know under which conditions the data and metadata can be used. +Inclusion of a license identifier in the list is a commitment of the database that the rights are in place to grant clients access to all the data and metadata according to the terms of either of these licenses (at the choice of the client). +If the licensing information provided via the field `license` omits licensing options specified in `available_licenses`, or if it otherwise contradicts them, a client MUST still be allowed to interpret the inclusion of a license in `available_licenses` as a full commitment from the database that the data and metadata is available, without exceptions, under the respective licenses. +If the database cannot make that commitment, e.g., if only part of the data is available under a license, the corresponding license identifier MUST NOT appear in `available_licenses` (but, rather, the field `license` is to be used to clarify the licensing situation.) +An empty list indicates that none of the SPDX licenses apply for the entirety of the database and that the licensing situation is clarified in human readable form in the field `license`.""", + ) is_index: Optional[bool] = StrictField( default=False, description="If true, this is an index meta-database base URL (see section Index Meta-Database). " From aae573370f6969fbb5040bf7f27e5abeedbc0f06 Mon Sep 17 00:00:00 2001 From: Matthew Evans Date: Tue, 6 Dec 2022 21:38:57 +0000 Subject: [PATCH 07/19] Add configurable `license` value and use it in the `/info` response --- optimade/server/config.py | 7 +++++++ optimade/server/routers/info.py | 2 ++ 2 files changed, 9 insertions(+) diff --git a/optimade/server/config.py b/optimade/server/config.py index 4dc360f73..5ef7addf4 100644 --- a/optimade/server/config.py +++ b/optimade/server/config.py @@ -291,6 +291,13 @@ class ServerConfig(BaseSettings): ), ) + license: str = Field( + "CC-BY-4.0", + description="""The SPDX license identifier that will be linked to by the server under the info field `license`. +The `license` field value will be constructed from this identifier preprended with `https://spdx.org/licenses/CC-BY-4.0`, and the identifier will also be added to the `available_licenses` field directly. +There is currently no support for providing a full list of identifiers to be served at `available_licenses`.""", + ) + log_level: LogLevel = Field( LogLevel.INFO, description="Logging level for the OPTIMADE server." ) diff --git a/optimade/server/routers/info.py b/optimade/server/routers/info.py index 4b351f371..0fec192d6 100644 --- a/optimade/server/routers/info.py +++ b/optimade/server/routers/info.py @@ -44,6 +44,8 @@ def _generate_info_response() -> BaseInfoResource: available_endpoints=["info", "links"] + list(ENTRY_INFO_SCHEMAS.keys()), entry_types_by_format={"json": list(ENTRY_INFO_SCHEMAS.keys())}, is_index=False, + license={"href": f"https://spdx.org/licenses/{CONFIG.license}"}, + available_licenses=[CONFIG.license], ), ) From 3c42b3284ce473de566a139c1e54edb522f934ff Mon Sep 17 00:00:00 2001 From: Matthew Evans Date: Tue, 6 Dec 2022 19:14:54 +0000 Subject: [PATCH 08/19] Add configurable `request_delay` support to server and models --- openapi/index_openapi.json | 6 ++++++ openapi/openapi.json | 6 ++++++ optimade/models/optimade_json.py | 14 +++++++++++++- optimade/server/config.py | 14 ++++++++++++++ optimade/server/routers/utils.py | 4 ++++ 5 files changed, 43 insertions(+), 1 deletion(-) diff --git a/openapi/index_openapi.json b/openapi/index_openapi.json index 337e33d09..95a0d8e37 100644 --- a/openapi/index_openapi.json +++ b/openapi/index_openapi.json @@ -1699,6 +1699,12 @@ "title": "Response Message", "description": "response string from the server" }, + "request_delay": { + "title": "Request Delay", + "minimum": 0.0, + "type": "number", + "description": "A non-negative float giving time in seconds that the client is suggested to wait before issuing a subsequent request." + }, "implementation": { "allOf": [ { diff --git a/openapi/openapi.json b/openapi/openapi.json index 2919f7313..6fac6c4fe 100644 --- a/openapi/openapi.json +++ b/openapi/openapi.json @@ -3523,6 +3523,12 @@ "title": "Response Message", "description": "response string from the server" }, + "request_delay": { + "title": "Request Delay", + "minimum": 0.0, + "type": "number", + "description": "A non-negative float giving time in seconds that the client is suggested to wait before issuing a subsequent request." + }, "implementation": { "allOf": [ { diff --git a/optimade/models/optimade_json.py b/optimade/models/optimade_json.py index 2ad7f4d0b..97b6e799f 100644 --- a/optimade/models/optimade_json.py +++ b/optimade/models/optimade_json.py @@ -4,7 +4,14 @@ from enum import Enum from typing import Any, Optional, Union -from pydantic import AnyHttpUrl, AnyUrl, BaseModel, EmailStr, root_validator +from pydantic import ( + AnyHttpUrl, + AnyUrl, + BaseModel, + EmailStr, + NonNegativeFloat, + root_validator, +) from optimade.models import jsonapi from optimade.models.utils import SemanticVersion, StrictField @@ -324,6 +331,11 @@ class ResponseMeta(jsonapi.Meta): None, description="response string from the server" ) + request_delay: Optional[NonNegativeFloat] = StrictField( + None, + description="A non-negative float giving time in seconds that the client is suggested to wait before issuing a subsequent request.", + ) + implementation: Optional[Implementation] = StrictField( None, description="a dictionary describing the server implementation" ) diff --git a/optimade/server/config.py b/optimade/server/config.py index 5ef7addf4..50dbdf10a 100644 --- a/optimade/server/config.py +++ b/optimade/server/config.py @@ -316,6 +316,13 @@ class ServerConfig(BaseSettings): only the mapping of aliases will occur.""", ) + request_delay: Optional[float] = Field( + None, + description=( + "The value to use for the `meta->request_delay` field, which indicates to clients how long they should leave between success queries." + ), + ) + @validator("implementation", pre=True) def set_implementation_version(cls, v): """Set defaults and modify bypassed value(s)""" @@ -323,6 +330,13 @@ def set_implementation_version(cls, v): res.update(v) return res + @validator("request_delay", pre=True) + def check_request_delay(cls, v): + """Check `request_delay` is non-negative.""" + if v is not None and v < 0: + raise ValueError("`request_delay` must be non-negative") + return v + @root_validator(pre=True) def use_real_mongo_override(cls, values): """Overrides the `database_backend` setting with MongoDB and diff --git a/optimade/server/routers/utils.py b/optimade/server/routers/utils.py index 16928ace8..2a1086b3d 100644 --- a/optimade/server/routers/utils.py +++ b/optimade/server/routers/utils.py @@ -76,6 +76,10 @@ def meta_values( if schema is None: schema = CONFIG.schema_url if not CONFIG.is_index else CONFIG.index_schema_url + if CONFIG.request_delay is not None: + # Add request delay via **kwargs only so that it is not set to null by default + kwargs["request_delay"] = CONFIG.request_delay + return ResponseMeta( query=ResponseMetaQuery(representation=f"{url_path}?{url.query}"), api_version=__api_version__, From 4b5c088e29671337eacf97cafde409987240b1a5 Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Fri, 26 Aug 2022 13:16:24 +0200 Subject: [PATCH 09/19] Added model for files endpoint. --- docs/api_reference/models/files.md | 5 + docs/api_reference/server/mappers/files.md | 3 + docs/api_reference/server/routers/files.md | 3 + optimade/models/__init__.py | 22 +- optimade/models/files.py | 232 +++++++++++++++++++++ optimade/models/responses.py | 17 ++ optimade/server/config.py | 4 + optimade/server/data/__init__.py | 1 + optimade/server/data/test_files.json | 4 + optimade/server/mappers/__init__.py | 2 + optimade/server/mappers/files.py | 9 + optimade/server/routers/__init__.py | 2 + optimade/server/routers/files.py | 58 ++++++ 13 files changed, 352 insertions(+), 10 deletions(-) create mode 100644 docs/api_reference/models/files.md create mode 100644 docs/api_reference/server/mappers/files.md create mode 100644 docs/api_reference/server/routers/files.md create mode 100644 optimade/models/files.py create mode 100644 optimade/server/data/test_files.json create mode 100644 optimade/server/mappers/files.py create mode 100644 optimade/server/routers/files.py diff --git a/docs/api_reference/models/files.md b/docs/api_reference/models/files.md new file mode 100644 index 000000000..e60e4ad6b --- /dev/null +++ b/docs/api_reference/models/files.md @@ -0,0 +1,5 @@ +# files + +::: optimade.models.files + options: + show_if_no_docstring: true diff --git a/docs/api_reference/server/mappers/files.md b/docs/api_reference/server/mappers/files.md new file mode 100644 index 000000000..75d3c94f2 --- /dev/null +++ b/docs/api_reference/server/mappers/files.md @@ -0,0 +1,3 @@ +# files + +::: optimade.server.mappers.files diff --git a/docs/api_reference/server/routers/files.md b/docs/api_reference/server/routers/files.md new file mode 100644 index 000000000..a987dfb69 --- /dev/null +++ b/docs/api_reference/server/routers/files.md @@ -0,0 +1,3 @@ +# files + +::: optimade.server.routers.files diff --git a/optimade/models/__init__.py b/optimade/models/__init__.py index 018560412..aecd1a6a7 100644 --- a/optimade/models/__init__.py +++ b/optimade/models/__init__.py @@ -8,17 +8,19 @@ from .references import * # noqa: F403 from .responses import * # noqa: F403 from .structures import * # noqa: F403 +from .files import * # noqa: F403 from .utils import * # noqa: F403 __all__ = ( - jsonapi.__all__ # type: ignore[name-defined] # noqa: F405 - + utils.__all__ # type: ignore[name-defined] # noqa: F405 - + baseinfo.__all__ # type: ignore[name-defined] # noqa: F405 - + entries.__all__ # type: ignore[name-defined] # noqa: F405 - + index_metadb.__all__ # type: ignore[name-defined] # noqa: F405 - + links.__all__ # type: ignore[name-defined] # noqa: F405 - + optimade_json.__all__ # type: ignore[name-defined] # noqa: F405 - + references.__all__ # type: ignore[name-defined] # noqa: F405 - + responses.__all__ # type: ignore[name-defined] # noqa: F405 - + structures.__all__ # type: ignore[name-defined] # noqa: F405 + jsonapi.__all__ # noqa: F405 + + utils.__all__ # noqa: F405 + + baseinfo.__all__ # noqa: F405 + + entries.__all__ # noqa: F405 + + index_metadb.__all__ # noqa: F405 + + links.__all__ # noqa: F405 + + optimade_json.__all__ # noqa: F405 + + references.__all__ # noqa: F405 + + responses.__all__ # noqa: F405 + + structures.__all__ # noqa: F405 + + files.__all__ # noqa: F405 ) diff --git a/optimade/models/files.py b/optimade/models/files.py new file mode 100644 index 000000000..96bf4b09c --- /dev/null +++ b/optimade/models/files.py @@ -0,0 +1,232 @@ +# pylint: disable=no-self-argument,line-too-long,no-name-in-module +from datetime import datetime +from typing import Optional, Dict +from optimade.models.entries import EntryResourceAttributes, EntryResource +from optimade.models.utils import ( + OptimadeField, + StrictField, + SupportLevel, +) + + +__all__ = ( + "FileResourceAttributes", + "FileResource", +) + + +CORRELATED_FILE_FIELDS = ( + {}, + {}, +) + + +class FileResourceAttributes(EntryResourceAttributes): + """This class contains the Field for the attributes used to represent a file, e.g. .""" + + url: str = OptimadeField( + ..., + description="""The URL to get the contents of a file. +- **Type**: string +- **Requirements/Conventions**: + + - **Support**: MUST be supported by all implementations, MUST NOT be :val:`null`. + - **Query**: Support for queries on this property is OPTIONAL. + - **Response**: REQUIRED in the response. + - The URL MUST point to the actual contents of a file (i.e. byte stream), not an intermediate (preview) representation. + For example, if referring to a file on GitHub, a link should point to raw contents. + +- **Examples**: + + - :val:`"https://example.org/files/cifs/1000000.cif"` +""", + support=SupportLevel.MUST, + queryable=SupportLevel.OPTIONAL, + ) + + url_stable_until: Optional[datetime] = OptimadeField( + ..., + description="""Point in time until which the URL in `url` is guaranteed to stay stable. +- **Type**: timestamp +- **Requirements/Conventions**: + + - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. + - **Query**: Support for queries on this property is OPTIONAL. + - :val:`null` means that there is no stability guarantee for the URL in `url`. + Indefinite support could be communicated by providing a date sufficiently far in the future, for example, :val:`9999-12-31`.""", + support=SupportLevel.OPTIONAL, + queryable=SupportLevel.OPTIONAL, + ) + + name: str = OptimadeField( + ..., + description="""Base name of a file. +- **Type**: string +- **Requirements/Conventions**: + + - **Support**: MUST be supported by all implementations, MUST NOT be :val:`null`. + - **Query**: Support for queries on this property is OPTIONAL. + - File name extension is an integral part of a file name and, if available, MUST be included. + +- **Examples**: + + - :val:`"1000000.cif"`""", + support=SupportLevel.MUST, + queryable=SupportLevel.OPTIONAL, + ) + + size: Optional[int] = OptimadeField( + ..., + description="""Size of a file in bytes. +- **Type**: integer +- **Requirements/Conventions**: + + - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. + - **Query**: Support for queries on this property is OPTIONAL. + - If provided, it MUST be guaranteed that either exact size of a file is given or its upper bound. + This way if a client reserves a static buffer or truncates the download stream after this many bytes the whole file would be received. + Such provision is included to allow the providers to serve on-the-fly compressed files.""", + support=SupportLevel.OPTIONAL, + queryable=SupportLevel.OPTIONAL, + ) + + media_type: Optional[str] = OptimadeField( + ..., + description="""Media type identifier (also known as MIME type), for a file as per `RFC 6838 Media Type Specifications and Registration Procedures `__. +- **Type**: string +- **Requirements/Conventions**: + + - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. + - **Query**: Support for queries on this property is OPTIONAL. + +- **Examples**: + + - :val:`"chemical/x-cif"`""", + support=SupportLevel.OPTIONAL, + queryable=SupportLevel.OPTIONAL, + ) + + version: Optional[str] = OptimadeField( + None, + description="""Version information of a file (e.g. commit, revision, timestamp). +- **Type**: string +- **Requirements/Conventions**: + + - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. + - **Query**: Support for queries on this property is OPTIONAL. + - If provided, it MUST be guaranteed that file contents pertaining to the same combination of :field:`id` and :field:`version` are the same""", + support=SupportLevel.OPTIONAL, + queryable=SupportLevel.OPTIONAL, + ) + + modification_timestamp: Optional[datetime] = OptimadeField( + ..., + description="""Timestamp of the last modification of file contents. + A modification is understood as an addition, change or deletion of one or more bytes, resulting in file contents different from the previous. +- **Type**: timestamp +- **Requirements/Conventions**: + + - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. + - **Query**: Support for queries on this property is OPTIONAL. + - Timestamps of subsequent file modifications SHOULD be increasing (not earlier than previous timestamps).""", + support=SupportLevel.OPTIONAL, + queryable=SupportLevel.OPTIONAL, + ) + + description: Optional[str] = OptimadeField( + ..., + description="""Free-form description of a file. +- **Type**: string +- **Requirements/Conventions**: + + - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. + - **Query**: Support for queries on this property is OPTIONAL. + +- **Examples**: + + - :val:`"POSCAR format file"`""", + support=SupportLevel.OPTIONAL, + queryable=SupportLevel.OPTIONAL, + ) + + checksums: Optional[Dict[str, str]] = OptimadeField( + ..., + description="""Dictionary providing checksums of file contents. +* **Type**: dictionary with keys identifying checksum functions and values (strings) giving the actual checksums +* **Requirements/Conventions**: + + - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. + - **Query**: Support for queries on this property is OPTIONAL. + - Supported dictionary keys: :property:`md5`, :property:`sha1`, :property:`sha224`, :property:`sha256`, :property:`sha384`, :property:`sha512`. + Checksums outside this list MAY be used, but their names MUST be prefixed by database-provider-specific namespace prefix (see appendix `Database-Provider-Specific Namespace Prefixes`_). +""", + support=SupportLevel.OPTIONAL, + queryable=SupportLevel.OPTIONAL, + ) + + atime: Optional[datetime] = OptimadeField( + ..., + description="""Time of last access of a file as per POSIX standard. +- **Type**: timestamp +- **Requirements/Conventions**: + + - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. + - **Query**: Support for queries on this property is OPTIONAL.""", + support=SupportLevel.OPTIONAL, + queryable=SupportLevel.OPTIONAL, + ) + + ctime: Optional[datetime] = OptimadeField( + ..., + description="""Time of last status change of a file as per POSIX standard. +- **Type**: timestamp +- **Requirements/Conventions**: + + - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. + - **Query**: Support for queries on this property is OPTIONAL.""", + unit="Å", + support=SupportLevel.OPTIONAL, + queryable=SupportLevel.OPTIONAL, + ) + + mtime: Optional[datetime] = OptimadeField( + ..., + description=""" Time of last modification of a file as per POSIX standard. +- **Type**: timestamp +- **Requirements/Conventions**: + + - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. + - **Query**: Support for queries on this property is OPTIONAL. + - It should be noted that the values of :field:`last_modified`, :field:`modification_timestamp` and :field:`mtime` do not necessary match. + :field:`last_modified` pertains to the modification of the OPTIMADE metadata, :field:`modification_timestamp` pertains to file contents and :field:`mtime` pertains to the modification of the file (not necessary changing its contents). + For example, appending an empty string to a file would result in the change of :field:`mtime` in some operating systems, but this would not be deemed as a modification of its contents. +""", + queryable=SupportLevel.OPTIONAL, + support=SupportLevel.OPTIONAL, + ) + + +class FileResource(EntryResource): + """Representing a structure.""" + + type: str = StrictField( + "files", + description="""The name of the type of an entry. + +- **Type**: string. + +- **Requirements/Conventions**: + - **Support**: MUST be supported by all implementations, MUST NOT be `null`. + - **Query**: MUST be a queryable property with support for all mandatory filter features. + - **Response**: REQUIRED in the response. + - MUST be an existing entry type. + - The entry of type `` and ID `` MUST be returned in response to a request for `//` under the versioned base URL. + +- **Examples**: + - `"structures"`""", + regex="^files$", + support=SupportLevel.MUST, + queryable=SupportLevel.MUST, + ) + + attributes: FileResourceAttributes diff --git a/optimade/models/responses.py b/optimade/models/responses.py index c883a0093..2a313c18b 100644 --- a/optimade/models/responses.py +++ b/optimade/models/responses.py @@ -11,6 +11,7 @@ from optimade.models.optimade_json import OptimadeError, ResponseMeta, Success from optimade.models.references import ReferenceResource from optimade.models.structures import StructureResource +from optimade.models.files import FileResource from optimade.models.utils import StrictField __all__ = ( @@ -23,6 +24,8 @@ "EntryResponseMany", "StructureResponseOne", "StructureResponseMany", + "FileResponseOne", + "FileResponseMany", "ReferenceResponseOne", "ReferenceResponseMany", ) @@ -103,6 +106,20 @@ class StructureResponseMany(EntryResponseMany): ) +class FileResponseOne(EntryResponseOne): + data: Union[FileResource, Dict[str, Any], None] = StrictField( + ..., description="A single files entry resource." + ) + + +class FileResponseMany(EntryResponseMany): + data: Union[List[FileResource], List[Dict[str, Any]]] = StrictField( + ..., + description="List of unique OPTIMADE files entry resource objects.", + uniqueItems=True, + ) + + class ReferenceResponseOne(EntryResponseOne): data: Union[ReferenceResource, dict[str, Any], None] = StrictField( ..., description="A single references entry resource." diff --git a/optimade/server/config.py b/optimade/server/config.py index 50dbdf10a..6aed7a2f6 100644 --- a/optimade/server/config.py +++ b/optimade/server/config.py @@ -178,6 +178,10 @@ class ServerConfig(BaseSettings): "structures", description="Mongo collection name for /structures endpoint resources", ) + files_collection: str = Field( + "files", + description="Mongo collection name for /files endpoint resources", + ) page_limit: int = Field(20, description="Default number of resources per page") page_limit_max: int = Field( 500, description="Max allowed number of resources per page" diff --git a/optimade/server/data/__init__.py b/optimade/server/data/__init__.py index 87060d387..e6e90a7d6 100644 --- a/optimade/server/data/__init__.py +++ b/optimade/server/data/__init__.py @@ -7,6 +7,7 @@ "structures": "test_structures.json", "references": "test_references.json", "links": "test_links.json", + "files": "test_files.json", "providers": "providers.json", } diff --git a/optimade/server/data/test_files.json b/optimade/server/data/test_files.json new file mode 100644 index 000000000..f56b9db21 --- /dev/null +++ b/optimade/server/data/test_files.json @@ -0,0 +1,4 @@ +[{"url": "www.example.com/file001.pdb", "name": "file001.pdb", "size": 12536, "media_type": "chemical/x-pdb","modification_timestamp": { + "$date": "2022-08-26T13:09:37.945Z" + } +}] diff --git a/optimade/server/mappers/__init__.py b/optimade/server/mappers/__init__.py index c38e6ccd0..27d0e8e44 100644 --- a/optimade/server/mappers/__init__.py +++ b/optimade/server/mappers/__init__.py @@ -3,10 +3,12 @@ from .links import * # noqa: F403 from .references import * # noqa: F403 from .structures import * # noqa: F403 +from .files import * # noqa: F403 __all__ = ( entries.__all__ # type: ignore[name-defined] # noqa: F405 + links.__all__ # type: ignore[name-defined] # noqa: F405 + references.__all__ # type: ignore[name-defined] # noqa: F405 + structures.__all__ # type: ignore[name-defined] # noqa: F405 + + files.__all__ # noqa: F405 ) diff --git a/optimade/server/mappers/files.py b/optimade/server/mappers/files.py new file mode 100644 index 000000000..29b80df6a --- /dev/null +++ b/optimade/server/mappers/files.py @@ -0,0 +1,9 @@ +from optimade.server.mappers.entries import BaseResourceMapper +from optimade.models.files import FileResource + +__all__ = ("FileMapper",) + + +class FileMapper(BaseResourceMapper): + + ENTRY_RESOURCE_CLASS = FileResource diff --git a/optimade/server/routers/__init__.py b/optimade/server/routers/__init__.py index 266518dbe..3c74f8bf2 100644 --- a/optimade/server/routers/__init__.py +++ b/optimade/server/routers/__init__.py @@ -1,9 +1,11 @@ from .links import links_coll from .references import references_coll from .structures import structures_coll +from .files import files_coll ENTRY_COLLECTIONS = { "links": links_coll, "references": references_coll, "structures": structures_coll, + "files": files_coll, } diff --git a/optimade/server/routers/files.py b/optimade/server/routers/files.py new file mode 100644 index 000000000..3a5846f3d --- /dev/null +++ b/optimade/server/routers/files.py @@ -0,0 +1,58 @@ +from fastapi import APIRouter, Depends, Request + +from optimade.models import ( + FileResource, + FileResponseMany, + FileResponseOne, +) +from optimade.server.config import CONFIG +from optimade.server.entry_collections import create_collection +from optimade.server.mappers import FileMapper +from optimade.server.query_params import EntryListingQueryParams, SingleEntryQueryParams +from optimade.server.routers.utils import get_entries, get_single_entry +from optimade.server.schemas import ERROR_RESPONSES + +router = APIRouter(redirect_slashes=True) + +files_coll = create_collection( + name=CONFIG.files_collection, + resource_cls=FileResource, + resource_mapper=FileMapper, +) + + +@router.get( + "/files", + response_model=FileResponseMany, + response_model_exclude_unset=True, + tags=["Files"], + responses=ERROR_RESPONSES, +) +def get_files( + request: Request, params: EntryListingQueryParams = Depends() +) -> FileResponseMany: + return get_entries( + collection=files_coll, + response=FileResponseMany, + request=request, + params=params, + ) + + +@router.get( + "/files/{entry_id:path}", + response_model=FileResponseOne, + response_model_exclude_unset=True, + tags=["Files"], + responses=ERROR_RESPONSES, +) +def get_single_file( + request: Request, entry_id: str, params: SingleEntryQueryParams = Depends() +) -> FileResponseOne: + return get_single_entry( + collection=files_coll, + entry_id=entry_id, + response=FileResponseOne, + request=request, + params=params, + ) From b165e366dba4e8ab56321d7c055b01653e5856bb Mon Sep 17 00:00:00 2001 From: Johan Bergsma <29785380+JPBergsma@users.noreply.github.com> Date: Fri, 2 Sep 2022 19:06:15 +0200 Subject: [PATCH 10/19] Storing intermediate code state in implementing the files endpoint. --- optimade/server/config.py | 4 +- .../test_entry_collections.py | 2 + tests/server/routers/test_files.py | 221 ++++++++++++++++++ 3 files changed, 226 insertions(+), 1 deletion(-) create mode 100644 tests/server/routers/test_files.py diff --git a/optimade/server/config.py b/optimade/server/config.py index 6aed7a2f6..fa9187d75 100644 --- a/optimade/server/config.py +++ b/optimade/server/config.py @@ -238,7 +238,9 @@ class ServerConfig(BaseSettings): "broken down by endpoint." ), ) - aliases: dict[Literal["links", "references", "structures"], dict[str, str]] = Field( + aliases: dict[ + Literal["links", "references", "structures", "files"], dict[str, str] + ] = Field( {}, description=( "A mapping between field names in the database with their corresponding OPTIMADE field" diff --git a/tests/server/entry_collections/test_entry_collections.py b/tests/server/entry_collections/test_entry_collections.py index a5f537698..de820429b 100644 --- a/tests/server/entry_collections/test_entry_collections.py +++ b/tests/server/entry_collections/test_entry_collections.py @@ -7,6 +7,7 @@ def test_get_attribute_fields(): LinksResourceAttributes, ReferenceResourceAttributes, StructureResourceAttributes, + FileResourceAttributes, ) from optimade.server.routers import ENTRY_COLLECTIONS @@ -14,6 +15,7 @@ def test_get_attribute_fields(): "links": LinksResourceAttributes, "references": ReferenceResourceAttributes, "structures": StructureResourceAttributes, + "files": FileResourceAttributes, } # Make sure we're hitting all collections diff --git a/tests/server/routers/test_files.py b/tests/server/routers/test_files.py new file mode 100644 index 000000000..406a05446 --- /dev/null +++ b/tests/server/routers/test_files.py @@ -0,0 +1,221 @@ +from optimade.models import ( + FileResponseMany, + # FileResponseOne, + # FileResource, +) + +from ..utils import RegularEndpointTests + + +class TestFilesEndpoint(RegularEndpointTests): + """Tests for /structures""" + + request_str = "/files" + response_cls = FileResponseMany + + def test_files_endpoint_data(self): + """Check known properties/attributes for successful response""" + assert "meta" in self.json_response + assert self.json_response["meta"]["data_available"] == 17 + assert not self.json_response["meta"]["more_data_available"] + assert "data" in self.json_response + assert ( + len(self.json_response["data"]) + == self.json_response["meta"]["data_available"] + ) + + +# def test_get_next_responses(self, get_good_response): +# """Check pagination""" +# total_data = self.json_response["meta"]["data_available"] +# page_limit = 5 +# +# json_response = get_good_response( +# self.request_str + f"?page_limit={page_limit}" +# ) +# +# cursor = json_response["data"].copy() +# assert json_response["meta"]["more_data_available"] +# assert json_response["meta"]["data_returned"] == total_data +# more_data_available = True +# next_request = json_response["links"]["next"] +# +# while more_data_available: +# next_response = get_good_response(next_request) +# assert next_response["meta"]["data_returned"] == total_data +# next_request = next_response["links"]["next"] +# cursor.extend(next_response["data"]) +# more_data_available = next_response["meta"]["more_data_available"] +# if more_data_available: +# assert len(next_response["data"]) == page_limit +# else: +# assert len(next_response["data"]) == total_data % page_limit +# +# assert len(cursor) == total_data +# +# +# class TestSingleFileeEndpoint(RegularEndpointTests): +# """Tests for /files/""" +# +# test_id = "mpf_1" +# request_str = f"/files/{test_id}" +# response_cls = FileResponseOne +# +# def test_structures_endpoint_data(self): +# """Check known properties/attributes for successful response""" +# assert "data" in self.json_response +# assert self.json_response["data"]["id"] == self.test_id +# assert self.json_response["data"]["type"] == "structures" +# assert "attributes" in self.json_response["data"] +# assert "_exmpl_chemsys" in self.json_response["data"]["attributes"] +# +# +# def test_check_response_single_structure(check_response): +# """Tests whether check_response also handles single endpoint queries correctly.""" +# +# test_id = "mpf_1" +# expected_ids = "mpf_1" +# request = f"/files/{test_id}?response_fields=name" +# check_response(request, expected_ids=expected_ids) +# +# +# class TestMissingSingleStructureEndpoint(RegularEndpointTests): +# """Tests for /structures/ for unknown """ +# +# test_id = "mpf_random_string_that_is_not_in_test_data" +# request_str = f"/structures/{test_id}" +# response_cls = StructureResponseOne +# +# def test_structures_endpoint_data(self): +# """Check known properties/attributes for successful response""" +# assert "data" in self.json_response +# assert "meta" in self.json_response +# assert self.json_response["data"] is None +# assert self.json_response["meta"]["data_returned"] == 0 +# assert not self.json_response["meta"]["more_data_available"] +# +# +# class TestSingleStructureWithRelationships(RegularEndpointTests): +# """Tests for /structures/, where has relationships""" +# +# test_id = "mpf_1" +# request_str = f"/structures/{test_id}" +# response_cls = StructureResponseOne +# +# def test_structures_endpoint_data(self): +# """Check known properties/attributes for successful response""" +# assert "data" in self.json_response +# assert self.json_response["data"]["id"] == self.test_id +# assert self.json_response["data"]["type"] == "structures" +# assert "attributes" in self.json_response["data"] +# assert "relationships" in self.json_response["data"] +# assert self.json_response["data"]["relationships"] == { +# "references": {"data": [{"type": "references", "id": "dijkstra1968"}]} +# } +# assert "included" in self.json_response +# assert len( +# self.json_response["data"]["relationships"]["references"]["data"] +# ) == len(self.json_response["included"]) +# +# ReferenceResource(**self.json_response["included"][0]) +# +# +# class TestMultiStructureWithSharedRelationships(RegularEndpointTests): +# """Tests for /structures for entries with shared relationships""" +# +# request_str = '/structures?filter=id="mpf_1" OR id="mpf_2"' +# response_cls = StructureResponseMany +# +# def test_structures_endpoint_data(self): +# """Check known properties/attributes for successful response""" +# # mpf_1 and mpf_2 both contain the same reference relationship, so response should not duplicate it +# assert "data" in self.json_response +# assert len(self.json_response["data"]) == 2 +# assert "included" in self.json_response +# assert len(self.json_response["included"]) == 1 +# +# +# class TestMultiStructureWithRelationships(RegularEndpointTests): +# """Tests for /structures for mixed entries with and without relationships""" +# +# request_str = '/structures?filter=id="mpf_1" OR id="mpf_23"' +# response_cls = StructureResponseMany +# +# def test_structures_endpoint_data(self): +# """Check known properties/attributes for successful response""" +# # mpf_23 contains no relationships, which shouldn't break anything +# assert "data" in self.json_response +# assert len(self.json_response["data"]) == 2 +# assert "included" in self.json_response +# assert len(self.json_response["included"]) == 1 +# +# +# class TestMultiStructureWithOverlappingRelationships(RegularEndpointTests): +# """Tests for /structures with entries with overlapping relationships +# +# One entry has multiple relationships, another entry has other relationships, +# some of these relationships overlap between the entries, others don't. +# """ +# +# request_str = '/structures?filter=id="mpf_1" OR id="mpf_3"' +# response_cls = StructureResponseMany +# +# def test_structures_endpoint_data(self): +# """Check known properties/attributes for successful response""" +# assert "data" in self.json_response +# assert len(self.json_response["data"]) == 2 +# assert "included" in self.json_response +# assert len(self.json_response["included"]) == 2 +# +# +# class TestStructuresWithNullFieldsDoNotMatchNegatedFilters(RegularEndpointTests): +# """Tests that structures with e.g., `'assemblies':null` do not get +# returned for negated queries like `filter=assemblies != 1`, as mandated +# by the specification. +# +# """ +# +# request_str = "/structures?filter=assemblies != 1" +# response_cls = StructureResponseMany +# +# def test_structures_endpoint_data(self): +# """Check that no structures are returned.""" +# assert len(self.json_response["data"]) == 0 +# +# +# class TestStructuresWithNullFieldsMatchUnknownFilter(RegularEndpointTests): +# """Tests that structures with e.g., `'assemblies':null` do get +# returned for queries testing for "UNKNOWN" fields. +# +# """ +# +# request_str = "/structures?filter=assemblies IS UNKNOWN" +# response_cls = StructureResponseMany +# +# def test_structures_endpoint_data(self): +# """Check that all structures are returned.""" +# assert len(self.json_response["data"]) == 17 +# +# +# class TestStructuresWithUnknownResponseFields(RegularEndpointTests): +# """Tests that structures with e.g., `'assemblies':null` do get +# returned for queries testing for "UNKNOWN" fields. +# +# """ +# +# request_str = "/structures?filter=assemblies IS UNKNOWN&response_fields=assemblies,_other_provider_field,chemical_formula_anonymous" +# response_cls = StructureResponseMany +# +# def test_structures_endpoint_data(self): +# """Check that all structures are returned.""" +# assert len(self.json_response["data"]) == 17 +# keys = ("_other_provider_field", "assemblies", "chemical_formula_anonymous") +# for key in keys: +# assert all(key in doc["attributes"] for doc in self.json_response["data"]) +# assert all( +# doc["attributes"]["_other_provider_field"] is None +# for doc in self.json_response["data"] +# ) +# assert all( +# len(doc["attributes"]) == len(keys) for doc in self.json_response["data"] +# ) From 59ed1f6f68622220dc4553bb24f9b08231fc5916 Mon Sep 17 00:00:00 2001 From: Matthew Evans Date: Tue, 6 Dec 2022 15:46:28 +0000 Subject: [PATCH 11/19] Linting --- optimade/models/__init__.py | 24 +++++++++---------- optimade/models/files.py | 15 ++++-------- optimade/models/responses.py | 2 +- optimade/server/mappers/__init__.py | 4 ++-- optimade/server/mappers/files.py | 2 +- optimade/server/routers/__init__.py | 2 +- optimade/server/routers/files.py | 6 +---- .../test_entry_collections.py | 2 +- tests/server/routers/test_files.py | 6 +---- 9 files changed, 24 insertions(+), 39 deletions(-) diff --git a/optimade/models/__init__.py b/optimade/models/__init__.py index aecd1a6a7..622423d2b 100644 --- a/optimade/models/__init__.py +++ b/optimade/models/__init__.py @@ -1,6 +1,7 @@ # pylint: disable=undefined-variable from .baseinfo import * # noqa: F403 from .entries import * # noqa: F403 +from .files import * # noqa: F403 from .index_metadb import * # noqa: F403 from .jsonapi import * # noqa: F403 from .links import * # noqa: F403 @@ -8,19 +9,18 @@ from .references import * # noqa: F403 from .responses import * # noqa: F403 from .structures import * # noqa: F403 -from .files import * # noqa: F403 from .utils import * # noqa: F403 __all__ = ( - jsonapi.__all__ # noqa: F405 - + utils.__all__ # noqa: F405 - + baseinfo.__all__ # noqa: F405 - + entries.__all__ # noqa: F405 - + index_metadb.__all__ # noqa: F405 - + links.__all__ # noqa: F405 - + optimade_json.__all__ # noqa: F405 - + references.__all__ # noqa: F405 - + responses.__all__ # noqa: F405 - + structures.__all__ # noqa: F405 - + files.__all__ # noqa: F405 + jsonapi.__all__ # type: ignore[name-defined] # noqa: F405 + + utils.__all__ # type: ignore[name-defined] # noqa: F405 + + baseinfo.__all__ # type: ignore[name-defined] # noqa: F405 + + entries.__all__ # type: ignore[name-defined] # noqa: F405 + + index_metadb.__all__ # type: ignore[name-defined] # noqa: F405 + + links.__all__ # type: ignore[name-defined] # noqa: F405 + + optimade_json.__all__ # type: ignore[name-defined] # noqa: F405 + + references.__all__ # type: ignore[name-defined] # noqa: F405 + + responses.__all__ # type: ignore[name-defined] # noqa: F405 + + structures.__all__ # type: ignore[name-defined] # noqa: F405 + + files.__all__ # type: ignore[name-defined] # noqa: F405 ) diff --git a/optimade/models/files.py b/optimade/models/files.py index 96bf4b09c..f72a867df 100644 --- a/optimade/models/files.py +++ b/optimade/models/files.py @@ -1,13 +1,9 @@ # pylint: disable=no-self-argument,line-too-long,no-name-in-module from datetime import datetime -from typing import Optional, Dict -from optimade.models.entries import EntryResourceAttributes, EntryResource -from optimade.models.utils import ( - OptimadeField, - StrictField, - SupportLevel, -) +from typing import Dict, Optional, Set, Tuple +from optimade.models.entries import EntryResource, EntryResourceAttributes +from optimade.models.utils import OptimadeField, StrictField, SupportLevel __all__ = ( "FileResourceAttributes", @@ -15,10 +11,7 @@ ) -CORRELATED_FILE_FIELDS = ( - {}, - {}, -) +CORRELATED_FILE_FIELDS: Tuple[Set[str], ...] class FileResourceAttributes(EntryResourceAttributes): diff --git a/optimade/models/responses.py b/optimade/models/responses.py index 2a313c18b..c0fceb8fd 100644 --- a/optimade/models/responses.py +++ b/optimade/models/responses.py @@ -5,13 +5,13 @@ from optimade.models.baseinfo import BaseInfoResource from optimade.models.entries import EntryInfoResource, EntryResource +from optimade.models.files import FileResource from optimade.models.index_metadb import IndexInfoResource from optimade.models.jsonapi import Response from optimade.models.links import LinksResource from optimade.models.optimade_json import OptimadeError, ResponseMeta, Success from optimade.models.references import ReferenceResource from optimade.models.structures import StructureResource -from optimade.models.files import FileResource from optimade.models.utils import StrictField __all__ = ( diff --git a/optimade/server/mappers/__init__.py b/optimade/server/mappers/__init__.py index 27d0e8e44..9693dd9fa 100644 --- a/optimade/server/mappers/__init__.py +++ b/optimade/server/mappers/__init__.py @@ -1,14 +1,14 @@ # pylint: disable=undefined-variable from .entries import * # noqa: F403 +from .files import * # noqa: F403 from .links import * # noqa: F403 from .references import * # noqa: F403 from .structures import * # noqa: F403 -from .files import * # noqa: F403 __all__ = ( entries.__all__ # type: ignore[name-defined] # noqa: F405 + links.__all__ # type: ignore[name-defined] # noqa: F405 + references.__all__ # type: ignore[name-defined] # noqa: F405 + structures.__all__ # type: ignore[name-defined] # noqa: F405 - + files.__all__ # noqa: F405 + + files.__all__ # type: ignore[name-defined] # noqa: F405 ) diff --git a/optimade/server/mappers/files.py b/optimade/server/mappers/files.py index 29b80df6a..0184a36a3 100644 --- a/optimade/server/mappers/files.py +++ b/optimade/server/mappers/files.py @@ -1,5 +1,5 @@ -from optimade.server.mappers.entries import BaseResourceMapper from optimade.models.files import FileResource +from optimade.server.mappers.entries import BaseResourceMapper __all__ = ("FileMapper",) diff --git a/optimade/server/routers/__init__.py b/optimade/server/routers/__init__.py index 3c74f8bf2..a9157cf18 100644 --- a/optimade/server/routers/__init__.py +++ b/optimade/server/routers/__init__.py @@ -1,7 +1,7 @@ +from .files import files_coll from .links import links_coll from .references import references_coll from .structures import structures_coll -from .files import files_coll ENTRY_COLLECTIONS = { "links": links_coll, diff --git a/optimade/server/routers/files.py b/optimade/server/routers/files.py index 3a5846f3d..ef52cec77 100644 --- a/optimade/server/routers/files.py +++ b/optimade/server/routers/files.py @@ -1,10 +1,6 @@ from fastapi import APIRouter, Depends, Request -from optimade.models import ( - FileResource, - FileResponseMany, - FileResponseOne, -) +from optimade.models import FileResource, FileResponseMany, FileResponseOne from optimade.server.config import CONFIG from optimade.server.entry_collections import create_collection from optimade.server.mappers import FileMapper diff --git a/tests/server/entry_collections/test_entry_collections.py b/tests/server/entry_collections/test_entry_collections.py index de820429b..3e9093325 100644 --- a/tests/server/entry_collections/test_entry_collections.py +++ b/tests/server/entry_collections/test_entry_collections.py @@ -4,10 +4,10 @@ def test_get_attribute_fields(): """Test get_attribute_fields() method""" from optimade.models import ( + FileResourceAttributes, LinksResourceAttributes, ReferenceResourceAttributes, StructureResourceAttributes, - FileResourceAttributes, ) from optimade.server.routers import ENTRY_COLLECTIONS diff --git a/tests/server/routers/test_files.py b/tests/server/routers/test_files.py index 406a05446..b613e6976 100644 --- a/tests/server/routers/test_files.py +++ b/tests/server/routers/test_files.py @@ -1,8 +1,4 @@ -from optimade.models import ( - FileResponseMany, - # FileResponseOne, - # FileResource, -) +from optimade.models import FileResponseMany # FileResponseOne,; FileResource, from ..utils import RegularEndpointTests From 71cdd23f417ebbe39cb95f5b31aa5d370ed8e688 Mon Sep 17 00:00:00 2001 From: Matthew Evans Date: Tue, 6 Dec 2022 15:49:07 +0000 Subject: [PATCH 12/19] Add endpoint to main server --- openapi/openapi.json | 1010 ++++++++++++++++++++++++++++++++++----- optimade/server/main.py | 9 +- 2 files changed, 896 insertions(+), 123 deletions(-) diff --git a/openapi/openapi.json b/openapi/openapi.json index 6fac6c4fe..c4fe00d0f 100644 --- a/openapi/openapi.json +++ b/openapi/openapi.json @@ -1288,6 +1288,428 @@ } } }, + "/files": { + "get": { + "tags": [ + "Files" + ], + "summary": "Get Files", + "operationId": "get_files_files_get", + "parameters": [ + { + "description": "A filter string, in the format described in section API Filtering Format Specification of the specification.", + "required": false, + "schema": { + "title": "Filter", + "type": "string", + "description": "A filter string, in the format described in section API Filtering Format Specification of the specification.", + "default": "" + }, + "name": "filter", + "in": "query" + }, + { + "description": "The output format requested (see section Response Format).\nDefaults to the format string 'json', which specifies the standard output format described in this specification.\nExample: `http://example.com/v1/structures?response_format=xml`", + "required": false, + "schema": { + "title": "Response Format", + "type": "string", + "description": "The output format requested (see section Response Format).\nDefaults to the format string 'json', which specifies the standard output format described in this specification.\nExample: `http://example.com/v1/structures?response_format=xml`", + "default": "json" + }, + "name": "response_format", + "in": "query" + }, + { + "description": "An email address of the user making the request.\nThe email SHOULD be that of a person and not an automatic system.\nExample: `http://example.com/v1/structures?email_address=user@example.com`", + "required": false, + "schema": { + "title": "Email Address", + "type": "string", + "description": "An email address of the user making the request.\nThe email SHOULD be that of a person and not an automatic system.\nExample: `http://example.com/v1/structures?email_address=user@example.com`", + "format": "email", + "default": "" + }, + "name": "email_address", + "in": "query" + }, + { + "description": "A comma-delimited set of fields to be provided in the output.\nIf provided, these fields MUST be returned along with the REQUIRED fields.\nOther OPTIONAL fields MUST NOT be returned when this parameter is present.\nExample: `http://example.com/v1/structures?response_fields=last_modified,nsites`", + "required": false, + "schema": { + "title": "Response Fields", + "pattern": "([a-z_][a-z_0-9]*(,[a-z_][a-z_0-9]*)*)?", + "type": "string", + "description": "A comma-delimited set of fields to be provided in the output.\nIf provided, these fields MUST be returned along with the REQUIRED fields.\nOther OPTIONAL fields MUST NOT be returned when this parameter is present.\nExample: `http://example.com/v1/structures?response_fields=last_modified,nsites`", + "default": "" + }, + "name": "response_fields", + "in": "query" + }, + { + "description": "If supporting sortable queries, an implementation MUST use the `sort` query parameter with format as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-sorting).\n\nAn implementation MAY support multiple sort fields for a single query.\nIf it does, it again MUST conform to the JSON API 1.0 specification.\n\nIf an implementation supports sorting for an entry listing endpoint, then the `/info/` endpoint MUST include, for each field name `` in its `data.properties.` response value that can be used for sorting, the key `sortable` with value `true`.\nIf a field name under an entry listing endpoint supporting sorting cannot be used for sorting, the server MUST either leave out the `sortable` key or set it equal to `false` for the specific field name.\nThe set of field names, with `sortable` equal to `true` are allowed to be used in the \"sort fields\" list according to its definition in the JSON API 1.0 specification.\nThe field `sortable` is in addition to each property description and other OPTIONAL fields.\nAn example is shown in the section Entry Listing Info Endpoints.", + "required": false, + "schema": { + "title": "Sort", + "pattern": "([a-z_][a-z_0-9]*(,[a-z_][a-z_0-9]*)*)?", + "type": "string", + "description": "If supporting sortable queries, an implementation MUST use the `sort` query parameter with format as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-sorting).\n\nAn implementation MAY support multiple sort fields for a single query.\nIf it does, it again MUST conform to the JSON API 1.0 specification.\n\nIf an implementation supports sorting for an entry listing endpoint, then the `/info/` endpoint MUST include, for each field name `` in its `data.properties.` response value that can be used for sorting, the key `sortable` with value `true`.\nIf a field name under an entry listing endpoint supporting sorting cannot be used for sorting, the server MUST either leave out the `sortable` key or set it equal to `false` for the specific field name.\nThe set of field names, with `sortable` equal to `true` are allowed to be used in the \"sort fields\" list according to its definition in the JSON API 1.0 specification.\nThe field `sortable` is in addition to each property description and other OPTIONAL fields.\nAn example is shown in the section Entry Listing Info Endpoints.", + "default": "" + }, + "name": "sort", + "in": "query" + }, + { + "description": "Sets a numerical limit on the number of entries returned.\nSee [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-pagination).\nThe API implementation MUST return no more than the number specified.\nIt MAY return fewer.\nThe database MAY have a maximum limit and not accept larger numbers (in which case an error code -- 403 Forbidden -- MUST be returned).\nThe default limit value is up to the API implementation to decide.\nExample: `http://example.com/optimade/v1/structures?page_limit=100`", + "required": false, + "schema": { + "title": "Page Limit", + "minimum": 0.0, + "type": "integer", + "description": "Sets a numerical limit on the number of entries returned.\nSee [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-pagination).\nThe API implementation MUST return no more than the number specified.\nIt MAY return fewer.\nThe database MAY have a maximum limit and not accept larger numbers (in which case an error code -- 403 Forbidden -- MUST be returned).\nThe default limit value is up to the API implementation to decide.\nExample: `http://example.com/optimade/v1/structures?page_limit=100`", + "default": 20 + }, + "name": "page_limit", + "in": "query" + }, + { + "description": "RECOMMENDED for use with _offset-based_ pagination: using `page_offset` and `page_limit` is RECOMMENDED.\nExample: Skip 50 structures and fetch up to 100: `/structures?page_offset=50&page_limit=100`.", + "required": false, + "schema": { + "title": "Page Offset", + "minimum": 0.0, + "type": "integer", + "description": "RECOMMENDED for use with _offset-based_ pagination: using `page_offset` and `page_limit` is RECOMMENDED.\nExample: Skip 50 structures and fetch up to 100: `/structures?page_offset=50&page_limit=100`.", + "default": 0 + }, + "name": "page_offset", + "in": "query" + }, + { + "description": "RECOMMENDED for use with _page-based_ pagination: using `page_number` and `page_limit` is RECOMMENDED.\nIt is RECOMMENDED that the first page has number 1, i.e., that `page_number` is 1-based.\nExample: Fetch page 2 of up to 50 structures per page: `/structures?page_number=2&page_limit=50`.", + "required": false, + "schema": { + "title": "Page Number", + "type": "integer", + "description": "RECOMMENDED for use with _page-based_ pagination: using `page_number` and `page_limit` is RECOMMENDED.\nIt is RECOMMENDED that the first page has number 1, i.e., that `page_number` is 1-based.\nExample: Fetch page 2 of up to 50 structures per page: `/structures?page_number=2&page_limit=50`." + }, + "name": "page_number", + "in": "query" + }, + { + "description": "RECOMMENDED for use with _cursor-based_ pagination: using `page_cursor` and `page_limit` is RECOMMENDED.", + "required": false, + "schema": { + "title": "Page Cursor", + "minimum": 0.0, + "type": "integer", + "description": "RECOMMENDED for use with _cursor-based_ pagination: using `page_cursor` and `page_limit` is RECOMMENDED.", + "default": 0 + }, + "name": "page_cursor", + "in": "query" + }, + { + "description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.\nExample: Fetch up to 100 structures above sort-field value 4000 (in this example, server chooses to fetch results sorted by increasing `id`, so `page_above` value refers to an `id` value): `/structures?page_above=4000&page_limit=100`.", + "required": false, + "schema": { + "title": "Page Above", + "minimum": 0.0, + "type": "integer", + "description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.\nExample: Fetch up to 100 structures above sort-field value 4000 (in this example, server chooses to fetch results sorted by increasing `id`, so `page_above` value refers to an `id` value): `/structures?page_above=4000&page_limit=100`.", + "default": 0 + }, + "name": "page_above", + "in": "query" + }, + { + "description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.", + "required": false, + "schema": { + "title": "Page Below", + "minimum": 0.0, + "type": "integer", + "description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.", + "default": 0 + }, + "name": "page_below", + "in": "query" + }, + { + "description": "A server MAY implement the JSON API concept of returning [compound documents](https://jsonapi.org/format/1.0/#document-compound-documents) by utilizing the `include` query parameter as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-includes).\n\nAll related resource objects MUST be returned as part of an array value for the top-level `included` field, see the section JSON Response Schema: Common Fields.\n\nThe value of `include` MUST be a comma-separated list of \"relationship paths\", as defined in the [JSON API](https://jsonapi.org/format/1.0/#fetching-includes).\nIf relationship paths are not supported, or a server is unable to identify a relationship path a `400 Bad Request` response MUST be made.\n\nThe **default value** for `include` is `references`.\nThis means `references` entries MUST always be included under the top-level field `included` as default, since a server assumes if `include` is not specified by a client in the request, it is still specified as `include=references`.\nNote, if a client explicitly specifies `include` and leaves out `references`, `references` resource objects MUST NOT be included under the top-level field `included`, as per the definition of `included`, see section JSON Response Schema: Common Fields.\n\n> **Note**: A query with the parameter `include` set to the empty string means no related resource objects are to be returned under the top-level field `included`.", + "required": false, + "schema": { + "title": "Include", + "type": "string", + "description": "A server MAY implement the JSON API concept of returning [compound documents](https://jsonapi.org/format/1.0/#document-compound-documents) by utilizing the `include` query parameter as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-includes).\n\nAll related resource objects MUST be returned as part of an array value for the top-level `included` field, see the section JSON Response Schema: Common Fields.\n\nThe value of `include` MUST be a comma-separated list of \"relationship paths\", as defined in the [JSON API](https://jsonapi.org/format/1.0/#fetching-includes).\nIf relationship paths are not supported, or a server is unable to identify a relationship path a `400 Bad Request` response MUST be made.\n\nThe **default value** for `include` is `references`.\nThis means `references` entries MUST always be included under the top-level field `included` as default, since a server assumes if `include` is not specified by a client in the request, it is still specified as `include=references`.\nNote, if a client explicitly specifies `include` and leaves out `references`, `references` resource objects MUST NOT be included under the top-level field `included`, as per the definition of `included`, see section JSON Response Schema: Common Fields.\n\n> **Note**: A query with the parameter `include` set to the empty string means no related resource objects are to be returned under the top-level field `included`.", + "default": "references" + }, + "name": "include", + "in": "query" + }, + { + "description": "If the client provides the parameter, the value SHOULD have the format `vMAJOR` or `vMAJOR.MINOR`, where MAJOR is a major version and MINOR is a minor version of the API. For example, if a client appends `api_hint=v1.0` to the query string, the hint provided is for major version 1 and minor version 0.", + "required": false, + "schema": { + "title": "Api Hint", + "pattern": "(v[0-9]+(\\.[0-9]+)?)?", + "type": "string", + "description": "If the client provides the parameter, the value SHOULD have the format `vMAJOR` or `vMAJOR.MINOR`, where MAJOR is a major version and MINOR is a minor version of the API. For example, if a client appends `api_hint=v1.0` to the query string, the hint provided is for major version 1 and minor version 0.", + "default": "" + }, + "name": "api_hint", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/vnd.api+json": { + "schema": { + "$ref": "#/components/schemas/FileResponseMany" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "application/vnd.api+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "application/vnd.api+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "404": { + "description": "Not Found", + "content": { + "application/vnd.api+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "422": { + "description": "Unprocessable Entity", + "content": { + "application/vnd.api+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "application/vnd.api+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "501": { + "description": "Not Implemented", + "content": { + "application/vnd.api+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "553": { + "description": "Version Not Supported", + "content": { + "application/vnd.api+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/files/{entry_id}": { + "get": { + "tags": [ + "Files" + ], + "summary": "Get Single File", + "operationId": "get_single_file_files__entry_id__get", + "parameters": [ + { + "required": true, + "schema": { + "title": "Entry Id", + "type": "string" + }, + "name": "entry_id", + "in": "path" + }, + { + "description": "The output format requested (see section Response Format).\nDefaults to the format string 'json', which specifies the standard output format described in this specification.\nExample: `http://example.com/v1/structures?response_format=xml`", + "required": false, + "schema": { + "title": "Response Format", + "type": "string", + "description": "The output format requested (see section Response Format).\nDefaults to the format string 'json', which specifies the standard output format described in this specification.\nExample: `http://example.com/v1/structures?response_format=xml`", + "default": "json" + }, + "name": "response_format", + "in": "query" + }, + { + "description": "An email address of the user making the request.\nThe email SHOULD be that of a person and not an automatic system.\nExample: `http://example.com/v1/structures?email_address=user@example.com`", + "required": false, + "schema": { + "title": "Email Address", + "type": "string", + "description": "An email address of the user making the request.\nThe email SHOULD be that of a person and not an automatic system.\nExample: `http://example.com/v1/structures?email_address=user@example.com`", + "format": "email", + "default": "" + }, + "name": "email_address", + "in": "query" + }, + { + "description": "A comma-delimited set of fields to be provided in the output.\nIf provided, these fields MUST be returned along with the REQUIRED fields.\nOther OPTIONAL fields MUST NOT be returned when this parameter is present.\nExample: `http://example.com/v1/structures?response_fields=last_modified,nsites`", + "required": false, + "schema": { + "title": "Response Fields", + "pattern": "([a-z_][a-z_0-9]*(,[a-z_][a-z_0-9]*)*)?", + "type": "string", + "description": "A comma-delimited set of fields to be provided in the output.\nIf provided, these fields MUST be returned along with the REQUIRED fields.\nOther OPTIONAL fields MUST NOT be returned when this parameter is present.\nExample: `http://example.com/v1/structures?response_fields=last_modified,nsites`", + "default": "" + }, + "name": "response_fields", + "in": "query" + }, + { + "description": "A server MAY implement the JSON API concept of returning [compound documents](https://jsonapi.org/format/1.0/#document-compound-documents) by utilizing the `include` query parameter as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-includes).\n\nAll related resource objects MUST be returned as part of an array value for the top-level `included` field, see the section JSON Response Schema: Common Fields.\n\nThe value of `include` MUST be a comma-separated list of \"relationship paths\", as defined in the [JSON API](https://jsonapi.org/format/1.0/#fetching-includes).\nIf relationship paths are not supported, or a server is unable to identify a relationship path a `400 Bad Request` response MUST be made.\n\nThe **default value** for `include` is `references`.\nThis means `references` entries MUST always be included under the top-level field `included` as default, since a server assumes if `include` is not specified by a client in the request, it is still specified as `include=references`.\nNote, if a client explicitly specifies `include` and leaves out `references`, `references` resource objects MUST NOT be included under the top-level field `included`, as per the definition of `included`, see section JSON Response Schema: Common Fields.\n\n> **Note**: A query with the parameter `include` set to the empty string means no related resource objects are to be returned under the top-level field `included`.", + "required": false, + "schema": { + "title": "Include", + "type": "string", + "description": "A server MAY implement the JSON API concept of returning [compound documents](https://jsonapi.org/format/1.0/#document-compound-documents) by utilizing the `include` query parameter as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-includes).\n\nAll related resource objects MUST be returned as part of an array value for the top-level `included` field, see the section JSON Response Schema: Common Fields.\n\nThe value of `include` MUST be a comma-separated list of \"relationship paths\", as defined in the [JSON API](https://jsonapi.org/format/1.0/#fetching-includes).\nIf relationship paths are not supported, or a server is unable to identify a relationship path a `400 Bad Request` response MUST be made.\n\nThe **default value** for `include` is `references`.\nThis means `references` entries MUST always be included under the top-level field `included` as default, since a server assumes if `include` is not specified by a client in the request, it is still specified as `include=references`.\nNote, if a client explicitly specifies `include` and leaves out `references`, `references` resource objects MUST NOT be included under the top-level field `included`, as per the definition of `included`, see section JSON Response Schema: Common Fields.\n\n> **Note**: A query with the parameter `include` set to the empty string means no related resource objects are to be returned under the top-level field `included`.", + "default": "references" + }, + "name": "include", + "in": "query" + }, + { + "description": "If the client provides the parameter, the value SHOULD have the format `vMAJOR` or `vMAJOR.MINOR`, where MAJOR is a major version and MINOR is a minor version of the API. For example, if a client appends `api_hint=v1.0` to the query string, the hint provided is for major version 1 and minor version 0.", + "required": false, + "schema": { + "title": "Api Hint", + "pattern": "(v[0-9]+(\\.[0-9]+)?)?", + "type": "string", + "description": "If the client provides the parameter, the value SHOULD have the format `vMAJOR` or `vMAJOR.MINOR`, where MAJOR is a major version and MINOR is a minor version of the API. For example, if a client appends `api_hint=v1.0` to the query string, the hint provided is for major version 1 and minor version 0.", + "default": "" + }, + "name": "api_hint", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/vnd.api+json": { + "schema": { + "$ref": "#/components/schemas/FileResponseOne" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "application/vnd.api+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "application/vnd.api+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "404": { + "description": "Not Found", + "content": { + "application/vnd.api+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "422": { + "description": "Unprocessable Entity", + "content": { + "application/vnd.api+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "application/vnd.api+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "501": { + "description": "Not Implemented", + "content": { + "application/vnd.api+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "553": { + "description": "Version Not Supported", + "content": { + "application/vnd.api+json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, "/versions": { "get": { "tags": [ @@ -1856,203 +2278,551 @@ "type", "attributes" ], - "title": "EntryResource", - "description": "The base model for an entry resource." - }, - "EntryResourceAttributes": { + "title": "EntryResource", + "description": "The base model for an entry resource." + }, + "EntryResourceAttributes": { + "properties": { + "immutable_id": { + "type": "string", + "title": "Immutable Id", + "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", + "x-optimade-queryable": "must", + "x-optimade-support": "optional" + }, + "last_modified": { + "type": "string", + "format": "date-time", + "title": "Last Modified", + "description": "Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n - As part of JSON response format: `\"2007-04-05T14:30:20Z\"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)", + "x-optimade-queryable": "must", + "x-optimade-support": "should" + } + }, + "type": "object", + "required": [ + "last_modified" + ], + "title": "EntryResourceAttributes", + "description": "Contains key-value pairs representing the entry's properties." + }, + "Error": { + "properties": { + "id": { + "type": "string", + "title": "Id", + "description": "A unique identifier for this particular occurrence of the problem." + }, + "links": { + "allOf": [ + { + "$ref": "#/components/schemas/ErrorLinks" + } + ], + "title": "Links", + "description": "A links object storing about" + }, + "status": { + "type": "string", + "title": "Status", + "description": "the HTTP status code applicable to this problem, expressed as a string value." + }, + "code": { + "type": "string", + "title": "Code", + "description": "an application-specific error code, expressed as a string value." + }, + "title": { + "type": "string", + "title": "Title", + "description": "A short, human-readable summary of the problem. It **SHOULD NOT** change from occurrence to occurrence of the problem, except for purposes of localization." + }, + "detail": { + "type": "string", + "title": "Detail", + "description": "A human-readable explanation specific to this occurrence of the problem." + }, + "source": { + "allOf": [ + { + "$ref": "#/components/schemas/ErrorSource" + } + ], + "title": "Source", + "description": "An object containing references to the source of the error" + }, + "meta": { + "allOf": [ + { + "$ref": "#/components/schemas/Meta" + } + ], + "title": "Meta", + "description": "a meta object containing non-standard meta-information about the error." + } + }, + "type": "object", + "title": "Error", + "description": "An error response" + }, + "ErrorLinks": { + "properties": { + "about": { + "anyOf": [ + { + "type": "string", + "maxLength": 65536, + "minLength": 1, + "format": "uri" + }, + { + "$ref": "#/components/schemas/Link" + } + ], + "title": "About", + "description": "A link that leads to further details about this particular occurrence of the problem." + } + }, + "type": "object", + "title": "ErrorLinks", + "description": "A Links object specific to Error objects" + }, + "ErrorResponse": { + "properties": { + "data": { + "anyOf": [ + { + "$ref": "#/components/schemas/Resource" + }, + { + "items": { + "$ref": "#/components/schemas/Resource" + }, + "type": "array" + } + ], + "uniqueItems": true, + "title": "Data", + "description": "Outputted Data" + }, + "meta": { + "allOf": [ + { + "$ref": "#/components/schemas/ResponseMeta" + } + ], + "title": "Meta", + "description": "A meta object containing non-standard information." + }, + "errors": { + "items": { + "$ref": "#/components/schemas/OptimadeError" + }, + "type": "array", + "uniqueItems": true, + "title": "Errors", + "description": "A list of OPTIMADE-specific JSON API error objects, where the field detail MUST be present." + }, + "included": { + "items": { + "$ref": "#/components/schemas/Resource" + }, + "type": "array", + "uniqueItems": true, + "title": "Included", + "description": "A list of unique included resources" + }, + "links": { + "allOf": [ + { + "$ref": "#/components/schemas/ToplevelLinks" + } + ], + "title": "Links", + "description": "Links associated with the primary data or errors" + }, + "jsonapi": { + "allOf": [ + { + "$ref": "#/components/schemas/JsonApi" + } + ], + "title": "Jsonapi", + "description": "Information about the JSON API used" + } + }, + "type": "object", + "required": [ + "meta", + "errors" + ], + "title": "ErrorResponse", + "description": "errors MUST be present and data MUST be skipped" + }, + "ErrorSource": { + "properties": { + "pointer": { + "type": "string", + "title": "Pointer", + "description": "a JSON Pointer [RFC6901] to the associated entity in the request document [e.g. \"/data\" for a primary data object, or \"/data/attributes/title\" for a specific attribute]." + }, + "parameter": { + "type": "string", + "title": "Parameter", + "description": "a string indicating which URI query parameter caused the error." + } + }, + "type": "object", + "title": "ErrorSource", + "description": "an object containing references to the source of the error" + }, + "FileResource": { + "title": "FileResource", + "required": [ + "id", + "type", + "attributes" + ], + "type": "object", + "properties": { + "id": { + "title": "Id", + "type": "string", + "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", + "x-optimade-support": "must", + "x-optimade-queryable": "must" + }, + "type": { + "title": "Type", + "pattern": "^files$", + "type": "string", + "description": "The name of the type of an entry.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - MUST be an existing entry type.\n - The entry of type `` and ID `` MUST be returned in response to a request for `//` under the versioned base URL.\n\n- **Examples**:\n - `\"structures\"`", + "default": "files", + "x-optimade-support": "must", + "x-optimade-queryable": "must" + }, + "links": { + "title": "Links", + "allOf": [ + { + "$ref": "#/components/schemas/ResourceLinks" + } + ], + "description": "a links object containing links related to the resource." + }, + "meta": { + "title": "Meta", + "allOf": [ + { + "$ref": "#/components/schemas/Meta" + } + ], + "description": "a meta object containing non-standard meta-information about a resource that can not be represented as an attribute or relationship." + }, + "attributes": { + "$ref": "#/components/schemas/FileResourceAttributes" + }, + "relationships": { + "title": "Relationships", + "allOf": [ + { + "$ref": "#/components/schemas/EntryRelationships" + } + ], + "description": "A dictionary containing references to other entries according to the description in section Relationships encoded as [JSON API Relationships](https://jsonapi.org/format/1.0/#document-resource-object-relationships).\nThe OPTIONAL human-readable description of the relationship MAY be provided in the `description` field inside the `meta` dictionary of the JSON API resource identifier object." + } + }, + "description": "Representing a structure." + }, + "FileResourceAttributes": { + "title": "FileResourceAttributes", + "required": [ + "last_modified", + "url", + "url_stable_until", + "name", + "size", + "media_type", + "modification_timestamp", + "description", + "checksums", + "atime", + "ctime", + "mtime" + ], + "type": "object", "properties": { "immutable_id": { - "type": "string", "title": "Immutable Id", + "type": "string", "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", - "x-optimade-queryable": "must", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "must" }, "last_modified": { - "type": "string", - "format": "date-time", "title": "Last Modified", + "type": "string", "description": "Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n - As part of JSON response format: `\"2007-04-05T14:30:20Z\"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)", - "x-optimade-queryable": "must", - "x-optimade-support": "should" - } - }, - "type": "object", - "required": [ - "last_modified" - ], - "title": "EntryResourceAttributes", - "description": "Contains key-value pairs representing the entry's properties." - }, - "Error": { - "properties": { - "id": { + "format": "date-time", + "x-optimade-support": "should", + "x-optimade-queryable": "must" + }, + "url": { + "title": "Url", "type": "string", - "title": "Id", - "description": "A unique identifier for this particular occurrence of the problem." + "description": "The URL to get the contents of a file.\n- **Type**: string\n- **Requirements/Conventions**:\n\n - **Support**: MUST be supported by all implementations, MUST NOT be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - **Response**: REQUIRED in the response.\n - The URL MUST point to the actual contents of a file (i.e. byte stream), not an intermediate (preview) representation.\n For example, if referring to a file on GitHub, a link should point to raw contents.\n\n- **Examples**:\n\n - :val:`\"https://example.org/files/cifs/1000000.cif\"`\n", + "x-optimade-support": "must", + "x-optimade-queryable": "optional" }, - "links": { - "allOf": [ - { - "$ref": "#/components/schemas/ErrorLinks" - } - ], - "title": "Links", - "description": "A links object storing about" + "url_stable_until": { + "title": "Url Stable Until", + "type": "string", + "description": "Point in time until which the URL in `url` is guaranteed to stay stable.\n- **Type**: timestamp\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - :val:`null` means that there is no stability guarantee for the URL in `url`.\n Indefinite support could be communicated by providing a date sufficiently far in the future, for example, :val:`9999-12-31`.", + "format": "date-time", + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, - "status": { + "name": { + "title": "Name", "type": "string", - "title": "Status", - "description": "the HTTP status code applicable to this problem, expressed as a string value." + "description": "Base name of a file.\n- **Type**: string\n- **Requirements/Conventions**:\n\n - **Support**: MUST be supported by all implementations, MUST NOT be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - File name extension is an integral part of a file name and, if available, MUST be included.\n\n- **Examples**:\n\n - :val:`\"1000000.cif\"`", + "x-optimade-support": "must", + "x-optimade-queryable": "optional" }, - "code": { + "size": { + "title": "Size", + "type": "integer", + "description": "Size of a file in bytes.\n- **Type**: integer\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - If provided, it MUST be guaranteed that either exact size of a file is given or its upper bound.\n This way if a client reserves a static buffer or truncates the download stream after this many bytes the whole file would be received.\n Such provision is included to allow the providers to serve on-the-fly compressed files.", + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" + }, + "media_type": { + "title": "Media Type", "type": "string", - "title": "Code", - "description": "an application-specific error code, expressed as a string value." + "description": "Media type identifier (also known as MIME type), for a file as per `RFC 6838 Media Type Specifications and Registration Procedures `__.\n- **Type**: string\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n\n- **Examples**:\n\n - :val:`\"chemical/x-cif\"`", + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, - "title": { + "version": { + "title": "Version", "type": "string", - "title": "Title", - "description": "A short, human-readable summary of the problem. It **SHOULD NOT** change from occurrence to occurrence of the problem, except for purposes of localization." + "description": "Version information of a file (e.g. commit, revision, timestamp).\n- **Type**: string\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - If provided, it MUST be guaranteed that file contents pertaining to the same combination of :field:`id` and :field:`version` are the same", + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, - "detail": { + "modification_timestamp": { + "title": "Modification Timestamp", "type": "string", - "title": "Detail", - "description": "A human-readable explanation specific to this occurrence of the problem." + "description": "Timestamp of the last modification of file contents.\n A modification is understood as an addition, change or deletion of one or more bytes, resulting in file contents different from the previous.\n- **Type**: timestamp\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - Timestamps of subsequent file modifications SHOULD be increasing (not earlier than previous timestamps).", + "format": "date-time", + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, - "source": { - "allOf": [ + "description": { + "title": "Description", + "type": "string", + "description": "Free-form description of a file.\n- **Type**: string\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n\n- **Examples**:\n\n - :val:`\"POSCAR format file\"`", + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" + }, + "checksums": { + "title": "Checksums", + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Dictionary providing checksums of file contents.\n* **Type**: dictionary with keys identifying checksum functions and values (strings) giving the actual checksums\n* **Requirements/Conventions**:\n\n - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - Supported dictionary keys: :property:`md5`, :property:`sha1`, :property:`sha224`, :property:`sha256`, :property:`sha384`, :property:`sha512`.\n Checksums outside this list MAY be used, but their names MUST be prefixed by database-provider-specific namespace prefix (see appendix `Database-Provider-Specific Namespace Prefixes`_).\n", + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" + }, + "atime": { + "title": "Atime", + "type": "string", + "description": "Time of last access of a file as per POSIX standard.\n- **Type**: timestamp\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.", + "format": "date-time", + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" + }, + "ctime": { + "title": "Ctime", + "type": "string", + "description": "Time of last status change of a file as per POSIX standard.\n- **Type**: timestamp\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.", + "format": "date-time", + "x-optimade-unit": "\u00c5", + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" + }, + "mtime": { + "title": "Mtime", + "type": "string", + "description": " Time of last modification of a file as per POSIX standard.\n- **Type**: timestamp\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - It should be noted that the values of :field:`last_modified`, :field:`modification_timestamp` and :field:`mtime` do not necessary match.\n :field:`last_modified` pertains to the modification of the OPTIMADE metadata, :field:`modification_timestamp` pertains to file contents and :field:`mtime` pertains to the modification of the file (not necessary changing its contents).\n For example, appending an empty string to a file would result in the change of :field:`mtime` in some operating systems, but this would not be deemed as a modification of its contents.\n", + "format": "date-time", + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" + } + }, + "description": "This class contains the Field for the attributes used to represent a file, e.g. ." + }, + "FileResponseMany": { + "title": "FileResponseMany", + "required": [ + "data", + "meta" + ], + "type": "object", + "properties": { + "data": { + "title": "Data", + "uniqueItems": true, + "anyOf": [ { - "$ref": "#/components/schemas/ErrorSource" + "type": "array", + "items": { + "$ref": "#/components/schemas/FileResource" + } + }, + { + "type": "array", + "items": { + "type": "object" + } } ], - "title": "Source", - "description": "An object containing references to the source of the error" + "description": "List of unique OPTIMADE files entry resource objects." }, "meta": { + "title": "Meta", "allOf": [ { - "$ref": "#/components/schemas/Meta" + "$ref": "#/components/schemas/ResponseMeta" } ], - "title": "Meta", - "description": "a meta object containing non-standard meta-information about the error." - } - }, - "type": "object", - "title": "Error", - "description": "An error response" - }, - "ErrorLinks": { - "properties": { - "about": { + "description": "A meta object containing non-standard information" + }, + "errors": { + "title": "Errors", + "uniqueItems": true, + "type": "array", + "items": { + "$ref": "#/components/schemas/Error" + }, + "description": "A list of unique errors" + }, + "included": { + "title": "Included", + "uniqueItems": true, "anyOf": [ { - "type": "string", - "maxLength": 65536, - "minLength": 1, - "format": "uri" + "type": "array", + "items": { + "$ref": "#/components/schemas/EntryResource" + } }, { - "$ref": "#/components/schemas/Link" + "type": "array", + "items": { + "type": "object" + } + } + ] + }, + "links": { + "title": "Links", + "allOf": [ + { + "$ref": "#/components/schemas/ToplevelLinks" } ], - "title": "About", - "description": "A link that leads to further details about this particular occurrence of the problem." + "description": "Links associated with the primary data or errors" + }, + "jsonapi": { + "title": "Jsonapi", + "allOf": [ + { + "$ref": "#/components/schemas/JsonApi" + } + ], + "description": "Information about the JSON API used" } }, - "type": "object", - "title": "ErrorLinks", - "description": "A Links object specific to Error objects" + "description": "errors are not allowed" }, - "ErrorResponse": { + "FileResponseOne": { + "title": "FileResponseOne", + "required": [ + "data", + "meta" + ], + "type": "object", "properties": { "data": { + "title": "Data", "anyOf": [ { - "$ref": "#/components/schemas/Resource" + "$ref": "#/components/schemas/FileResource" }, { - "items": { - "$ref": "#/components/schemas/Resource" - }, - "type": "array" + "type": "object" } ], - "uniqueItems": true, - "title": "Data", - "description": "Outputted Data" + "description": "A single files entry resource." }, "meta": { + "title": "Meta", "allOf": [ { "$ref": "#/components/schemas/ResponseMeta" } ], - "title": "Meta", - "description": "A meta object containing non-standard information." + "description": "A meta object containing non-standard information" }, "errors": { + "title": "Errors", + "uniqueItems": true, + "type": "array", "items": { - "$ref": "#/components/schemas/OptimadeError" + "$ref": "#/components/schemas/Error" }, - "type": "array", - "uniqueItems": true, - "title": "Errors", - "description": "A list of OPTIMADE-specific JSON API error objects, where the field detail MUST be present." + "description": "A list of unique errors" }, "included": { - "items": { - "$ref": "#/components/schemas/Resource" - }, - "type": "array", - "uniqueItems": true, "title": "Included", - "description": "A list of unique included resources" + "uniqueItems": true, + "anyOf": [ + { + "type": "array", + "items": { + "$ref": "#/components/schemas/EntryResource" + } + }, + { + "type": "array", + "items": { + "type": "object" + } + } + ] }, "links": { + "title": "Links", "allOf": [ { "$ref": "#/components/schemas/ToplevelLinks" } ], - "title": "Links", "description": "Links associated with the primary data or errors" }, "jsonapi": { + "title": "Jsonapi", "allOf": [ { "$ref": "#/components/schemas/JsonApi" } ], - "title": "Jsonapi", "description": "Information about the JSON API used" } }, - "type": "object", - "required": [ - "meta", - "errors" - ], - "title": "ErrorResponse", - "description": "errors MUST be present and data MUST be skipped" - }, - "ErrorSource": { - "properties": { - "pointer": { - "type": "string", - "title": "Pointer", - "description": "a JSON Pointer [RFC6901] to the associated entity in the request document [e.g. \"/data\" for a primary data object, or \"/data/attributes/title\" for a specific attribute]." - }, - "parameter": { - "type": "string", - "title": "Parameter", - "description": "a string indicating which URI query parameter caused the error." - } - }, - "type": "object", - "title": "ErrorSource", - "description": "an object containing references to the source of the error" + "description": "errors are not allowed" }, "Implementation": { "properties": { diff --git a/optimade/server/main.py b/optimade/server/main.py index 4f95dcccb..8abd33e14 100644 --- a/optimade/server/main.py +++ b/optimade/server/main.py @@ -22,6 +22,7 @@ from optimade.server.logger import LOGGER from optimade.server.middleware import OPTIMADE_MIDDLEWARE from optimade.server.routers import ( + files, info, landing, links, @@ -31,6 +32,8 @@ ) from optimade.server.routers.utils import BASE_URL_PREFIXES, JSONAPIResponse +ENDPOINTS = (info, landing, links, references, structures, files) + if config_warnings: LOGGER.warn( f"Invalid config file or no config file provided, running server with default settings. Errors: " @@ -103,13 +106,13 @@ def load_entries(endpoint_name: str, endpoint_collection: EntryCollection): app.add_exception_handler(exception, handler) # Add various endpoints to unversioned URL -for endpoint in (info, links, references, structures, landing, versions): +for endpoint in ENDPOINTS + (versions,): app.include_router(endpoint.router) def add_major_version_base_url(app: FastAPI): """Add mandatory vMajor endpoints, i.e. all except versions.""" - for endpoint in (info, links, references, structures, landing): + for endpoint in ENDPOINTS: app.include_router(endpoint.router, prefix=BASE_URL_PREFIXES["major"]) @@ -121,7 +124,7 @@ def add_optional_versioned_base_urls(app: FastAPI): ``` """ for version in ("minor", "patch"): - for endpoint in (info, links, references, structures, landing): + for endpoint in ENDPOINTS: app.include_router(endpoint.router, prefix=BASE_URL_PREFIXES[version]) From 8cebb18eebdc671abc6918623a526f14b4c4c176 Mon Sep 17 00:00:00 2001 From: Matthew Evans Date: Tue, 6 Dec 2022 15:53:35 +0000 Subject: [PATCH 13/19] Format test file --- optimade/server/data/test_files.json | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/optimade/server/data/test_files.json b/optimade/server/data/test_files.json index f56b9db21..2ec844099 100644 --- a/optimade/server/data/test_files.json +++ b/optimade/server/data/test_files.json @@ -1,4 +1,11 @@ -[{"url": "www.example.com/file001.pdb", "name": "file001.pdb", "size": 12536, "media_type": "chemical/x-pdb","modification_timestamp": { - "$date": "2022-08-26T13:09:37.945Z" +[ + { + "url": "www.example.com/file001.pdb", + "name": "file001.pdb", + "size": 12536, + "media_type": "chemical/x-pdb", + "modification_timestamp": { + "$date": "2022-08-26T13:09:37.945Z" + } } -}] +] From 1b27478d801dcc571d3aee40c43bd55196eee3ee Mon Sep 17 00:00:00 2001 From: Matthew Evans Date: Tue, 6 Dec 2022 16:05:49 +0000 Subject: [PATCH 14/19] Update elastic_indexes.json with fields from `files` --- .../entry_collections/elastic_indexes.json | 54 +++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/optimade/server/entry_collections/elastic_indexes.json b/optimade/server/entry_collections/elastic_indexes.json index a6f954582..376657f62 100644 --- a/optimade/server/entry_collections/elastic_indexes.json +++ b/optimade/server/entry_collections/elastic_indexes.json @@ -152,6 +152,60 @@ }, "lattice_vectors": { "type": "float" + }, + "immutable_id": { + "type": "keyword" + }, + "last_modified": { + "type": "date" + }, + "species": { + "type": "object" + } + } + } + }, + "files": { + "mappings": { + "properties": { + "url": { + "type": "keyword" + }, + "url_stable_until": { + "type": "date" + }, + "name": { + "type": "keyword" + }, + "size": { + "type": "integer" + }, + "media_type": { + "type": "str" + }, + "version": { + "type": "keyword" + }, + "modification_timestamp": { + "type": "date" + }, + "checksums": { + "type": "object" + }, + "id": { + "type": "keyword" + }, + "description": { + "type": "integer" + }, + "atime": { + "type": "date" + }, + "ctime": { + "type": "date" + }, + "mtime": { + "type": "date" } } } From 82d49e4fc6cab6e22de9fb0e32d39978a8d09a9a Mon Sep 17 00:00:00 2001 From: Matthew Evans Date: Sat, 23 Dec 2023 13:24:27 +0000 Subject: [PATCH 15/19] Update OpenAPI JSON after merge --- openapi/index_openapi.json | 51 +++- openapi/openapi.json | 573 ++++++++++++++++++----------------- optimade/models/responses.py | 4 +- 3 files changed, 337 insertions(+), 291 deletions(-) diff --git a/openapi/index_openapi.json b/openapi/index_openapi.json index 95a0d8e37..90d093f46 100644 --- a/openapi/index_openapi.json +++ b/openapi/index_openapi.json @@ -498,15 +498,15 @@ "type": "string", "title": "Id", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "type": { "type": "string", "title": "Type", "description": "The name of the type of an entry.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - MUST be an existing entry type.\n - The entry of type `` and ID `` MUST be returned in response to a request for `//` under the versioned base URL.\n\n- **Example**: `\"structures\"`", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "links": { "allOf": [ @@ -560,16 +560,16 @@ "type": "string", "title": "Immutable Id", "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", - "x-optimade-queryable": "must", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "must" }, "last_modified": { "type": "string", "format": "date-time", "title": "Last Modified", "description": "Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n - As part of JSON response format: `\"2007-04-05T14:30:20Z\"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)", - "x-optimade-queryable": "must", - "x-optimade-support": "should" + "x-optimade-support": "should", + "x-optimade-queryable": "must" } }, "type": "object", @@ -887,6 +887,29 @@ "title": "Entry Types By Format", "description": "Available entry endpoints as a function of output formats." }, + "license": { + "anyOf": [ + { + "$ref": "#/components/schemas/Link" + }, + { + "type": "string", + "maxLength": 65536, + "minLength": 1, + "format": "uri" + } + ], + "title": "License", + "description": "A [JSON API links object](http://jsonapi.org/format/1.0/#document-links) giving a URL to a web page containing a human-readable text describing the license (or licensing options if there are multiple) covering all the data and metadata provided by this database.\nClients are advised not to try automated parsing of this link or its content, but rather rely on the field `available_licenses` instead." + }, + "available_licenses": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Available Licenses", + "description": "List of [SPDX license identifiers](https://spdx.org/licenses/) specifying a set of alternative licenses under which the client is granted access to all the data and metadata in this database.\n\nIf the data and metadata is available under multiple alternative licenses, identifiers of these multiple licenses SHOULD be provided to let clients know under which conditions the data and metadata can be used.\nInclusion of a license identifier in the list is a commitment of the database that the rights are in place to grant clients access to all the data and metadata according to the terms of either of these licenses (at the choice of the client).\nIf the licensing information provided via the field `license` omits licensing options specified in `available_licenses`, or if it otherwise contradicts them, a client MUST still be allowed to interpret the inclusion of a license in `available_licenses` as a full commitment from the database that the data and metadata is available, without exceptions, under the respective licenses.\nIf the database cannot make that commitment, e.g., if only part of the data is available under a license, the corresponding license identifier MUST NOT appear in `available_licenses` (but, rather, the field `license` is to be used to clarify the licensing situation.)\nAn empty list indicates that none of the SPDX licenses apply for the entirety of the database and that the licensing situation is clarified in human readable form in the field `license`." + }, "is_index": { "type": "boolean", "title": "Is Index", @@ -899,7 +922,9 @@ "api_version", "available_api_versions", "available_endpoints", - "entry_types_by_format" + "entry_types_by_format", + "license", + "available_licenses" ], "title": "IndexInfoAttributes", "description": "Attributes for Base URL Info endpoint for an Index Meta-Database" @@ -1107,8 +1132,8 @@ "type": "string", "title": "Id", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "type": { "type": "string", @@ -1700,9 +1725,9 @@ "description": "response string from the server" }, "request_delay": { - "title": "Request Delay", - "minimum": 0.0, "type": "number", + "minimum": 0.0, + "title": "Request Delay", "description": "A non-negative float giving time in seconds that the client is suggested to wait before issuing a subsequent request." }, "implementation": { diff --git a/openapi/openapi.json b/openapi/openapi.json index c4fe00d0f..98c6bb92e 100644 --- a/openapi/openapi.json +++ b/openapi/openapi.json @@ -1300,8 +1300,8 @@ "description": "A filter string, in the format described in section API Filtering Format Specification of the specification.", "required": false, "schema": { - "title": "Filter", "type": "string", + "title": "Filter", "description": "A filter string, in the format described in section API Filtering Format Specification of the specification.", "default": "" }, @@ -1312,8 +1312,8 @@ "description": "The output format requested (see section Response Format).\nDefaults to the format string 'json', which specifies the standard output format described in this specification.\nExample: `http://example.com/v1/structures?response_format=xml`", "required": false, "schema": { - "title": "Response Format", "type": "string", + "title": "Response Format", "description": "The output format requested (see section Response Format).\nDefaults to the format string 'json', which specifies the standard output format described in this specification.\nExample: `http://example.com/v1/structures?response_format=xml`", "default": "json" }, @@ -1324,10 +1324,10 @@ "description": "An email address of the user making the request.\nThe email SHOULD be that of a person and not an automatic system.\nExample: `http://example.com/v1/structures?email_address=user@example.com`", "required": false, "schema": { - "title": "Email Address", "type": "string", - "description": "An email address of the user making the request.\nThe email SHOULD be that of a person and not an automatic system.\nExample: `http://example.com/v1/structures?email_address=user@example.com`", "format": "email", + "title": "Email Address", + "description": "An email address of the user making the request.\nThe email SHOULD be that of a person and not an automatic system.\nExample: `http://example.com/v1/structures?email_address=user@example.com`", "default": "" }, "name": "email_address", @@ -1337,9 +1337,9 @@ "description": "A comma-delimited set of fields to be provided in the output.\nIf provided, these fields MUST be returned along with the REQUIRED fields.\nOther OPTIONAL fields MUST NOT be returned when this parameter is present.\nExample: `http://example.com/v1/structures?response_fields=last_modified,nsites`", "required": false, "schema": { - "title": "Response Fields", - "pattern": "([a-z_][a-z_0-9]*(,[a-z_][a-z_0-9]*)*)?", "type": "string", + "pattern": "([a-z_][a-z_0-9]*(,[a-z_][a-z_0-9]*)*)?", + "title": "Response Fields", "description": "A comma-delimited set of fields to be provided in the output.\nIf provided, these fields MUST be returned along with the REQUIRED fields.\nOther OPTIONAL fields MUST NOT be returned when this parameter is present.\nExample: `http://example.com/v1/structures?response_fields=last_modified,nsites`", "default": "" }, @@ -1350,9 +1350,9 @@ "description": "If supporting sortable queries, an implementation MUST use the `sort` query parameter with format as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-sorting).\n\nAn implementation MAY support multiple sort fields for a single query.\nIf it does, it again MUST conform to the JSON API 1.0 specification.\n\nIf an implementation supports sorting for an entry listing endpoint, then the `/info/` endpoint MUST include, for each field name `` in its `data.properties.` response value that can be used for sorting, the key `sortable` with value `true`.\nIf a field name under an entry listing endpoint supporting sorting cannot be used for sorting, the server MUST either leave out the `sortable` key or set it equal to `false` for the specific field name.\nThe set of field names, with `sortable` equal to `true` are allowed to be used in the \"sort fields\" list according to its definition in the JSON API 1.0 specification.\nThe field `sortable` is in addition to each property description and other OPTIONAL fields.\nAn example is shown in the section Entry Listing Info Endpoints.", "required": false, "schema": { - "title": "Sort", - "pattern": "([a-z_][a-z_0-9]*(,[a-z_][a-z_0-9]*)*)?", "type": "string", + "pattern": "([a-z_][a-z_0-9]*(,[a-z_][a-z_0-9]*)*)?", + "title": "Sort", "description": "If supporting sortable queries, an implementation MUST use the `sort` query parameter with format as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-sorting).\n\nAn implementation MAY support multiple sort fields for a single query.\nIf it does, it again MUST conform to the JSON API 1.0 specification.\n\nIf an implementation supports sorting for an entry listing endpoint, then the `/info/` endpoint MUST include, for each field name `` in its `data.properties.` response value that can be used for sorting, the key `sortable` with value `true`.\nIf a field name under an entry listing endpoint supporting sorting cannot be used for sorting, the server MUST either leave out the `sortable` key or set it equal to `false` for the specific field name.\nThe set of field names, with `sortable` equal to `true` are allowed to be used in the \"sort fields\" list according to its definition in the JSON API 1.0 specification.\nThe field `sortable` is in addition to each property description and other OPTIONAL fields.\nAn example is shown in the section Entry Listing Info Endpoints.", "default": "" }, @@ -1363,9 +1363,9 @@ "description": "Sets a numerical limit on the number of entries returned.\nSee [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-pagination).\nThe API implementation MUST return no more than the number specified.\nIt MAY return fewer.\nThe database MAY have a maximum limit and not accept larger numbers (in which case an error code -- 403 Forbidden -- MUST be returned).\nThe default limit value is up to the API implementation to decide.\nExample: `http://example.com/optimade/v1/structures?page_limit=100`", "required": false, "schema": { - "title": "Page Limit", - "minimum": 0.0, "type": "integer", + "minimum": 0.0, + "title": "Page Limit", "description": "Sets a numerical limit on the number of entries returned.\nSee [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-pagination).\nThe API implementation MUST return no more than the number specified.\nIt MAY return fewer.\nThe database MAY have a maximum limit and not accept larger numbers (in which case an error code -- 403 Forbidden -- MUST be returned).\nThe default limit value is up to the API implementation to decide.\nExample: `http://example.com/optimade/v1/structures?page_limit=100`", "default": 20 }, @@ -1376,9 +1376,9 @@ "description": "RECOMMENDED for use with _offset-based_ pagination: using `page_offset` and `page_limit` is RECOMMENDED.\nExample: Skip 50 structures and fetch up to 100: `/structures?page_offset=50&page_limit=100`.", "required": false, "schema": { - "title": "Page Offset", - "minimum": 0.0, "type": "integer", + "minimum": 0.0, + "title": "Page Offset", "description": "RECOMMENDED for use with _offset-based_ pagination: using `page_offset` and `page_limit` is RECOMMENDED.\nExample: Skip 50 structures and fetch up to 100: `/structures?page_offset=50&page_limit=100`.", "default": 0 }, @@ -1389,8 +1389,8 @@ "description": "RECOMMENDED for use with _page-based_ pagination: using `page_number` and `page_limit` is RECOMMENDED.\nIt is RECOMMENDED that the first page has number 1, i.e., that `page_number` is 1-based.\nExample: Fetch page 2 of up to 50 structures per page: `/structures?page_number=2&page_limit=50`.", "required": false, "schema": { - "title": "Page Number", "type": "integer", + "title": "Page Number", "description": "RECOMMENDED for use with _page-based_ pagination: using `page_number` and `page_limit` is RECOMMENDED.\nIt is RECOMMENDED that the first page has number 1, i.e., that `page_number` is 1-based.\nExample: Fetch page 2 of up to 50 structures per page: `/structures?page_number=2&page_limit=50`." }, "name": "page_number", @@ -1400,9 +1400,9 @@ "description": "RECOMMENDED for use with _cursor-based_ pagination: using `page_cursor` and `page_limit` is RECOMMENDED.", "required": false, "schema": { - "title": "Page Cursor", - "minimum": 0.0, "type": "integer", + "minimum": 0.0, + "title": "Page Cursor", "description": "RECOMMENDED for use with _cursor-based_ pagination: using `page_cursor` and `page_limit` is RECOMMENDED.", "default": 0 }, @@ -1413,11 +1413,9 @@ "description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.\nExample: Fetch up to 100 structures above sort-field value 4000 (in this example, server chooses to fetch results sorted by increasing `id`, so `page_above` value refers to an `id` value): `/structures?page_above=4000&page_limit=100`.", "required": false, "schema": { + "type": "string", "title": "Page Above", - "minimum": 0.0, - "type": "integer", - "description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.\nExample: Fetch up to 100 structures above sort-field value 4000 (in this example, server chooses to fetch results sorted by increasing `id`, so `page_above` value refers to an `id` value): `/structures?page_above=4000&page_limit=100`.", - "default": 0 + "description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.\nExample: Fetch up to 100 structures above sort-field value 4000 (in this example, server chooses to fetch results sorted by increasing `id`, so `page_above` value refers to an `id` value): `/structures?page_above=4000&page_limit=100`." }, "name": "page_above", "in": "query" @@ -1426,11 +1424,9 @@ "description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.", "required": false, "schema": { + "type": "string", "title": "Page Below", - "minimum": 0.0, - "type": "integer", - "description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.", - "default": 0 + "description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED." }, "name": "page_below", "in": "query" @@ -1439,8 +1435,8 @@ "description": "A server MAY implement the JSON API concept of returning [compound documents](https://jsonapi.org/format/1.0/#document-compound-documents) by utilizing the `include` query parameter as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-includes).\n\nAll related resource objects MUST be returned as part of an array value for the top-level `included` field, see the section JSON Response Schema: Common Fields.\n\nThe value of `include` MUST be a comma-separated list of \"relationship paths\", as defined in the [JSON API](https://jsonapi.org/format/1.0/#fetching-includes).\nIf relationship paths are not supported, or a server is unable to identify a relationship path a `400 Bad Request` response MUST be made.\n\nThe **default value** for `include` is `references`.\nThis means `references` entries MUST always be included under the top-level field `included` as default, since a server assumes if `include` is not specified by a client in the request, it is still specified as `include=references`.\nNote, if a client explicitly specifies `include` and leaves out `references`, `references` resource objects MUST NOT be included under the top-level field `included`, as per the definition of `included`, see section JSON Response Schema: Common Fields.\n\n> **Note**: A query with the parameter `include` set to the empty string means no related resource objects are to be returned under the top-level field `included`.", "required": false, "schema": { - "title": "Include", "type": "string", + "title": "Include", "description": "A server MAY implement the JSON API concept of returning [compound documents](https://jsonapi.org/format/1.0/#document-compound-documents) by utilizing the `include` query parameter as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-includes).\n\nAll related resource objects MUST be returned as part of an array value for the top-level `included` field, see the section JSON Response Schema: Common Fields.\n\nThe value of `include` MUST be a comma-separated list of \"relationship paths\", as defined in the [JSON API](https://jsonapi.org/format/1.0/#fetching-includes).\nIf relationship paths are not supported, or a server is unable to identify a relationship path a `400 Bad Request` response MUST be made.\n\nThe **default value** for `include` is `references`.\nThis means `references` entries MUST always be included under the top-level field `included` as default, since a server assumes if `include` is not specified by a client in the request, it is still specified as `include=references`.\nNote, if a client explicitly specifies `include` and leaves out `references`, `references` resource objects MUST NOT be included under the top-level field `included`, as per the definition of `included`, see section JSON Response Schema: Common Fields.\n\n> **Note**: A query with the parameter `include` set to the empty string means no related resource objects are to be returned under the top-level field `included`.", "default": "references" }, @@ -1451,9 +1447,9 @@ "description": "If the client provides the parameter, the value SHOULD have the format `vMAJOR` or `vMAJOR.MINOR`, where MAJOR is a major version and MINOR is a minor version of the API. For example, if a client appends `api_hint=v1.0` to the query string, the hint provided is for major version 1 and minor version 0.", "required": false, "schema": { - "title": "Api Hint", - "pattern": "(v[0-9]+(\\.[0-9]+)?)?", "type": "string", + "pattern": "(v[0-9]+(\\.[0-9]+)?)?", + "title": "Api Hint", "description": "If the client provides the parameter, the value SHOULD have the format `vMAJOR` or `vMAJOR.MINOR`, where MAJOR is a major version and MINOR is a minor version of the API. For example, if a client appends `api_hint=v1.0` to the query string, the hint provided is for major version 1 and minor version 0.", "default": "" }, @@ -1556,8 +1552,8 @@ { "required": true, "schema": { - "title": "Entry Id", - "type": "string" + "type": "string", + "title": "Entry Id" }, "name": "entry_id", "in": "path" @@ -1566,8 +1562,8 @@ "description": "The output format requested (see section Response Format).\nDefaults to the format string 'json', which specifies the standard output format described in this specification.\nExample: `http://example.com/v1/structures?response_format=xml`", "required": false, "schema": { - "title": "Response Format", "type": "string", + "title": "Response Format", "description": "The output format requested (see section Response Format).\nDefaults to the format string 'json', which specifies the standard output format described in this specification.\nExample: `http://example.com/v1/structures?response_format=xml`", "default": "json" }, @@ -1578,10 +1574,10 @@ "description": "An email address of the user making the request.\nThe email SHOULD be that of a person and not an automatic system.\nExample: `http://example.com/v1/structures?email_address=user@example.com`", "required": false, "schema": { - "title": "Email Address", "type": "string", - "description": "An email address of the user making the request.\nThe email SHOULD be that of a person and not an automatic system.\nExample: `http://example.com/v1/structures?email_address=user@example.com`", "format": "email", + "title": "Email Address", + "description": "An email address of the user making the request.\nThe email SHOULD be that of a person and not an automatic system.\nExample: `http://example.com/v1/structures?email_address=user@example.com`", "default": "" }, "name": "email_address", @@ -1591,9 +1587,9 @@ "description": "A comma-delimited set of fields to be provided in the output.\nIf provided, these fields MUST be returned along with the REQUIRED fields.\nOther OPTIONAL fields MUST NOT be returned when this parameter is present.\nExample: `http://example.com/v1/structures?response_fields=last_modified,nsites`", "required": false, "schema": { - "title": "Response Fields", - "pattern": "([a-z_][a-z_0-9]*(,[a-z_][a-z_0-9]*)*)?", "type": "string", + "pattern": "([a-z_][a-z_0-9]*(,[a-z_][a-z_0-9]*)*)?", + "title": "Response Fields", "description": "A comma-delimited set of fields to be provided in the output.\nIf provided, these fields MUST be returned along with the REQUIRED fields.\nOther OPTIONAL fields MUST NOT be returned when this parameter is present.\nExample: `http://example.com/v1/structures?response_fields=last_modified,nsites`", "default": "" }, @@ -1604,8 +1600,8 @@ "description": "A server MAY implement the JSON API concept of returning [compound documents](https://jsonapi.org/format/1.0/#document-compound-documents) by utilizing the `include` query parameter as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-includes).\n\nAll related resource objects MUST be returned as part of an array value for the top-level `included` field, see the section JSON Response Schema: Common Fields.\n\nThe value of `include` MUST be a comma-separated list of \"relationship paths\", as defined in the [JSON API](https://jsonapi.org/format/1.0/#fetching-includes).\nIf relationship paths are not supported, or a server is unable to identify a relationship path a `400 Bad Request` response MUST be made.\n\nThe **default value** for `include` is `references`.\nThis means `references` entries MUST always be included under the top-level field `included` as default, since a server assumes if `include` is not specified by a client in the request, it is still specified as `include=references`.\nNote, if a client explicitly specifies `include` and leaves out `references`, `references` resource objects MUST NOT be included under the top-level field `included`, as per the definition of `included`, see section JSON Response Schema: Common Fields.\n\n> **Note**: A query with the parameter `include` set to the empty string means no related resource objects are to be returned under the top-level field `included`.", "required": false, "schema": { - "title": "Include", "type": "string", + "title": "Include", "description": "A server MAY implement the JSON API concept of returning [compound documents](https://jsonapi.org/format/1.0/#document-compound-documents) by utilizing the `include` query parameter as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-includes).\n\nAll related resource objects MUST be returned as part of an array value for the top-level `included` field, see the section JSON Response Schema: Common Fields.\n\nThe value of `include` MUST be a comma-separated list of \"relationship paths\", as defined in the [JSON API](https://jsonapi.org/format/1.0/#fetching-includes).\nIf relationship paths are not supported, or a server is unable to identify a relationship path a `400 Bad Request` response MUST be made.\n\nThe **default value** for `include` is `references`.\nThis means `references` entries MUST always be included under the top-level field `included` as default, since a server assumes if `include` is not specified by a client in the request, it is still specified as `include=references`.\nNote, if a client explicitly specifies `include` and leaves out `references`, `references` resource objects MUST NOT be included under the top-level field `included`, as per the definition of `included`, see section JSON Response Schema: Common Fields.\n\n> **Note**: A query with the parameter `include` set to the empty string means no related resource objects are to be returned under the top-level field `included`.", "default": "references" }, @@ -1616,9 +1612,9 @@ "description": "If the client provides the parameter, the value SHOULD have the format `vMAJOR` or `vMAJOR.MINOR`, where MAJOR is a major version and MINOR is a minor version of the API. For example, if a client appends `api_hint=v1.0` to the query string, the hint provided is for major version 1 and minor version 0.", "required": false, "schema": { - "title": "Api Hint", - "pattern": "(v[0-9]+(\\.[0-9]+)?)?", "type": "string", + "pattern": "(v[0-9]+(\\.[0-9]+)?)?", + "title": "Api Hint", "description": "If the client provides the parameter, the value SHOULD have the format `vMAJOR` or `vMAJOR.MINOR`, where MAJOR is a major version and MINOR is a minor version of the API. For example, if a client appends `api_hint=v1.0` to the query string, the hint provided is for major version 1 and minor version 0.", "default": "" }, @@ -1769,8 +1765,8 @@ "type": "array", "title": "Sites In Groups", "description": "Index of the sites (0-based) that belong to each group for each assembly.\n\n- **Examples**:\n - `[[1], [2]]`: two groups, one with the second site, one with the third.\n - `[[1,2], [3]]`: one group with the second and third site, one with the fourth.", - "x-optimade-queryable": "optional", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "optional" }, "group_probabilities": { "items": { @@ -1779,8 +1775,8 @@ "type": "array", "title": "Group Probabilities", "description": "Statistical probability of each group. It MUST have the same length as `sites_in_groups`.\nIt SHOULD sum to one.\nSee below for examples of how to specify the probability of the occurrence of a vacancy.\nThe possible reasons for the values not to sum to one are the same as already specified above for the `concentration` of each `species`.", - "x-optimade-queryable": "optional", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "optional" } }, "type": "object", @@ -1879,6 +1875,29 @@ "title": "Entry Types By Format", "description": "Available entry endpoints as a function of output formats." }, + "license": { + "anyOf": [ + { + "$ref": "#/components/schemas/Link" + }, + { + "type": "string", + "maxLength": 65536, + "minLength": 1, + "format": "uri" + } + ], + "title": "License", + "description": "A [JSON API links object](http://jsonapi.org/format/1.0/#document-links) giving a URL to a web page containing a human-readable text describing the license (or licensing options if there are multiple) covering all the data and metadata provided by this database.\nClients are advised not to try automated parsing of this link or its content, but rather rely on the field `available_licenses` instead." + }, + "available_licenses": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Available Licenses", + "description": "List of [SPDX license identifiers](https://spdx.org/licenses/) specifying a set of alternative licenses under which the client is granted access to all the data and metadata in this database.\n\nIf the data and metadata is available under multiple alternative licenses, identifiers of these multiple licenses SHOULD be provided to let clients know under which conditions the data and metadata can be used.\nInclusion of a license identifier in the list is a commitment of the database that the rights are in place to grant clients access to all the data and metadata according to the terms of either of these licenses (at the choice of the client).\nIf the licensing information provided via the field `license` omits licensing options specified in `available_licenses`, or if it otherwise contradicts them, a client MUST still be allowed to interpret the inclusion of a license in `available_licenses` as a full commitment from the database that the data and metadata is available, without exceptions, under the respective licenses.\nIf the database cannot make that commitment, e.g., if only part of the data is available under a license, the corresponding license identifier MUST NOT appear in `available_licenses` (but, rather, the field `license` is to be used to clarify the licensing situation.)\nAn empty list indicates that none of the SPDX licenses apply for the entirety of the database and that the licensing situation is clarified in human readable form in the field `license`." + }, "is_index": { "type": "boolean", "title": "Is Index", @@ -1891,7 +1910,9 @@ "api_version", "available_api_versions", "available_endpoints", - "entry_types_by_format" + "entry_types_by_format", + "license", + "available_licenses" ], "title": "BaseInfoAttributes", "description": "Attributes for Base URL Info endpoint" @@ -2225,15 +2246,15 @@ "type": "string", "title": "Id", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "type": { "type": "string", "title": "Type", "description": "The name of the type of an entry.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - MUST be an existing entry type.\n - The entry of type `` and ID `` MUST be returned in response to a request for `//` under the versioned base URL.\n\n- **Example**: `\"structures\"`", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "links": { "allOf": [ @@ -2287,16 +2308,16 @@ "type": "string", "title": "Immutable Id", "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", - "x-optimade-queryable": "must", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "must" }, "last_modified": { "type": "string", "format": "date-time", "title": "Last Modified", "description": "Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n - As part of JSON response format: `\"2007-04-05T14:30:20Z\"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)", - "x-optimade-queryable": "must", - "x-optimade-support": "should" + "x-optimade-support": "should", + "x-optimade-queryable": "must" } }, "type": "object", @@ -2477,286 +2498,279 @@ "description": "an object containing references to the source of the error" }, "FileResource": { - "title": "FileResource", - "required": [ - "id", - "type", - "attributes" - ], - "type": "object", "properties": { "id": { - "title": "Id", "type": "string", + "title": "Id", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", "x-optimade-support": "must", "x-optimade-queryable": "must" }, "type": { - "title": "Type", - "pattern": "^files$", "type": "string", + "pattern": "^files$", + "title": "Type", "description": "The name of the type of an entry.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - MUST be an existing entry type.\n - The entry of type `` and ID `` MUST be returned in response to a request for `//` under the versioned base URL.\n\n- **Examples**:\n - `\"structures\"`", "default": "files", "x-optimade-support": "must", "x-optimade-queryable": "must" }, "links": { - "title": "Links", "allOf": [ { "$ref": "#/components/schemas/ResourceLinks" } ], + "title": "Links", "description": "a links object containing links related to the resource." }, "meta": { - "title": "Meta", "allOf": [ { "$ref": "#/components/schemas/Meta" } ], + "title": "Meta", "description": "a meta object containing non-standard meta-information about a resource that can not be represented as an attribute or relationship." }, "attributes": { "$ref": "#/components/schemas/FileResourceAttributes" }, "relationships": { - "title": "Relationships", "allOf": [ { "$ref": "#/components/schemas/EntryRelationships" } ], + "title": "Relationships", "description": "A dictionary containing references to other entries according to the description in section Relationships encoded as [JSON API Relationships](https://jsonapi.org/format/1.0/#document-resource-object-relationships).\nThe OPTIONAL human-readable description of the relationship MAY be provided in the `description` field inside the `meta` dictionary of the JSON API resource identifier object." } }, + "type": "object", + "required": [ + "id", + "type", + "attributes" + ], + "title": "FileResource", "description": "Representing a structure." }, "FileResourceAttributes": { - "title": "FileResourceAttributes", - "required": [ - "last_modified", - "url", - "url_stable_until", - "name", - "size", - "media_type", - "modification_timestamp", - "description", - "checksums", - "atime", - "ctime", - "mtime" - ], - "type": "object", "properties": { "immutable_id": { - "title": "Immutable Id", "type": "string", + "title": "Immutable Id", "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", "x-optimade-support": "optional", "x-optimade-queryable": "must" }, "last_modified": { - "title": "Last Modified", "type": "string", - "description": "Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n - As part of JSON response format: `\"2007-04-05T14:30:20Z\"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)", "format": "date-time", + "title": "Last Modified", + "description": "Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n - As part of JSON response format: `\"2007-04-05T14:30:20Z\"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)", "x-optimade-support": "should", "x-optimade-queryable": "must" }, "url": { - "title": "Url", "type": "string", + "title": "Url", "description": "The URL to get the contents of a file.\n- **Type**: string\n- **Requirements/Conventions**:\n\n - **Support**: MUST be supported by all implementations, MUST NOT be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - **Response**: REQUIRED in the response.\n - The URL MUST point to the actual contents of a file (i.e. byte stream), not an intermediate (preview) representation.\n For example, if referring to a file on GitHub, a link should point to raw contents.\n\n- **Examples**:\n\n - :val:`\"https://example.org/files/cifs/1000000.cif\"`\n", "x-optimade-support": "must", "x-optimade-queryable": "optional" }, "url_stable_until": { - "title": "Url Stable Until", "type": "string", - "description": "Point in time until which the URL in `url` is guaranteed to stay stable.\n- **Type**: timestamp\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - :val:`null` means that there is no stability guarantee for the URL in `url`.\n Indefinite support could be communicated by providing a date sufficiently far in the future, for example, :val:`9999-12-31`.", "format": "date-time", + "title": "Url Stable Until", + "description": "Point in time until which the URL in `url` is guaranteed to stay stable.\n- **Type**: timestamp\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - :val:`null` means that there is no stability guarantee for the URL in `url`.\n Indefinite support could be communicated by providing a date sufficiently far in the future, for example, :val:`9999-12-31`.", "x-optimade-support": "optional", "x-optimade-queryable": "optional" }, "name": { - "title": "Name", "type": "string", + "title": "Name", "description": "Base name of a file.\n- **Type**: string\n- **Requirements/Conventions**:\n\n - **Support**: MUST be supported by all implementations, MUST NOT be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - File name extension is an integral part of a file name and, if available, MUST be included.\n\n- **Examples**:\n\n - :val:`\"1000000.cif\"`", "x-optimade-support": "must", "x-optimade-queryable": "optional" }, "size": { - "title": "Size", "type": "integer", + "title": "Size", "description": "Size of a file in bytes.\n- **Type**: integer\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - If provided, it MUST be guaranteed that either exact size of a file is given or its upper bound.\n This way if a client reserves a static buffer or truncates the download stream after this many bytes the whole file would be received.\n Such provision is included to allow the providers to serve on-the-fly compressed files.", "x-optimade-support": "optional", "x-optimade-queryable": "optional" }, "media_type": { - "title": "Media Type", "type": "string", + "title": "Media Type", "description": "Media type identifier (also known as MIME type), for a file as per `RFC 6838 Media Type Specifications and Registration Procedures `__.\n- **Type**: string\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n\n- **Examples**:\n\n - :val:`\"chemical/x-cif\"`", "x-optimade-support": "optional", "x-optimade-queryable": "optional" }, "version": { - "title": "Version", "type": "string", + "title": "Version", "description": "Version information of a file (e.g. commit, revision, timestamp).\n- **Type**: string\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - If provided, it MUST be guaranteed that file contents pertaining to the same combination of :field:`id` and :field:`version` are the same", "x-optimade-support": "optional", "x-optimade-queryable": "optional" }, "modification_timestamp": { - "title": "Modification Timestamp", "type": "string", - "description": "Timestamp of the last modification of file contents.\n A modification is understood as an addition, change or deletion of one or more bytes, resulting in file contents different from the previous.\n- **Type**: timestamp\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - Timestamps of subsequent file modifications SHOULD be increasing (not earlier than previous timestamps).", "format": "date-time", + "title": "Modification Timestamp", + "description": "Timestamp of the last modification of file contents.\n A modification is understood as an addition, change or deletion of one or more bytes, resulting in file contents different from the previous.\n- **Type**: timestamp\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - Timestamps of subsequent file modifications SHOULD be increasing (not earlier than previous timestamps).", "x-optimade-support": "optional", "x-optimade-queryable": "optional" }, "description": { - "title": "Description", "type": "string", + "title": "Description", "description": "Free-form description of a file.\n- **Type**: string\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n\n- **Examples**:\n\n - :val:`\"POSCAR format file\"`", "x-optimade-support": "optional", "x-optimade-queryable": "optional" }, "checksums": { - "title": "Checksums", - "type": "object", "additionalProperties": { "type": "string" }, + "type": "object", + "title": "Checksums", "description": "Dictionary providing checksums of file contents.\n* **Type**: dictionary with keys identifying checksum functions and values (strings) giving the actual checksums\n* **Requirements/Conventions**:\n\n - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - Supported dictionary keys: :property:`md5`, :property:`sha1`, :property:`sha224`, :property:`sha256`, :property:`sha384`, :property:`sha512`.\n Checksums outside this list MAY be used, but their names MUST be prefixed by database-provider-specific namespace prefix (see appendix `Database-Provider-Specific Namespace Prefixes`_).\n", "x-optimade-support": "optional", "x-optimade-queryable": "optional" }, "atime": { - "title": "Atime", "type": "string", - "description": "Time of last access of a file as per POSIX standard.\n- **Type**: timestamp\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.", "format": "date-time", + "title": "Atime", + "description": "Time of last access of a file as per POSIX standard.\n- **Type**: timestamp\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.", "x-optimade-support": "optional", "x-optimade-queryable": "optional" }, "ctime": { - "title": "Ctime", "type": "string", - "description": "Time of last status change of a file as per POSIX standard.\n- **Type**: timestamp\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.", "format": "date-time", - "x-optimade-unit": "\u00c5", + "title": "Ctime", + "description": "Time of last status change of a file as per POSIX standard.\n- **Type**: timestamp\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.", "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-unit": "\u00c5" }, "mtime": { - "title": "Mtime", "type": "string", - "description": " Time of last modification of a file as per POSIX standard.\n- **Type**: timestamp\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - It should be noted that the values of :field:`last_modified`, :field:`modification_timestamp` and :field:`mtime` do not necessary match.\n :field:`last_modified` pertains to the modification of the OPTIMADE metadata, :field:`modification_timestamp` pertains to file contents and :field:`mtime` pertains to the modification of the file (not necessary changing its contents).\n For example, appending an empty string to a file would result in the change of :field:`mtime` in some operating systems, but this would not be deemed as a modification of its contents.\n", "format": "date-time", + "title": "Mtime", + "description": " Time of last modification of a file as per POSIX standard.\n- **Type**: timestamp\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - It should be noted that the values of :field:`last_modified`, :field:`modification_timestamp` and :field:`mtime` do not necessary match.\n :field:`last_modified` pertains to the modification of the OPTIMADE metadata, :field:`modification_timestamp` pertains to file contents and :field:`mtime` pertains to the modification of the file (not necessary changing its contents).\n For example, appending an empty string to a file would result in the change of :field:`mtime` in some operating systems, but this would not be deemed as a modification of its contents.\n", "x-optimade-support": "optional", "x-optimade-queryable": "optional" } }, + "type": "object", + "required": [ + "last_modified", + "url", + "url_stable_until", + "name", + "size", + "media_type", + "modification_timestamp", + "description", + "checksums", + "atime", + "ctime", + "mtime" + ], + "title": "FileResourceAttributes", "description": "This class contains the Field for the attributes used to represent a file, e.g. ." }, "FileResponseMany": { - "title": "FileResponseMany", - "required": [ - "data", - "meta" - ], - "type": "object", "properties": { "data": { - "title": "Data", - "uniqueItems": true, "anyOf": [ { - "type": "array", "items": { "$ref": "#/components/schemas/FileResource" - } + }, + "type": "array" }, { - "type": "array", "items": { "type": "object" - } + }, + "type": "array" } ], + "uniqueItems": true, + "title": "Data", "description": "List of unique OPTIMADE files entry resource objects." }, "meta": { - "title": "Meta", "allOf": [ { "$ref": "#/components/schemas/ResponseMeta" } ], + "title": "Meta", "description": "A meta object containing non-standard information" }, "errors": { - "title": "Errors", - "uniqueItems": true, - "type": "array", "items": { "$ref": "#/components/schemas/Error" }, + "type": "array", + "uniqueItems": true, + "title": "Errors", "description": "A list of unique errors" }, "included": { - "title": "Included", - "uniqueItems": true, "anyOf": [ { - "type": "array", "items": { "$ref": "#/components/schemas/EntryResource" - } + }, + "type": "array" }, { - "type": "array", "items": { "type": "object" - } + }, + "type": "array" } - ] + ], + "uniqueItems": true, + "title": "Included" }, "links": { - "title": "Links", "allOf": [ { "$ref": "#/components/schemas/ToplevelLinks" } ], + "title": "Links", "description": "Links associated with the primary data or errors" }, "jsonapi": { - "title": "Jsonapi", "allOf": [ { "$ref": "#/components/schemas/JsonApi" } ], + "title": "Jsonapi", "description": "Information about the JSON API used" } }, - "description": "errors are not allowed" - }, - "FileResponseOne": { - "title": "FileResponseOne", + "type": "object", "required": [ "data", "meta" ], - "type": "object", + "title": "FileResponseMany", + "description": "errors are not allowed" + }, + "FileResponseOne": { "properties": { "data": { - "title": "Data", "anyOf": [ { "$ref": "#/components/schemas/FileResource" @@ -2765,63 +2779,70 @@ "type": "object" } ], + "title": "Data", "description": "A single files entry resource." }, "meta": { - "title": "Meta", "allOf": [ { "$ref": "#/components/schemas/ResponseMeta" } ], + "title": "Meta", "description": "A meta object containing non-standard information" }, "errors": { - "title": "Errors", - "uniqueItems": true, - "type": "array", "items": { "$ref": "#/components/schemas/Error" }, + "type": "array", + "uniqueItems": true, + "title": "Errors", "description": "A list of unique errors" }, "included": { - "title": "Included", - "uniqueItems": true, "anyOf": [ { - "type": "array", "items": { "$ref": "#/components/schemas/EntryResource" - } + }, + "type": "array" }, { - "type": "array", "items": { "type": "object" - } + }, + "type": "array" } - ] + ], + "uniqueItems": true, + "title": "Included" }, "links": { - "title": "Links", "allOf": [ { "$ref": "#/components/schemas/ToplevelLinks" } ], + "title": "Links", "description": "Links associated with the primary data or errors" }, "jsonapi": { - "title": "Jsonapi", "allOf": [ { "$ref": "#/components/schemas/JsonApi" } ], + "title": "Jsonapi", "description": "Information about the JSON API used" } }, + "type": "object", + "required": [ + "data", + "meta" + ], + "title": "FileResponseOne", "description": "errors are not allowed" }, "Implementation": { @@ -3041,8 +3062,8 @@ "type": "string", "title": "Id", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "type": { "type": "string", @@ -3446,22 +3467,22 @@ "type": "string", "title": "Name", "description": "Full name of the person, REQUIRED.", - "x-optimade-queryable": "optional", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "optional" }, "firstname": { "type": "string", "title": "Firstname", "description": "First name of the person.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "lastname": { "type": "string", "title": "Lastname", "description": "Last name of the person.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" } }, "type": "object", @@ -3664,8 +3685,8 @@ "type": "string", "title": "Id", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "type": { "type": "string", @@ -3673,8 +3694,8 @@ "title": "Type", "description": "The name of the type of an entry.\n- **Type**: string.\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - MUST be an existing entry type.\n - The entry of type and ID MUST be returned in response to a request for `//` under the versioned base URL.\n- **Example**: `\"structures\"`", "default": "references", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "links": { "allOf": [ @@ -3722,16 +3743,16 @@ "type": "string", "title": "Immutable Id", "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", - "x-optimade-queryable": "must", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "must" }, "last_modified": { "type": "string", "format": "date-time", "title": "Last Modified", "description": "Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n - As part of JSON response format: `\"2007-04-05T14:30:20Z\"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)", - "x-optimade-queryable": "must", - "x-optimade-support": "should" + "x-optimade-support": "should", + "x-optimade-queryable": "must" }, "authors": { "items": { @@ -3740,8 +3761,8 @@ "type": "array", "title": "Authors", "description": "List of person objects containing the authors of the reference.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "editors": { "items": { @@ -3750,15 +3771,15 @@ "type": "array", "title": "Editors", "description": "List of person objects containing the editors of the reference.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "doi": { "type": "string", "title": "Doi", "description": "The digital object identifier of the reference.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "url": { "type": "string", @@ -3767,162 +3788,162 @@ "format": "uri", "title": "Url", "description": "The URL of the reference.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "address": { "type": "string", "title": "Address", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "annote": { "type": "string", "title": "Annote", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "booktitle": { "type": "string", "title": "Booktitle", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "chapter": { "type": "string", "title": "Chapter", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "crossref": { "type": "string", "title": "Crossref", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "edition": { "type": "string", "title": "Edition", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "howpublished": { "type": "string", "title": "Howpublished", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "institution": { "type": "string", "title": "Institution", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "journal": { "type": "string", "title": "Journal", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "key": { "type": "string", "title": "Key", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "month": { "type": "string", "title": "Month", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "note": { "type": "string", "title": "Note", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "number": { "type": "string", "title": "Number", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "organization": { "type": "string", "title": "Organization", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "pages": { "type": "string", "title": "Pages", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "publisher": { "type": "string", "title": "Publisher", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "school": { "type": "string", "title": "School", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "series": { "type": "string", "title": "Series", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "title": { "type": "string", "title": "Title", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "bib_type": { "type": "string", "title": "Bib Type", "description": "Type of the reference, corresponding to the **type** property in the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "volume": { "type": "string", "title": "Volume", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "year": { "type": "string", "title": "Year", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" } }, "type": "object", @@ -4294,9 +4315,9 @@ "description": "response string from the server" }, "request_delay": { - "title": "Request Delay", - "minimum": 0.0, "type": "number", + "minimum": 0.0, + "title": "Request Delay", "description": "A non-negative float giving time in seconds that the client is suggested to wait before issuing a subsequent request." }, "implementation": { @@ -4348,8 +4369,8 @@ "type": "string", "title": "Name", "description": "Gives the name of the species; the **name** value MUST be unique in the `species` list.", - "x-optimade-queryable": "optional", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "optional" }, "chemical_symbols": { "items": { @@ -4358,8 +4379,8 @@ "type": "array", "title": "Chemical Symbols", "description": "MUST be a list of strings of all chemical elements composing this species. Each item of the list MUST be one of the following:\n\n- a valid chemical-element symbol, or\n- the special value `\"X\"` to represent a non-chemical element, or\n- the special value `\"vacancy\"` to represent that this site has a non-zero probability of having a vacancy (the respective probability is indicated in the `concentration` list, see below).\n\nIf any one entry in the `species` list has a `chemical_symbols` list that is longer than 1 element, the correct flag MUST be set in the list `structure_features`.", - "x-optimade-queryable": "optional", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "optional" }, "concentration": { "items": { @@ -4368,8 +4389,8 @@ "type": "array", "title": "Concentration", "description": "MUST be a list of floats, with same length as `chemical_symbols`. The numbers represent the relative concentration of the corresponding chemical symbol in this species. The numbers SHOULD sum to one. Cases in which the numbers do not sum to one typically fall only in the following two categories:\n\n- Numerical errors when representing float numbers in fixed precision, e.g. for two chemical symbols with concentrations `1/3` and `2/3`, the concentration might look something like `[0.33333333333, 0.66666666666]`. If the client is aware that the sum is not one because of numerical precision, it can renormalize the values so that the sum is exactly one.\n- Experimental errors in the data present in the database. In this case, it is the responsibility of the client to decide how to process the data.\n\nNote that concentrations are uncorrelated between different site (even of the same species).", - "x-optimade-queryable": "optional", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "optional" }, "mass": { "items": { @@ -4378,16 +4399,16 @@ "type": "array", "title": "Mass", "description": "If present MUST be a list of floats expressed in a.m.u.\nElements denoting vacancies MUST have masses equal to 0.", - "x-optimade-queryable": "optional", "x-optimade-support": "optional", + "x-optimade-queryable": "optional", "x-optimade-unit": "a.m.u." }, "original_name": { "type": "string", "title": "Original Name", "description": "Can be any valid Unicode string, and SHOULD contain (if specified) the name of the species that is used internally in the source database.\n\nNote: With regards to \"source database\", we refer to the immediate source being queried via the OPTIMADE API implementation.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "attached": { "items": { @@ -4396,8 +4417,8 @@ "type": "array", "title": "Attached", "description": "If provided MUST be a list of length 1 or more of strings of chemical symbols for the elements attached to this site, or \"X\" for a non-chemical element.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "nattached": { "items": { @@ -4406,8 +4427,8 @@ "type": "array", "title": "Nattached", "description": "If provided MUST be a list of length 1 or more of integers indicating the number of attached atoms of the kind specified in the value of the :field:`attached` key.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" } }, "type": "object", @@ -4476,8 +4497,8 @@ "type": "string", "title": "Id", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "type": { "type": "string", @@ -4485,8 +4506,8 @@ "title": "Type", "description": "The name of the type of an entry.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - MUST be an existing entry type.\n - The entry of type `` and ID `` MUST be returned in response to a request for `//` under the versioned base URL.\n\n- **Examples**:\n - `\"structures\"`", "default": "structures", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "links": { "allOf": [ @@ -4534,17 +4555,17 @@ "type": "string", "title": "Immutable Id", "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", - "x-optimade-queryable": "must", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "must" }, "last_modified": { "type": "string", "format": "date-time", "title": "Last Modified", "description": "Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n - As part of JSON response format: `\"2007-04-05T14:30:20Z\"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)", + "x-optimade-support": "should", "x-optimade-queryable": "must", - "nullable": true, - "x-optimade-support": "should" + "nullable": true }, "elements": { "items": { @@ -4553,17 +4574,17 @@ "type": "array", "title": "Elements", "description": "The chemical symbols of the different elements present in the structure.\n\n- **Type**: list of strings.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - The strings are the chemical symbols, i.e., either a single uppercase letter or an uppercase letter followed by a number of lowercase letters.\n - The order MUST be alphabetical.\n - MUST refer to the same elements in the same order, and therefore be of the same length, as `elements_ratios`, if the latter is provided.\n - Note: This property SHOULD NOT contain the string \"X\" to indicate non-chemical elements or \"vacancy\" to indicate vacancies (in contrast to the field `chemical_symbols` for the `species` property).\n\n- **Examples**:\n - `[\"Si\"]`\n - `[\"Al\",\"O\",\"Si\"]`\n\n- **Query examples**:\n - A filter that matches all records of structures that contain Si, Al **and** O, and possibly other elements: `elements HAS ALL \"Si\", \"Al\", \"O\"`.\n - To match structures with exactly these three elements, use `elements HAS ALL \"Si\", \"Al\", \"O\" AND elements LENGTH 3`.\n - Note: length queries on this property can be equivalently formulated by filtering on the `nelements`_ property directly.", + "x-optimade-support": "should", "x-optimade-queryable": "must", - "nullable": true, - "x-optimade-support": "should" + "nullable": true }, "nelements": { "type": "integer", "title": "Nelements", "description": "Number of different elements in the structure as an integer.\n\n- **Type**: integer\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - MUST be equal to the lengths of the list properties `elements` and `elements_ratios`, if they are provided.\n\n- **Examples**:\n - `3`\n\n- **Querying**:\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`.", + "x-optimade-support": "should", "x-optimade-queryable": "must", - "nullable": true, - "x-optimade-support": "should" + "nullable": true }, "elements_ratios": { "items": { @@ -4572,43 +4593,43 @@ "type": "array", "title": "Elements Ratios", "description": "Relative proportions of different elements in the structure.\n\n- **Type**: list of floats\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - Composed by the proportions of elements in the structure as a list of floating point numbers.\n - The sum of the numbers MUST be 1.0 (within floating point accuracy)\n - MUST refer to the same elements in the same order, and therefore be of the same length, as `elements`, if the latter is provided.\n\n- **Examples**:\n - `[1.0]`\n - `[0.3333333333333333, 0.2222222222222222, 0.4444444444444444]`\n\n- **Query examples**:\n - Note: Useful filters can be formulated using the set operator syntax for correlated values.\n However, since the values are floating point values, the use of equality comparisons is generally inadvisable.\n - OPTIONAL: a filter that matches structures where approximately 1/3 of the atoms in the structure are the element Al is: `elements:elements_ratios HAS ALL \"Al\":>0.3333, \"Al\":<0.3334`.", + "x-optimade-support": "should", "x-optimade-queryable": "must", - "nullable": true, - "x-optimade-support": "should" + "nullable": true }, "chemical_formula_descriptive": { "type": "string", "title": "Chemical Formula Descriptive", "description": "The chemical formula for a structure as a string in a form chosen by the API implementation.\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - The chemical formula is given as a string consisting of properly capitalized element symbols followed by integers or decimal numbers, balanced parentheses, square, and curly brackets `(`,`)`, `[`,`]`, `{`, `}`, commas, the `+`, `-`, `:` and `=` symbols. The parentheses are allowed to be followed by a number. Spaces are allowed anywhere except within chemical symbols. The order of elements and any groupings indicated by parentheses or brackets are chosen freely by the API implementation.\n - The string SHOULD be arithmetically consistent with the element ratios in the `chemical_formula_reduced` property.\n - It is RECOMMENDED, but not mandatory, that symbols, parentheses and brackets, if used, are used with the meanings prescribed by [IUPAC's Nomenclature of Organic Chemistry](https://www.qmul.ac.uk/sbcs/iupac/bibliog/blue.html).\n\n- **Examples**:\n - `\"(H2O)2 Na\"`\n - `\"NaCl\"`\n - `\"CaCO3\"`\n - `\"CCaO3\"`\n - `\"(CH3)3N+ - [CH2]2-OH = Me3N+ - CH2 - CH2OH\"`\n\n- **Query examples**:\n - Note: the free-form nature of this property is likely to make queries on it across different databases inconsistent.\n - A filter that matches an exactly given formula: `chemical_formula_descriptive=\"(H2O)2 Na\"`.\n - A filter that does a partial match: `chemical_formula_descriptive CONTAINS \"H2O\"`.", + "x-optimade-support": "should", "x-optimade-queryable": "must", - "nullable": true, - "x-optimade-support": "should" + "nullable": true }, "chemical_formula_reduced": { "type": "string", "pattern": "(^$)|^([A-Z][a-z]?([2-9]|[1-9]\\d+)?)+$", "title": "Chemical Formula Reduced", "description": "The reduced chemical formula for a structure as a string with element symbols and integer chemical proportion numbers.\nThe proportion number MUST be omitted if it is 1.\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property.\n However, support for filters using partial string matching with this property is OPTIONAL (i.e., BEGINS WITH, ENDS WITH, and CONTAINS).\n Intricate queries on formula components are instead suggested to be formulated using set-type filter operators on the multi valued `elements` and `elements_ratios` properties.\n - Element symbols MUST have proper capitalization (e.g., `\"Si\"`, not `\"SI\"` for \"silicon\").\n - Elements MUST be placed in alphabetical order, followed by their integer chemical proportion number.\n - For structures with no partial occupation, the chemical proportion numbers are the smallest integers for which the chemical proportion is exactly correct.\n - For structures with partial occupation, the chemical proportion numbers are integers that within reasonable approximation indicate the correct chemical proportions. The precise details of how to perform the rounding is chosen by the API implementation.\n - No spaces or separators are allowed.\n\n- **Examples**:\n - `\"H2NaO\"`\n - `\"ClNa\"`\n - `\"CCaO3\"`\n\n- **Query examples**:\n - A filter that matches an exactly given formula is `chemical_formula_reduced=\"H2NaO\"`.", + "x-optimade-support": "should", "x-optimade-queryable": "must", - "nullable": true, - "x-optimade-support": "should" + "nullable": true }, "chemical_formula_hill": { "type": "string", "pattern": "(^$)|^([A-Z][a-z]?([2-9]|[1-9]\\d+)?)+$", "title": "Chemical Formula Hill", "description": "The chemical formula for a structure in [Hill form](https://dx.doi.org/10.1021/ja02046a005) with element symbols followed by integer chemical proportion numbers. The proportion number MUST be omitted if it is 1.\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, only a subset of the filter features MAY be supported.\n - The overall scale factor of the chemical proportions is chosen such that the resulting values are integers that indicate the most chemically relevant unit of which the system is composed.\n For example, if the structure is a repeating unit cell with four hydrogens and four oxygens that represents two hydroperoxide molecules, `chemical_formula_hill` is `\"H2O2\"` (i.e., not `\"HO\"`, nor `\"H4O4\"`).\n - If the chemical insight needed to ascribe a Hill formula to the system is not present, the property MUST be handled as unset.\n - Element symbols MUST have proper capitalization (e.g., `\"Si\"`, not `\"SI\"` for \"silicon\").\n - Elements MUST be placed in [Hill order](https://dx.doi.org/10.1021/ja02046a005), followed by their integer chemical proportion number.\n Hill order means: if carbon is present, it is placed first, and if also present, hydrogen is placed second.\n After that, all other elements are ordered alphabetically.\n If carbon is not present, all elements are ordered alphabetically.\n - If the system has sites with partial occupation and the total occupations of each element do not all sum up to integers, then the Hill formula SHOULD be handled as unset.\n - No spaces or separators are allowed.\n\n- **Examples**:\n - `\"H2O2\"`\n\n- **Query examples**:\n - A filter that matches an exactly given formula is `chemical_formula_hill=\"H2O2\"`.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "chemical_formula_anonymous": { "type": "string", "pattern": "(^$)|^([A-Z][a-z]?([2-9]|[1-9]\\d+)?)+$", "title": "Chemical Formula Anonymous", "description": "The anonymous formula is the `chemical_formula_reduced`, but where the elements are instead first ordered by their chemical proportion number, and then, in order left to right, replaced by anonymous symbols A, B, C, ..., Z, Aa, Ba, ..., Za, Ab, Bb, ... and so on.\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property.\n However, support for filters using partial string matching with this property is OPTIONAL (i.e., BEGINS WITH, ENDS WITH, and CONTAINS).\n\n- **Examples**:\n - `\"A2B\"`\n - `\"A42B42C16D12E10F9G5\"`\n\n- **Querying**:\n - A filter that matches an exactly given formula is `chemical_formula_anonymous=\"A2B\"`.", + "x-optimade-support": "should", "x-optimade-queryable": "must", - "nullable": true, - "x-optimade-support": "should" + "nullable": true }, "dimension_types": { "items": { @@ -4619,17 +4640,17 @@ "minItems": 3, "title": "Dimension Types", "description": "List of three integers.\nFor each of the three directions indicated by the three lattice vectors (see property `lattice_vectors`), this list indicates if the direction is periodic (value `1`) or non-periodic (value `0`).\nNote: the elements in this list each refer to the direction of the corresponding entry in `lattice_vectors` and *not* the Cartesian x, y, z directions.\n\n- **Type**: list of integers.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - MUST be a list of length 3.\n - Each integer element MUST assume only the value 0 or 1.\n\n- **Examples**:\n - For a molecule: `[0, 0, 0]`\n - For a wire along the direction specified by the third lattice vector: `[0, 0, 1]`\n - For a 2D surface/slab, periodic on the plane defined by the first and third lattice vectors: `[1, 0, 1]`\n - For a bulk 3D system: `[1, 1, 1]`", + "x-optimade-support": "should", "x-optimade-queryable": "optional", - "nullable": true, - "x-optimade-support": "should" + "nullable": true }, "nperiodic_dimensions": { "type": "integer", "title": "Nperiodic Dimensions", "description": "An integer specifying the number of periodic dimensions in the structure, equivalent to the number of non-zero entries in `dimension_types`.\n\n- **Type**: integer\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - The integer value MUST be between 0 and 3 inclusive and MUST be equal to the sum of the items in the `dimension_types` property.\n - This property only reflects the treatment of the lattice vectors provided for the structure, and not any physical interpretation of the dimensionality of its contents.\n\n- **Examples**:\n - `2` should be indicated in cases where `dimension_types` is any of `[1, 1, 0]`, `[1, 0, 1]`, `[0, 1, 1]`.\n\n- **Query examples**:\n - Match only structures with exactly 3 periodic dimensions: `nperiodic_dimensions=3`\n - Match all structures with 2 or fewer periodic dimensions: `nperiodic_dimensions<=2`", + "x-optimade-support": "should", "x-optimade-queryable": "must", - "nullable": true, - "x-optimade-support": "should" + "nullable": true }, "lattice_vectors": { "items": { @@ -4645,10 +4666,10 @@ "minItems": 3, "title": "Lattice Vectors", "description": "The three lattice vectors in Cartesian coordinates, in \u00e5ngstr\u00f6m (\u00c5).\n\n- **Type**: list of list of floats or unknown values.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - MUST be a list of three vectors *a*, *b*, and *c*, where each of the vectors MUST BE a list of the vector's coordinates along the x, y, and z Cartesian coordinates.\n (Therefore, the first index runs over the three lattice vectors and the second index runs over the x, y, z Cartesian coordinates).\n - For databases that do not define an absolute Cartesian system (e.g., only defining the length and angles between vectors), the first lattice vector SHOULD be set along *x* and the second on the *xy*-plane.\n - MUST always contain three vectors of three coordinates each, independently of the elements of property `dimension_types`.\n The vectors SHOULD by convention be chosen so the determinant of the `lattice_vectors` matrix is different from zero.\n The vectors in the non-periodic directions have no significance beyond fulfilling these requirements.\n - The coordinates of the lattice vectors of non-periodic dimensions (i.e., those dimensions for which `dimension_types` is `0`) MAY be given as a list of all `null` values.\n If a lattice vector contains the value `null`, all coordinates of that lattice vector MUST be `null`.\n\n- **Examples**:\n - `[[4.0,0.0,0.0],[0.0,4.0,0.0],[0.0,1.0,4.0]]` represents a cell, where the first vector is `(4, 0, 0)`, i.e., a vector aligned along the `x` axis of length 4 \u00c5; the second vector is `(0, 4, 0)`; and the third vector is `(0, 1, 4)`.", + "x-optimade-support": "should", "x-optimade-queryable": "optional", "x-optimade-unit": "\u00c5", - "nullable": true, - "x-optimade-support": "should" + "nullable": true }, "space_group_symmetry_operations_xyz": { "items": { @@ -4658,22 +4679,22 @@ "type": "array", "title": "Space Group Symmetry Operations Xyz", "description": "A list of symmetry operations given as general position x, y and z coordinates in algebraic form.\n\nEach symmetry operation is described by a string that gives that symmetry operation in Jones' faithful representation (Bradley & Cracknell, 1972: pp. 35-37), adapted for computer string notation.\nThe letters x, y and z that are typesetted with overbars in printed text represent coordinate values multiplied by -1 and are encoded as -x, -y and -z, respectively.\nThe syntax of the strings representing symmetry operations MUST conform to regular expressions given in appendix The Symmetry Operation String Regular Expressions.\nThe interpretation of the strings MUST follow the conventions of the IUCr CIF core dictionary (IUCr, 2023).\nIn particular, this property MUST explicitly provide all symmetry operations needed to generate all the atoms in the unit cell from the atoms in the asymmetric unit, for the setting used.\nThis symmetry operation set MUST always include the `\"x,y,z\"` identity operation.\nThe symmetry operations are to be applied to fractional atom coordinates.\nIn case only Cartesian coordinates are available, these Cartesian coordinates must be converted to fractional coordinates before the application of the provided symmetry operations.\nIf the symmetry operation list is present, it MUST be compatible with other space group specifications (e.g. the ITC space group number, the Hall symbol, the Hermann-Mauguin symbol) if these are present.\n\n- **Type**: list of strings\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n However, the property is RECOMMENDED if coordinates are returned in a form to which these operations can or must be applied (e.g. fractional atom coordinates of an asymmetric unit).\n Moreover, the property is REQUIRED if symmetry operations are necessary to reconstruct the full model of the material and no other symmetry information (e.g., the Hall symbol) is provided that would allow the user to derive symmetry operations unambiguously.\n - MUST be null if `nperiodic_dimensions` is equal to 0.\n\n- **Examples**:\n - Space group operations for the space group with ITC number 3 (H-M symbol: P 2, extended H-M symbol: P 1 2 1, Hall symbol P 2y):\n ```\n [\"x,y,z\", \"-x,y,-z\"]\n ```\n - Space group operations for the space group with ITC number 5 (H-M symbol C 2, extended H-M symbol: C 1 2 1, Hall symbol C 2y):\n ```\n [\"x,y,z\", \"-x,y,-z\", \"x+1/2,y+1/2,z\", \"-x+1/2,y+1/2,-z\"]\n ```\n\n- **Notes**:\n The list of space group symmetry operations applies to the whole periodic array of atoms and together with the lattice translations given in the `lattice_vectors` property provides the necessary information to reconstruct all atom site positions of the periodic material.\n Thus, the symmetry operations described in this property are only applicable to material models with at least one periodic dimension.\n This property is not meant to represent arbitrary symmetries of molecules, non-periodic (finite) collections of atoms or non-crystallographic symmetry.\n\n- **Bibliographic References**:\n\n Bradley, C. J. and Cracknell, A. P. (1972) The Mathematical Theory of Symmetry in Solids. Oxford, Clarendon Press (paperback edition 2010) 745 p. ISBN 978-0-19-958258-7.\n\n IUCr (2023) Core dictionary (coreCIF) version 2.4.5; data name _space_group_symop_operation_xyz. Available from: https://www.iucr.org/__data/iucr/cifdic_html/1/cif_core.dic/Ispace_group_symop_operation_xyz.html [Accessed 2023-06-18T16:46+03:00].", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "space_group_hall": { "type": "string", "title": "Space Group Hall", "description": "A Hall space group symbol representing the symmetry of the structure as defined in (Hall, 1981, 1981a).\nThe change-of-basis operations are used as defined in the International Tables of Crystallography (ITC) Vol. B, Sect. 1.4, Appendix A1.4.2 (IUCr, 2001).\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - Each component of the Hall symbol MUST be separated by a single space symbol.\n - If there exists a standard Hall symbol which represents the symmetry it SHOULD be used.\n - MUST be null if `nperiodic_dimensions` is not equal to 3.\n\n- **Bibliographic References**:\n\n Hall, S. R. (1981) Space-group notation with an explicit origin. Acta Crystallographica Section A, 37, 517-525, International Union of Crystallography (IUCr), DOI: https://doi.org/10.1107/s0567739481001228\n\n Hall, S. R. (1981a) Space-group notation with an explicit origin; erratum. Acta Crystallographica Section A, 37, 921-921, International Union of Crystallography (IUCr), DOI: https://doi.org/10.1107/s0567739481001976\n\n IUCr (2001). International Tables for Crystallography vol. B. Reciprocal Space. Ed. U. Shmueli. 2-nd edition. Dordrecht/Boston/London, Kluwer Academic Publishers.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "space_group_symbol_hermann_mauguin": { "type": "string", "title": "Space Group Symbol Hermann Mauguin", "description": "A human- and machine-readable string containing the short Hermann-Mauguin (H-M) symbol which specifies the space group of the structure in the response.\nThe H-M symbol SHOULD aim to convey the closest representation of the symmetry information that can be specified using the short format used in the International Tables for Crystallography vol. A (IUCr, 2005), Table 4.3.2.1 as described in the accompanying text.\nThe symbol MAY be a non-standard short H-M symbol.\nThe H-M symbol does not unambiguously communicate the axis, cell, and origin choice, and the given symbol SHOULD NOT be amended to convey this information.\n\nTo encode as character strings, the following adaptations MUST be made when representing H-M symbols given in their typesetted form:\n - the overbar above the numbers MUST be changed to the minus sign in front of the digit (e.g. '-2');\n - subscripts that denote screw axes are written as digits immediately after the axis designator without a space (e.g. 'P 32')\n - the space group generators MUST be separated by a single space (e.g. 'P 21 21 2');\n - there MUST be no spaces in the space group generator designation (i.e. use 'P 21/m', not the 'P 21 / m');\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n\n- **Examples**:\n - `C 2`\n - `P 21 21 21`\n\n- **Bibliographic References**:\n\nIUCr (2005). International Tables for Crystallography vol. A. Space-Group Symmetry. Ed. Theo Hahn. 5-th edition. Dordrecht, Springer.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "space_group_it_number": { "type": "integer", @@ -4681,8 +4702,8 @@ "minimum": 1.0, "title": "Space Group It Number", "description": "Space group number for the structure assigned by the International Tables for Crystallography Vol. A.\n- **Type**: integer\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - The integer value MUST be between 1 and 230.\n - MUST be null if `nperiodic_dimensions` is not equal to 3.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "cartesian_site_positions": { "items": { @@ -4696,18 +4717,18 @@ "type": "array", "title": "Cartesian Site Positions", "description": "Cartesian positions of each site in the structure.\nA site is usually used to describe positions of atoms; what atoms can be encountered at a given site is conveyed by the `species_at_sites` property, and the species themselves are described in the `species` property.\n\n- **Type**: list of list of floats\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - It MUST be a list of length equal to the number of sites in the structure, where every element is a list of the three Cartesian coordinates of a site expressed as float values in the unit angstrom (\u00c5).\n - An entry MAY have multiple sites at the same Cartesian position (for a relevant use of this, see e.g., the property `assemblies`).\n\n- **Examples**:\n - `[[0,0,0],[0,0,2]]` indicates a structure with two sites, one sitting at the origin and one along the (positive) *z*-axis, 2 \u00c5 away from the origin.", + "x-optimade-support": "should", "x-optimade-queryable": "optional", "x-optimade-unit": "\u00c5", - "nullable": true, - "x-optimade-support": "should" + "nullable": true }, "nsites": { "type": "integer", "title": "Nsites", "description": "An integer specifying the length of the `cartesian_site_positions` property.\n\n- **Type**: integer\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `42`\n\n- **Query examples**:\n - Match only structures with exactly 4 sites: `nsites=4`\n - Match structures that have between 2 and 7 sites: `nsites>=2 AND nsites<=7`", + "x-optimade-support": "should", "x-optimade-queryable": "must", - "nullable": true, - "x-optimade-support": "should" + "nullable": true }, "species": { "items": { @@ -4716,9 +4737,9 @@ "type": "array", "title": "Species", "description": "A list describing the species of the sites of this structure.\nSpecies can represent pure chemical elements, virtual-crystal atoms representing a statistical occupation of a given site by multiple chemical elements, and/or a location to which there are attached atoms, i.e., atoms whose precise location are unknown beyond that they are attached to that position (frequently used to indicate hydrogen atoms attached to another element, e.g., a carbon with three attached hydrogens might represent a methyl group, -CH3).\n\n- **Type**: list of dictionary with keys:\n - `name`: string (REQUIRED)\n - `chemical_symbols`: list of strings (REQUIRED)\n - `concentration`: list of float (REQUIRED)\n - `attached`: list of strings (REQUIRED)\n - `nattached`: list of integers (OPTIONAL)\n - `mass`: list of floats (OPTIONAL)\n - `original_name`: string (OPTIONAL).\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - Each list member MUST be a dictionary with the following keys:\n - **name**: REQUIRED; gives the name of the species; the **name** value MUST be unique in the `species` list;\n - **chemical_symbols**: REQUIRED; MUST be a list of strings of all chemical elements composing this species.\n Each item of the list MUST be one of the following:\n - a valid chemical-element symbol, or\n - the special value `\"X\"` to represent a non-chemical element, or\n - the special value `\"vacancy\"` to represent that this site has a non-zero probability of having a vacancy (the respective probability is indicated in the `concentration` list, see below).\n\n If any one entry in the `species` list has a `chemical_symbols` list that is longer than 1 element, the correct flag MUST be set in the list `structure_features`.\n\n - **concentration**: REQUIRED; MUST be a list of floats, with same length as `chemical_symbols`.\n The numbers represent the relative concentration of the corresponding chemical symbol in this species.\n The numbers SHOULD sum to one. Cases in which the numbers do not sum to one typically fall only in the following two categories:\n\n - Numerical errors when representing float numbers in fixed precision, e.g. for two chemical symbols with concentrations `1/3` and `2/3`, the concentration might look something like `[0.33333333333, 0.66666666666]`. If the client is aware that the sum is not one because of numerical precision, it can renormalize the values so that the sum is exactly one.\n - Experimental errors in the data present in the database. In this case, it is the responsibility of the client to decide how to process the data.\n\n Note that concentrations are uncorrelated between different sites (even of the same species).\n\n - **attached**: OPTIONAL; if provided MUST be a list of length 1 or more of strings of chemical symbols for the elements attached to this site, or \"X\" for a non-chemical element.\n\n - **nattached**: OPTIONAL; if provided MUST be a list of length 1 or more of integers indicating the number of attached atoms of the kind specified in the value of the `attached` key.\n\n The implementation MUST include either both or none of the `attached` and `nattached` keys, and if they are provided, they MUST be of the same length.\n Furthermore, if they are provided, the `structure_features` property MUST include the string `site_attachments`.\n\n - **mass**: OPTIONAL. If present MUST be a list of floats, with the same length as `chemical_symbols`, providing element masses expressed in a.m.u.\n Elements denoting vacancies MUST have masses equal to 0.\n\n - **original_name**: OPTIONAL. Can be any valid Unicode string, and SHOULD contain (if specified) the name of the species that is used internally in the source database.\n\n Note: With regards to \"source database\", we refer to the immediate source being queried via the OPTIMADE API implementation.\n\n The main use of this field is for source databases that use species names, containing characters that are not allowed (see description of the list property `species_at_sites`).\n\n - For systems that have only species formed by a single chemical symbol, and that have at most one species per chemical symbol, SHOULD use the chemical symbol as species name (e.g., `\"Ti\"` for titanium, `\"O\"` for oxygen, etc.)\n However, note that this is OPTIONAL, and client implementations MUST NOT assume that the key corresponds to a chemical symbol, nor assume that if the species name is a valid chemical symbol, that it represents a species with that chemical symbol.\n This means that a species `{\"name\": \"C\", \"chemical_symbols\": [\"Ti\"], \"concentration\": [1.0]}` is valid and represents a titanium species (and *not* a carbon species).\n - It is NOT RECOMMENDED that a structure includes species that do not have at least one corresponding site.\n\n- **Examples**:\n - `[ {\"name\": \"Ti\", \"chemical_symbols\": [\"Ti\"], \"concentration\": [1.0]} ]`: any site with this species is occupied by a Ti atom.\n - `[ {\"name\": \"Ti\", \"chemical_symbols\": [\"Ti\", \"vacancy\"], \"concentration\": [0.9, 0.1]} ]`: any site with this species is occupied by a Ti atom with 90 % probability, and has a vacancy with 10 % probability.\n - `[ {\"name\": \"BaCa\", \"chemical_symbols\": [\"vacancy\", \"Ba\", \"Ca\"], \"concentration\": [0.05, 0.45, 0.5], \"mass\": [0.0, 137.327, 40.078]} ]`: any site with this species is occupied by a Ba atom with 45 % probability, a Ca atom with 50 % probability, and by a vacancy with 5 % probability. The mass of this site is (on average) 88.5 a.m.u.\n - `[ {\"name\": \"C12\", \"chemical_symbols\": [\"C\"], \"concentration\": [1.0], \"mass\": [12.0]} ]`: any site with this species is occupied by a carbon isotope with mass 12.\n - `[ {\"name\": \"C13\", \"chemical_symbols\": [\"C\"], \"concentration\": [1.0], \"mass\": [13.0]} ]`: any site with this species is occupied by a carbon isotope with mass 13.\n - `[ {\"name\": \"CH3\", \"chemical_symbols\": [\"C\"], \"concentration\": [1.0], \"attached\": [\"H\"], \"nattached\": [3]} ]`: any site with this species is occupied by a methyl group, -CH3, which is represented without specifying precise positions of the hydrogen atoms.", + "x-optimade-support": "should", "x-optimade-queryable": "optional", - "nullable": true, - "x-optimade-support": "should" + "nullable": true }, "species_at_sites": { "items": { @@ -4727,9 +4748,9 @@ "type": "array", "title": "Species At Sites", "description": "Name of the species at each site (where values for sites are specified with the same order of the property `cartesian_site_positions`).\nThe properties of the species are found in the property `species`.\n\n- **Type**: list of strings.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - MUST have length equal to the number of sites in the structure (first dimension of the list property `cartesian_site_positions`).\n - Each species name mentioned in the `species_at_sites` list MUST be described in the list property `species` (i.e. for each value in the `species_at_sites` list there MUST exist exactly one dictionary in the `species` list with the `name` attribute equal to the corresponding `species_at_sites` value).\n - Each site MUST be associated only to a single species.\n **Note**: However, species can represent mixtures of atoms, and multiple species MAY be defined for the same chemical element.\n This latter case is useful when different atoms of the same type need to be grouped or distinguished, for instance in simulation codes to assign different initial spin states.\n\n- **Examples**:\n - `[\"Ti\",\"O2\"]` indicates that the first site is hosting a species labeled `\"Ti\"` and the second a species labeled `\"O2\"`.\n - `[\"Ac\", \"Ac\", \"Ag\", \"Ir\"]` indicating the first two sites contains the `\"Ac\"` species, while the third and fourth sites contain the `\"Ag\"` and `\"Ir\"` species, respectively.", + "x-optimade-support": "should", "x-optimade-queryable": "optional", - "nullable": true, - "x-optimade-support": "should" + "nullable": true }, "assemblies": { "items": { @@ -4738,8 +4759,8 @@ "type": "array", "title": "Assemblies", "description": "A description of groups of sites that are statistically correlated.\n\n- **Type**: list of dictionary with keys:\n - `sites_in_groups`: list of list of integers (REQUIRED)\n - `group_probabilities`: list of floats (REQUIRED)\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - The property SHOULD be `null` for entries that have no partial occupancies.\n - If present, the correct flag MUST be set in the list `structure_features`.\n - Client implementations MUST check its presence (as its presence changes the interpretation of the structure).\n - If present, it MUST be a list of dictionaries, each of which represents an assembly and MUST have the following two keys:\n - **sites_in_groups**: Index of the sites (0-based) that belong to each group for each assembly.\n\n Example: `[[1], [2]]`: two groups, one with the second site, one with the third.\n Example: `[[1,2], [3]]`: one group with the second and third site, one with the fourth.\n\n - **group_probabilities**: Statistical probability of each group. It MUST have the same length as `sites_in_groups`.\n It SHOULD sum to one.\n See below for examples of how to specify the probability of the occurrence of a vacancy.\n The possible reasons for the values not to sum to one are the same as already specified above for the `concentration` of each `species`.\n\n - If a site is not present in any group, it means that it is present with 100 % probability (as if no assembly was specified).\n - A site MUST NOT appear in more than one group.\n\n- **Examples** (for each entry of the assemblies list):\n - `{\"sites_in_groups\": [[0], [1]], \"group_probabilities: [0.3, 0.7]}`: the first site and the second site never occur at the same time in the unit cell.\n Statistically, 30 % of the times the first site is present, while 70 % of the times the second site is present.\n - `{\"sites_in_groups\": [[1,2], [3]], \"group_probabilities: [0.3, 0.7]}`: the second and third site are either present together or not present; they form the first group of atoms for this assembly.\n The second group is formed by the fourth site.\n Sites of the first group (the second and the third) are never present at the same time as the fourth site.\n 30 % of times sites 1 and 2 are present (and site 3 is absent); 70 % of times site 3 is present (and sites 1 and 2 are absent).\n\n- **Notes**:\n - Assemblies are essential to represent, for instance, the situation where an atom can statistically occupy two different positions (sites).\n\n - By defining groups, it is possible to represent, e.g., the case where a functional molecule (and not just one atom) is either present or absent (or the case where it it is present in two conformations)\n\n - Considerations on virtual alloys and on vacancies: In the special case of a virtual alloy, these specifications allow two different, equivalent ways of specifying them.\n For instance, for a site at the origin with 30 % probability of being occupied by Si, 50 % probability of being occupied by Ge, and 20 % of being a vacancy, the following two representations are possible:\n\n - Using a single species:\n ```json\n {\n \"cartesian_site_positions\": [[0,0,0]],\n \"species_at_sites\": [\"SiGe-vac\"],\n \"species\": [\n {\n \"name\": \"SiGe-vac\",\n \"chemical_symbols\": [\"Si\", \"Ge\", \"vacancy\"],\n \"concentration\": [0.3, 0.5, 0.2]\n }\n ]\n // ...\n }\n ```\n\n - Using multiple species and the assemblies:\n ```json\n {\n \"cartesian_site_positions\": [ [0,0,0], [0,0,0], [0,0,0] ],\n \"species_at_sites\": [\"Si\", \"Ge\", \"vac\"],\n \"species\": [\n { \"name\": \"Si\", \"chemical_symbols\": [\"Si\"], \"concentration\": [1.0] },\n { \"name\": \"Ge\", \"chemical_symbols\": [\"Ge\"], \"concentration\": [1.0] },\n { \"name\": \"vac\", \"chemical_symbols\": [\"vacancy\"], \"concentration\": [1.0] }\n ],\n \"assemblies\": [\n {\n \"sites_in_groups\": [ [0], [1], [2] ],\n \"group_probabilities\": [0.3, 0.5, 0.2]\n }\n ]\n // ...\n }\n ```\n\n - It is up to the database provider to decide which representation to use, typically depending on the internal format in which the structure is stored.\n However, given a structure identified by a unique ID, the API implementation MUST always provide the same representation for it.\n\n - The probabilities of occurrence of different assemblies are uncorrelated.\n So, for instance in the following case with two assemblies:\n ```json\n {\n \"assemblies\": [\n {\n \"sites_in_groups\": [ [0], [1] ],\n \"group_probabilities\": [0.2, 0.8],\n },\n {\n \"sites_in_groups\": [ [2], [3] ],\n \"group_probabilities\": [0.3, 0.7]\n }\n ]\n }\n ```\n\n Site 0 is present with a probability of 20 % and site 1 with a probability of 80 %. These two sites are correlated (either site 0 or 1 is present). Similarly, site 2 is present with a probability of 30 % and site 3 with a probability of 70 %.\n These two sites are correlated (either site 2 or 3 is present).\n However, the presence or absence of sites 0 and 1 is not correlated with the presence or absence of sites 2 and 3 (in the specific example, the pair of sites (0, 2) can occur with 0.2*0.3 = 6 % probability; the pair (0, 3) with 0.2*0.7 = 14 % probability; the pair (1, 2) with 0.8*0.3 = 24 % probability; and the pair (1, 3) with 0.8*0.7 = 56 % probability).", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "structure_features": { "items": { @@ -4748,8 +4769,8 @@ "type": "array", "title": "Structure Features", "description": "A list of strings that flag which special features are used by the structure.\n\n- **Type**: list of strings\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property.\n Filters on the list MUST support all mandatory HAS-type queries.\n Filter operators for comparisons on the string components MUST support equality, support for other comparison operators are OPTIONAL.\n - MUST be an empty list if no special features are used.\n - MUST be sorted alphabetically.\n - If a special feature listed below is used, the list MUST contain the corresponding string.\n - If a special feature listed below is not used, the list MUST NOT contain the corresponding string.\n - **List of strings used to indicate special structure features**:\n - `disorder`: this flag MUST be present if any one entry in the `species` list has a `chemical_symbols` list that is longer than 1 element.\n - `implicit_atoms`: this flag MUST be present if the structure contains atoms that are not assigned to sites via the property `species_at_sites` (e.g., because their positions are unknown).\n When this flag is present, the properties related to the chemical formula will likely not match the type and count of atoms represented by the `species_at_sites`, `species` and `assemblies` properties.\n - `site_attachments`: this flag MUST be present if any one entry in the `species` list includes `attached` and `nattached`.\n - `assemblies`: this flag MUST be present if the property `assemblies` is present.\n\n- **Examples**: A structure having implicit atoms and using assemblies: `[\"assemblies\", \"implicit_atoms\"]`", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" } }, "type": "object", diff --git a/optimade/models/responses.py b/optimade/models/responses.py index c0fceb8fd..2d5814176 100644 --- a/optimade/models/responses.py +++ b/optimade/models/responses.py @@ -107,13 +107,13 @@ class StructureResponseMany(EntryResponseMany): class FileResponseOne(EntryResponseOne): - data: Union[FileResource, Dict[str, Any], None] = StrictField( + data: Union[FileResource, dict[str, Any], None] = StrictField( ..., description="A single files entry resource." ) class FileResponseMany(EntryResponseMany): - data: Union[List[FileResource], List[Dict[str, Any]]] = StrictField( + data: Union[list[FileResource], list[dict[str, Any]]] = StrictField( ..., description="List of unique OPTIMADE files entry resource objects.", uniqueItems=True, From b8abdc7310917696054c44a633eb9d8f3faec524 Mon Sep 17 00:00:00 2001 From: Matthew Evans Date: Sat, 23 Dec 2023 13:32:15 +0000 Subject: [PATCH 16/19] Remove space from regexp --- openapi/openapi.json | 30 +++++++++++++++--------------- optimade/models/utils.py | 2 +- 2 files changed, 16 insertions(+), 16 deletions(-) diff --git a/openapi/openapi.json b/openapi/openapi.json index 98c6bb92e..3e8fa0c8a 100644 --- a/openapi/openapi.json +++ b/openapi/openapi.json @@ -4582,9 +4582,9 @@ "type": "integer", "title": "Nelements", "description": "Number of different elements in the structure as an integer.\n\n- **Type**: integer\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - MUST be equal to the lengths of the list properties `elements` and `elements_ratios`, if they are provided.\n\n- **Examples**:\n - `3`\n\n- **Querying**:\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`.", + "nullable": true, "x-optimade-support": "should", - "x-optimade-queryable": "must", - "nullable": true + "x-optimade-queryable": "must" }, "elements_ratios": { "items": { @@ -4601,9 +4601,9 @@ "type": "string", "title": "Chemical Formula Descriptive", "description": "The chemical formula for a structure as a string in a form chosen by the API implementation.\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - The chemical formula is given as a string consisting of properly capitalized element symbols followed by integers or decimal numbers, balanced parentheses, square, and curly brackets `(`,`)`, `[`,`]`, `{`, `}`, commas, the `+`, `-`, `:` and `=` symbols. The parentheses are allowed to be followed by a number. Spaces are allowed anywhere except within chemical symbols. The order of elements and any groupings indicated by parentheses or brackets are chosen freely by the API implementation.\n - The string SHOULD be arithmetically consistent with the element ratios in the `chemical_formula_reduced` property.\n - It is RECOMMENDED, but not mandatory, that symbols, parentheses and brackets, if used, are used with the meanings prescribed by [IUPAC's Nomenclature of Organic Chemistry](https://www.qmul.ac.uk/sbcs/iupac/bibliog/blue.html).\n\n- **Examples**:\n - `\"(H2O)2 Na\"`\n - `\"NaCl\"`\n - `\"CaCO3\"`\n - `\"CCaO3\"`\n - `\"(CH3)3N+ - [CH2]2-OH = Me3N+ - CH2 - CH2OH\"`\n\n- **Query examples**:\n - Note: the free-form nature of this property is likely to make queries on it across different databases inconsistent.\n - A filter that matches an exactly given formula: `chemical_formula_descriptive=\"(H2O)2 Na\"`.\n - A filter that does a partial match: `chemical_formula_descriptive CONTAINS \"H2O\"`.", + "nullable": true, "x-optimade-support": "should", - "x-optimade-queryable": "must", - "nullable": true + "x-optimade-queryable": "must" }, "chemical_formula_reduced": { "type": "string", @@ -4640,17 +4640,17 @@ "minItems": 3, "title": "Dimension Types", "description": "List of three integers.\nFor each of the three directions indicated by the three lattice vectors (see property `lattice_vectors`), this list indicates if the direction is periodic (value `1`) or non-periodic (value `0`).\nNote: the elements in this list each refer to the direction of the corresponding entry in `lattice_vectors` and *not* the Cartesian x, y, z directions.\n\n- **Type**: list of integers.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - MUST be a list of length 3.\n - Each integer element MUST assume only the value 0 or 1.\n\n- **Examples**:\n - For a molecule: `[0, 0, 0]`\n - For a wire along the direction specified by the third lattice vector: `[0, 0, 1]`\n - For a 2D surface/slab, periodic on the plane defined by the first and third lattice vectors: `[1, 0, 1]`\n - For a bulk 3D system: `[1, 1, 1]`", + "nullable": true, "x-optimade-support": "should", - "x-optimade-queryable": "optional", - "nullable": true + "x-optimade-queryable": "optional" }, "nperiodic_dimensions": { "type": "integer", "title": "Nperiodic Dimensions", "description": "An integer specifying the number of periodic dimensions in the structure, equivalent to the number of non-zero entries in `dimension_types`.\n\n- **Type**: integer\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - The integer value MUST be between 0 and 3 inclusive and MUST be equal to the sum of the items in the `dimension_types` property.\n - This property only reflects the treatment of the lattice vectors provided for the structure, and not any physical interpretation of the dimensionality of its contents.\n\n- **Examples**:\n - `2` should be indicated in cases where `dimension_types` is any of `[1, 1, 0]`, `[1, 0, 1]`, `[0, 1, 1]`.\n\n- **Query examples**:\n - Match only structures with exactly 3 periodic dimensions: `nperiodic_dimensions=3`\n - Match all structures with 2 or fewer periodic dimensions: `nperiodic_dimensions<=2`", + "nullable": true, "x-optimade-support": "should", - "x-optimade-queryable": "must", - "nullable": true + "x-optimade-queryable": "must" }, "lattice_vectors": { "items": { @@ -4666,15 +4666,15 @@ "minItems": 3, "title": "Lattice Vectors", "description": "The three lattice vectors in Cartesian coordinates, in \u00e5ngstr\u00f6m (\u00c5).\n\n- **Type**: list of list of floats or unknown values.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - MUST be a list of three vectors *a*, *b*, and *c*, where each of the vectors MUST BE a list of the vector's coordinates along the x, y, and z Cartesian coordinates.\n (Therefore, the first index runs over the three lattice vectors and the second index runs over the x, y, z Cartesian coordinates).\n - For databases that do not define an absolute Cartesian system (e.g., only defining the length and angles between vectors), the first lattice vector SHOULD be set along *x* and the second on the *xy*-plane.\n - MUST always contain three vectors of three coordinates each, independently of the elements of property `dimension_types`.\n The vectors SHOULD by convention be chosen so the determinant of the `lattice_vectors` matrix is different from zero.\n The vectors in the non-periodic directions have no significance beyond fulfilling these requirements.\n - The coordinates of the lattice vectors of non-periodic dimensions (i.e., those dimensions for which `dimension_types` is `0`) MAY be given as a list of all `null` values.\n If a lattice vector contains the value `null`, all coordinates of that lattice vector MUST be `null`.\n\n- **Examples**:\n - `[[4.0,0.0,0.0],[0.0,4.0,0.0],[0.0,1.0,4.0]]` represents a cell, where the first vector is `(4, 0, 0)`, i.e., a vector aligned along the `x` axis of length 4 \u00c5; the second vector is `(0, 4, 0)`; and the third vector is `(0, 1, 4)`.", + "nullable": true, "x-optimade-support": "should", "x-optimade-queryable": "optional", - "x-optimade-unit": "\u00c5", - "nullable": true + "x-optimade-unit": "\u00c5" }, "space_group_symmetry_operations_xyz": { "items": { "type": "string", - "pattern": "^([-+]? [xyz] ([-+][xyz])? ([-+] (1/2|[12]/3|[1-3]/4|[1-5]/6) )?|[-+]? (1/2|[12]/3|[1-3]/4|[1-5]/6) ([-+] [xyz] ([-+][xyz])? )?),([-+]? [xyz] ([-+][xyz])? ([-+] (1/2|[12]/3|[1-3]/4|[1-5]/6) )?|[-+]? (1/2|[12]/3|[1-3]/4|[1-5]/6) ([-+] [xyz] ([-+][xyz])? )?),([-+]? [xyz] ([-+][xyz])? ([-+] (1/2|[12]/3|[1-3]/4|[1-5]/6) )?|[-+]? (1/2|[12]/3|[1-3]/4|[1-5]/6) ([-+] [xyz] ([-+][xyz])? )?)$" + "pattern": "^([-+]?[xyz]([-+][xyz])?([-+](1/2|[12]/3|[1-3]/4|[1-5]/6))?|[-+]?(1/2|[12]/3|[1-3]/4|[1-5]/6)([-+][xyz]([-+][xyz])?)?),([-+]?[xyz]([-+][xyz])?([-+](1/2|[12]/3|[1-3]/4|[1-5]/6))?|[-+]?(1/2|[12]/3|[1-3]/4|[1-5]/6)([-+][xyz]([-+][xyz])?)?),([-+]?[xyz]([-+][xyz])?([-+](1/2|[12]/3|[1-3]/4|[1-5]/6))?|[-+]?(1/2|[12]/3|[1-3]/4|[1-5]/6)([-+][xyz]([-+][xyz])?)?)$" }, "type": "array", "title": "Space Group Symmetry Operations Xyz", @@ -4717,18 +4717,18 @@ "type": "array", "title": "Cartesian Site Positions", "description": "Cartesian positions of each site in the structure.\nA site is usually used to describe positions of atoms; what atoms can be encountered at a given site is conveyed by the `species_at_sites` property, and the species themselves are described in the `species` property.\n\n- **Type**: list of list of floats\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - It MUST be a list of length equal to the number of sites in the structure, where every element is a list of the three Cartesian coordinates of a site expressed as float values in the unit angstrom (\u00c5).\n - An entry MAY have multiple sites at the same Cartesian position (for a relevant use of this, see e.g., the property `assemblies`).\n\n- **Examples**:\n - `[[0,0,0],[0,0,2]]` indicates a structure with two sites, one sitting at the origin and one along the (positive) *z*-axis, 2 \u00c5 away from the origin.", + "nullable": true, "x-optimade-support": "should", "x-optimade-queryable": "optional", - "x-optimade-unit": "\u00c5", - "nullable": true + "x-optimade-unit": "\u00c5" }, "nsites": { "type": "integer", "title": "Nsites", "description": "An integer specifying the length of the `cartesian_site_positions` property.\n\n- **Type**: integer\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `42`\n\n- **Query examples**:\n - Match only structures with exactly 4 sites: `nsites=4`\n - Match structures that have between 2 and 7 sites: `nsites>=2 AND nsites<=7`", + "nullable": true, "x-optimade-support": "should", - "x-optimade-queryable": "must", - "nullable": true + "x-optimade-queryable": "must" }, "species": { "items": { diff --git a/optimade/models/utils.py b/optimade/models/utils.py index 4e72ea3d2..cdba8ce1c 100644 --- a/optimade/models/utils.py +++ b/optimade/models/utils.py @@ -429,5 +429,5 @@ def reduce_formula(formula: str) -> str: translation = "1/2|[12]/3|[1-3]/4|[1-5]/6" translation_appended = f"[-+]? [xyz] ([-+][xyz])? ([-+] ({translation}) )?" translation_prepended = f"[-+]? ({translation}) ([-+] [xyz] ([-+][xyz])? )?" -symop = f"({translation_appended}|{translation_prepended})" +symop = f"({translation_appended}|{translation_prepended})".replace(" ", "") SPACE_GROUP_SYMMETRY_OPERATION_REGEX = f"^{symop},{symop},{symop}$" From 8168f7323485862902f33a6cb7de6658ce60e623 Mon Sep 17 00:00:00 2001 From: Matthew Evans Date: Sat, 23 Dec 2023 13:33:17 +0000 Subject: [PATCH 17/19] Remove space from regexp --- openapi/index_openapi.json | 20 +-- openapi/openapi.json | 288 ++++++++++++++++++------------------- optimade/models/utils.py | 2 +- 3 files changed, 155 insertions(+), 155 deletions(-) diff --git a/openapi/index_openapi.json b/openapi/index_openapi.json index 62c29ef4a..337e33d09 100644 --- a/openapi/index_openapi.json +++ b/openapi/index_openapi.json @@ -498,15 +498,15 @@ "type": "string", "title": "Id", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "type": { "type": "string", "title": "Type", "description": "The name of the type of an entry.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - MUST be an existing entry type.\n - The entry of type `` and ID `` MUST be returned in response to a request for `//` under the versioned base URL.\n\n- **Example**: `\"structures\"`", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "links": { "allOf": [ @@ -560,16 +560,16 @@ "type": "string", "title": "Immutable Id", "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", - "x-optimade-support": "optional", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "optional" }, "last_modified": { "type": "string", "format": "date-time", "title": "Last Modified", "description": "Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n - As part of JSON response format: `\"2007-04-05T14:30:20Z\"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)", - "x-optimade-support": "should", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "should" } }, "type": "object", @@ -1107,8 +1107,8 @@ "type": "string", "title": "Id", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "type": { "type": "string", diff --git a/openapi/openapi.json b/openapi/openapi.json index 55ae3d7e5..7a61435bd 100644 --- a/openapi/openapi.json +++ b/openapi/openapi.json @@ -1335,8 +1335,8 @@ "type": "array", "title": "Sites In Groups", "description": "Index of the sites (0-based) that belong to each group for each assembly.\n\n- **Examples**:\n - `[[1], [2]]`: two groups, one with the second site, one with the third.\n - `[[1,2], [3]]`: one group with the second and third site, one with the fourth.", - "x-optimade-support": "must", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "must" }, "group_probabilities": { "items": { @@ -1345,8 +1345,8 @@ "type": "array", "title": "Group Probabilities", "description": "Statistical probability of each group. It MUST have the same length as `sites_in_groups`.\nIt SHOULD sum to one.\nSee below for examples of how to specify the probability of the occurrence of a vacancy.\nThe possible reasons for the values not to sum to one are the same as already specified above for the `concentration` of each `species`.", - "x-optimade-support": "must", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "must" } }, "type": "object", @@ -1748,15 +1748,15 @@ "type": "string", "title": "Id", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "type": { "type": "string", "title": "Type", "description": "The name of the type of an entry.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - MUST be an existing entry type.\n - The entry of type `` and ID `` MUST be returned in response to a request for `//` under the versioned base URL.\n\n- **Example**: `\"structures\"`", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "links": { "allOf": [ @@ -1810,16 +1810,16 @@ "type": "string", "title": "Immutable Id", "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", - "x-optimade-support": "optional", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "optional" }, "last_modified": { "type": "string", "format": "date-time", "title": "Last Modified", "description": "Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n - As part of JSON response format: `\"2007-04-05T14:30:20Z\"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)", - "x-optimade-support": "should", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "should" } }, "type": "object", @@ -2216,8 +2216,8 @@ "type": "string", "title": "Id", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "type": { "type": "string", @@ -2517,22 +2517,22 @@ "type": "string", "title": "Name", "description": "Full name of the person, REQUIRED.", - "x-optimade-support": "must", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "must" }, "firstname": { "type": "string", "title": "Firstname", "description": "First name of the person.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "lastname": { "type": "string", "title": "Lastname", "description": "Last name of the person.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" } }, "type": "object", @@ -2632,8 +2632,8 @@ "type": "string", "title": "Id", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "type": { "type": "string", @@ -2641,8 +2641,8 @@ "title": "Type", "description": "The name of the type of an entry.\n- **Type**: string.\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - MUST be an existing entry type.\n - The entry of type and ID MUST be returned in response to a request for `//` under the versioned base URL.\n- **Example**: `\"structures\"`", "default": "references", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "links": { "allOf": [ @@ -2690,16 +2690,16 @@ "type": "string", "title": "Immutable Id", "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", - "x-optimade-support": "optional", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "optional" }, "last_modified": { "type": "string", "format": "date-time", "title": "Last Modified", "description": "Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n - As part of JSON response format: `\"2007-04-05T14:30:20Z\"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)", - "x-optimade-support": "should", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "should" }, "authors": { "items": { @@ -2708,8 +2708,8 @@ "type": "array", "title": "Authors", "description": "List of person objects containing the authors of the reference.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "editors": { "items": { @@ -2718,15 +2718,15 @@ "type": "array", "title": "Editors", "description": "List of person objects containing the editors of the reference.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "doi": { "type": "string", "title": "Doi", "description": "The digital object identifier of the reference.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "url": { "type": "string", @@ -2735,162 +2735,162 @@ "format": "uri", "title": "Url", "description": "The URL of the reference.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "address": { "type": "string", "title": "Address", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "annote": { "type": "string", "title": "Annote", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "booktitle": { "type": "string", "title": "Booktitle", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "chapter": { "type": "string", "title": "Chapter", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "crossref": { "type": "string", "title": "Crossref", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "edition": { "type": "string", "title": "Edition", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "howpublished": { "type": "string", "title": "Howpublished", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "institution": { "type": "string", "title": "Institution", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "journal": { "type": "string", "title": "Journal", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "key": { "type": "string", "title": "Key", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "month": { "type": "string", "title": "Month", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "note": { "type": "string", "title": "Note", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "number": { "type": "string", "title": "Number", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "organization": { "type": "string", "title": "Organization", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "pages": { "type": "string", "title": "Pages", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "publisher": { "type": "string", "title": "Publisher", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "school": { "type": "string", "title": "School", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "series": { "type": "string", "title": "Series", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "title": { "type": "string", "title": "Title", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "bib_type": { "type": "string", "title": "Bib Type", "description": "Type of the reference, corresponding to the **type** property in the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "volume": { "type": "string", "title": "Volume", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "year": { "type": "string", "title": "Year", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" } }, "type": "object", @@ -3310,8 +3310,8 @@ "type": "string", "title": "Name", "description": "Gives the name of the species; the **name** value MUST be unique in the `species` list.", - "x-optimade-support": "must", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "must" }, "chemical_symbols": { "items": { @@ -3320,8 +3320,8 @@ "type": "array", "title": "Chemical Symbols", "description": "MUST be a list of strings of all chemical elements composing this species. Each item of the list MUST be one of the following:\n\n- a valid chemical-element symbol, or\n- the special value `\"X\"` to represent a non-chemical element, or\n- the special value `\"vacancy\"` to represent that this site has a non-zero probability of having a vacancy (the respective probability is indicated in the `concentration` list, see below).\n\nIf any one entry in the `species` list has a `chemical_symbols` list that is longer than 1 element, the correct flag MUST be set in the list `structure_features`.", - "x-optimade-support": "must", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "must" }, "concentration": { "items": { @@ -3330,8 +3330,8 @@ "type": "array", "title": "Concentration", "description": "MUST be a list of floats, with same length as `chemical_symbols`. The numbers represent the relative concentration of the corresponding chemical symbol in this species. The numbers SHOULD sum to one. Cases in which the numbers do not sum to one typically fall only in the following two categories:\n\n- Numerical errors when representing float numbers in fixed precision, e.g. for two chemical symbols with concentrations `1/3` and `2/3`, the concentration might look something like `[0.33333333333, 0.66666666666]`. If the client is aware that the sum is not one because of numerical precision, it can renormalize the values so that the sum is exactly one.\n- Experimental errors in the data present in the database. In this case, it is the responsibility of the client to decide how to process the data.\n\nNote that concentrations are uncorrelated between different site (even of the same species).", - "x-optimade-support": "must", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "must" }, "mass": { "items": { @@ -3340,16 +3340,16 @@ "type": "array", "title": "Mass", "description": "If present MUST be a list of floats expressed in a.m.u.\nElements denoting vacancies MUST have masses equal to 0.", - "x-optimade-support": "optional", "x-optimade-queryable": "optional", - "x-optimade-unit": "a.m.u." + "x-optimade-unit": "a.m.u.", + "x-optimade-support": "optional" }, "original_name": { "type": "string", "title": "Original Name", "description": "Can be any valid Unicode string, and SHOULD contain (if specified) the name of the species that is used internally in the source database.\n\nNote: With regards to \"source database\", we refer to the immediate source being queried via the OPTIMADE API implementation.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "attached": { "items": { @@ -3358,8 +3358,8 @@ "type": "array", "title": "Attached", "description": "If provided MUST be a list of length 1 or more of strings of chemical symbols for the elements attached to this site, or \"X\" for a non-chemical element.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "nattached": { "items": { @@ -3368,8 +3368,8 @@ "type": "array", "title": "Nattached", "description": "If provided MUST be a list of length 1 or more of integers indicating the number of attached atoms of the kind specified in the value of the :field:`attached` key.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" } }, "type": "object", @@ -3438,8 +3438,8 @@ "type": "string", "title": "Id", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "type": { "type": "string", @@ -3447,8 +3447,8 @@ "title": "Type", "description": "The name of the type of an entry.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - MUST be an existing entry type.\n - The entry of type `` and ID `` MUST be returned in response to a request for `//` under the versioned base URL.\n\n- **Examples**:\n - `\"structures\"`", "default": "structures", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "links": { "allOf": [ @@ -3496,17 +3496,17 @@ "type": "string", "title": "Immutable Id", "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", - "x-optimade-support": "optional", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "optional" }, "last_modified": { "type": "string", "format": "date-time", "title": "Last Modified", "description": "Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n - As part of JSON response format: `\"2007-04-05T14:30:20Z\"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)", - "nullable": true, + "x-optimade-queryable": "must", "x-optimade-support": "should", - "x-optimade-queryable": "must" + "nullable": true }, "elements": { "items": { @@ -3515,17 +3515,17 @@ "type": "array", "title": "Elements", "description": "The chemical symbols of the different elements present in the structure.\n\n- **Type**: list of strings.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - The strings are the chemical symbols, i.e., either a single uppercase letter or an uppercase letter followed by a number of lowercase letters.\n - The order MUST be alphabetical.\n - MUST refer to the same elements in the same order, and therefore be of the same length, as `elements_ratios`, if the latter is provided.\n - Note: This property SHOULD NOT contain the string \"X\" to indicate non-chemical elements or \"vacancy\" to indicate vacancies (in contrast to the field `chemical_symbols` for the `species` property).\n\n- **Examples**:\n - `[\"Si\"]`\n - `[\"Al\",\"O\",\"Si\"]`\n\n- **Query examples**:\n - A filter that matches all records of structures that contain Si, Al **and** O, and possibly other elements: `elements HAS ALL \"Si\", \"Al\", \"O\"`.\n - To match structures with exactly these three elements, use `elements HAS ALL \"Si\", \"Al\", \"O\" AND elements LENGTH 3`.\n - Note: length queries on this property can be equivalently formulated by filtering on the `nelements`_ property directly.", - "nullable": true, + "x-optimade-queryable": "must", "x-optimade-support": "should", - "x-optimade-queryable": "must" + "nullable": true }, "nelements": { "type": "integer", "title": "Nelements", "description": "Number of different elements in the structure as an integer.\n\n- **Type**: integer\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - MUST be equal to the lengths of the list properties `elements` and `elements_ratios`, if they are provided.\n\n- **Examples**:\n - `3`\n\n- **Querying**:\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`.", - "nullable": true, + "x-optimade-queryable": "must", "x-optimade-support": "should", - "x-optimade-queryable": "must" + "nullable": true }, "elements_ratios": { "items": { @@ -3534,43 +3534,43 @@ "type": "array", "title": "Elements Ratios", "description": "Relative proportions of different elements in the structure.\n\n- **Type**: list of floats\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - Composed by the proportions of elements in the structure as a list of floating point numbers.\n - The sum of the numbers MUST be 1.0 (within floating point accuracy)\n - MUST refer to the same elements in the same order, and therefore be of the same length, as `elements`, if the latter is provided.\n\n- **Examples**:\n - `[1.0]`\n - `[0.3333333333333333, 0.2222222222222222, 0.4444444444444444]`\n\n- **Query examples**:\n - Note: Useful filters can be formulated using the set operator syntax for correlated values.\n However, since the values are floating point values, the use of equality comparisons is generally inadvisable.\n - OPTIONAL: a filter that matches structures where approximately 1/3 of the atoms in the structure are the element Al is: `elements:elements_ratios HAS ALL \"Al\":>0.3333, \"Al\":<0.3334`.", - "nullable": true, + "x-optimade-queryable": "must", "x-optimade-support": "should", - "x-optimade-queryable": "must" + "nullable": true }, "chemical_formula_descriptive": { "type": "string", "title": "Chemical Formula Descriptive", "description": "The chemical formula for a structure as a string in a form chosen by the API implementation.\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - The chemical formula is given as a string consisting of properly capitalized element symbols followed by integers or decimal numbers, balanced parentheses, square, and curly brackets `(`,`)`, `[`,`]`, `{`, `}`, commas, the `+`, `-`, `:` and `=` symbols. The parentheses are allowed to be followed by a number. Spaces are allowed anywhere except within chemical symbols. The order of elements and any groupings indicated by parentheses or brackets are chosen freely by the API implementation.\n - The string SHOULD be arithmetically consistent with the element ratios in the `chemical_formula_reduced` property.\n - It is RECOMMENDED, but not mandatory, that symbols, parentheses and brackets, if used, are used with the meanings prescribed by [IUPAC's Nomenclature of Organic Chemistry](https://www.qmul.ac.uk/sbcs/iupac/bibliog/blue.html).\n\n- **Examples**:\n - `\"(H2O)2 Na\"`\n - `\"NaCl\"`\n - `\"CaCO3\"`\n - `\"CCaO3\"`\n - `\"(CH3)3N+ - [CH2]2-OH = Me3N+ - CH2 - CH2OH\"`\n\n- **Query examples**:\n - Note: the free-form nature of this property is likely to make queries on it across different databases inconsistent.\n - A filter that matches an exactly given formula: `chemical_formula_descriptive=\"(H2O)2 Na\"`.\n - A filter that does a partial match: `chemical_formula_descriptive CONTAINS \"H2O\"`.", - "nullable": true, + "x-optimade-queryable": "must", "x-optimade-support": "should", - "x-optimade-queryable": "must" + "nullable": true }, "chemical_formula_reduced": { "type": "string", "pattern": "(^$)|^([A-Z][a-z]?([2-9]|[1-9]\\d+)?)+$", "title": "Chemical Formula Reduced", "description": "The reduced chemical formula for a structure as a string with element symbols and integer chemical proportion numbers.\nThe proportion number MUST be omitted if it is 1.\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property.\n However, support for filters using partial string matching with this property is OPTIONAL (i.e., BEGINS WITH, ENDS WITH, and CONTAINS).\n Intricate queries on formula components are instead suggested to be formulated using set-type filter operators on the multi valued `elements` and `elements_ratios` properties.\n - Element symbols MUST have proper capitalization (e.g., `\"Si\"`, not `\"SI\"` for \"silicon\").\n - Elements MUST be placed in alphabetical order, followed by their integer chemical proportion number.\n - For structures with no partial occupation, the chemical proportion numbers are the smallest integers for which the chemical proportion is exactly correct.\n - For structures with partial occupation, the chemical proportion numbers are integers that within reasonable approximation indicate the correct chemical proportions. The precise details of how to perform the rounding is chosen by the API implementation.\n - No spaces or separators are allowed.\n\n- **Examples**:\n - `\"H2NaO\"`\n - `\"ClNa\"`\n - `\"CCaO3\"`\n\n- **Query examples**:\n - A filter that matches an exactly given formula is `chemical_formula_reduced=\"H2NaO\"`.", - "nullable": true, + "x-optimade-queryable": "must", "x-optimade-support": "should", - "x-optimade-queryable": "must" + "nullable": true }, "chemical_formula_hill": { "type": "string", "pattern": "(^$)|^([A-Z][a-z]?([2-9]|[1-9]\\d+)?)+$", "title": "Chemical Formula Hill", "description": "The chemical formula for a structure in [Hill form](https://dx.doi.org/10.1021/ja02046a005) with element symbols followed by integer chemical proportion numbers. The proportion number MUST be omitted if it is 1.\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, only a subset of the filter features MAY be supported.\n - The overall scale factor of the chemical proportions is chosen such that the resulting values are integers that indicate the most chemically relevant unit of which the system is composed.\n For example, if the structure is a repeating unit cell with four hydrogens and four oxygens that represents two hydroperoxide molecules, `chemical_formula_hill` is `\"H2O2\"` (i.e., not `\"HO\"`, nor `\"H4O4\"`).\n - If the chemical insight needed to ascribe a Hill formula to the system is not present, the property MUST be handled as unset.\n - Element symbols MUST have proper capitalization (e.g., `\"Si\"`, not `\"SI\"` for \"silicon\").\n - Elements MUST be placed in [Hill order](https://dx.doi.org/10.1021/ja02046a005), followed by their integer chemical proportion number.\n Hill order means: if carbon is present, it is placed first, and if also present, hydrogen is placed second.\n After that, all other elements are ordered alphabetically.\n If carbon is not present, all elements are ordered alphabetically.\n - If the system has sites with partial occupation and the total occupations of each element do not all sum up to integers, then the Hill formula SHOULD be handled as unset.\n - No spaces or separators are allowed.\n\n- **Examples**:\n - `\"H2O2\"`\n\n- **Query examples**:\n - A filter that matches an exactly given formula is `chemical_formula_hill=\"H2O2\"`.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "chemical_formula_anonymous": { "type": "string", "pattern": "(^$)|^([A-Z][a-z]?([2-9]|[1-9]\\d+)?)+$", "title": "Chemical Formula Anonymous", "description": "The anonymous formula is the `chemical_formula_reduced`, but where the elements are instead first ordered by their chemical proportion number, and then, in order left to right, replaced by anonymous symbols A, B, C, ..., Z, Aa, Ba, ..., Za, Ab, Bb, ... and so on.\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property.\n However, support for filters using partial string matching with this property is OPTIONAL (i.e., BEGINS WITH, ENDS WITH, and CONTAINS).\n\n- **Examples**:\n - `\"A2B\"`\n - `\"A42B42C16D12E10F9G5\"`\n\n- **Querying**:\n - A filter that matches an exactly given formula is `chemical_formula_anonymous=\"A2B\"`.", - "nullable": true, + "x-optimade-queryable": "must", "x-optimade-support": "should", - "x-optimade-queryable": "must" + "nullable": true }, "dimension_types": { "items": { @@ -3581,17 +3581,17 @@ "minItems": 3, "title": "Dimension Types", "description": "List of three integers.\nFor each of the three directions indicated by the three lattice vectors (see property `lattice_vectors`), this list indicates if the direction is periodic (value `1`) or non-periodic (value `0`).\nNote: the elements in this list each refer to the direction of the corresponding entry in `lattice_vectors` and *not* the Cartesian x, y, z directions.\n\n- **Type**: list of integers.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - MUST be a list of length 3.\n - Each integer element MUST assume only the value 0 or 1.\n\n- **Examples**:\n - For a molecule: `[0, 0, 0]`\n - For a wire along the direction specified by the third lattice vector: `[0, 0, 1]`\n - For a 2D surface/slab, periodic on the plane defined by the first and third lattice vectors: `[1, 0, 1]`\n - For a bulk 3D system: `[1, 1, 1]`", - "x-optimade-support": "should", "x-optimade-queryable": "optional", + "x-optimade-support": "should", "nullable": true }, "nperiodic_dimensions": { "type": "integer", "title": "Nperiodic Dimensions", "description": "An integer specifying the number of periodic dimensions in the structure, equivalent to the number of non-zero entries in `dimension_types`.\n\n- **Type**: integer\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - The integer value MUST be between 0 and 3 inclusive and MUST be equal to the sum of the items in the `dimension_types` property.\n - This property only reflects the treatment of the lattice vectors provided for the structure, and not any physical interpretation of the dimensionality of its contents.\n\n- **Examples**:\n - `2` should be indicated in cases where `dimension_types` is any of `[1, 1, 0]`, `[1, 0, 1]`, `[0, 1, 1]`.\n\n- **Query examples**:\n - Match only structures with exactly 3 periodic dimensions: `nperiodic_dimensions=3`\n - Match all structures with 2 or fewer periodic dimensions: `nperiodic_dimensions<=2`", - "nullable": true, + "x-optimade-queryable": "must", "x-optimade-support": "should", - "x-optimade-queryable": "must" + "nullable": true }, "lattice_vectors": { "items": { @@ -3607,35 +3607,35 @@ "minItems": 3, "title": "Lattice Vectors", "description": "The three lattice vectors in Cartesian coordinates, in \u00e5ngstr\u00f6m (\u00c5).\n\n- **Type**: list of list of floats or unknown values.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - MUST be a list of three vectors *a*, *b*, and *c*, where each of the vectors MUST BE a list of the vector's coordinates along the x, y, and z Cartesian coordinates.\n (Therefore, the first index runs over the three lattice vectors and the second index runs over the x, y, z Cartesian coordinates).\n - For databases that do not define an absolute Cartesian system (e.g., only defining the length and angles between vectors), the first lattice vector SHOULD be set along *x* and the second on the *xy*-plane.\n - MUST always contain three vectors of three coordinates each, independently of the elements of property `dimension_types`.\n The vectors SHOULD by convention be chosen so the determinant of the `lattice_vectors` matrix is different from zero.\n The vectors in the non-periodic directions have no significance beyond fulfilling these requirements.\n - The coordinates of the lattice vectors of non-periodic dimensions (i.e., those dimensions for which `dimension_types` is `0`) MAY be given as a list of all `null` values.\n If a lattice vector contains the value `null`, all coordinates of that lattice vector MUST be `null`.\n\n- **Examples**:\n - `[[4.0,0.0,0.0],[0.0,4.0,0.0],[0.0,1.0,4.0]]` represents a cell, where the first vector is `(4, 0, 0)`, i.e., a vector aligned along the `x` axis of length 4 \u00c5; the second vector is `(0, 4, 0)`; and the third vector is `(0, 1, 4)`.", - "x-optimade-support": "should", "x-optimade-queryable": "optional", - "x-optimade-unit": "\u00c5", - "nullable": true + "x-optimade-support": "should", + "nullable": true, + "x-optimade-unit": "\u00c5" }, "space_group_symmetry_operations_xyz": { "items": { "type": "string", - "pattern": "^([-+]? [xyz] ([-+][xyz])? ([-+] (1/2|[12]/3|[1-3]/4|[1-5]/6) )?|[-+]? (1/2|[12]/3|[1-3]/4|[1-5]/6) ([-+] [xyz] ([-+][xyz])? )?),([-+]? [xyz] ([-+][xyz])? ([-+] (1/2|[12]/3|[1-3]/4|[1-5]/6) )?|[-+]? (1/2|[12]/3|[1-3]/4|[1-5]/6) ([-+] [xyz] ([-+][xyz])? )?),([-+]? [xyz] ([-+][xyz])? ([-+] (1/2|[12]/3|[1-3]/4|[1-5]/6) )?|[-+]? (1/2|[12]/3|[1-3]/4|[1-5]/6) ([-+] [xyz] ([-+][xyz])? )?)$" + "pattern": "^([-+]?[xyz]([-+][xyz])?([-+](1/2|[12]/3|[1-3]/4|[1-5]/6))?|[-+]?(1/2|[12]/3|[1-3]/4|[1-5]/6)([-+][xyz]([-+][xyz])?)?),([-+]?[xyz]([-+][xyz])?([-+](1/2|[12]/3|[1-3]/4|[1-5]/6))?|[-+]?(1/2|[12]/3|[1-3]/4|[1-5]/6)([-+][xyz]([-+][xyz])?)?),([-+]?[xyz]([-+][xyz])?([-+](1/2|[12]/3|[1-3]/4|[1-5]/6))?|[-+]?(1/2|[12]/3|[1-3]/4|[1-5]/6)([-+][xyz]([-+][xyz])?)?)$" }, "type": "array", "title": "Space Group Symmetry Operations Xyz", "description": "A list of symmetry operations given as general position x, y and z coordinates in algebraic form.\n\nEach symmetry operation is described by a string that gives that symmetry operation in Jones' faithful representation (Bradley & Cracknell, 1972: pp. 35-37), adapted for computer string notation.\nThe letters x, y and z that are typesetted with overbars in printed text represent coordinate values multiplied by -1 and are encoded as -x, -y and -z, respectively.\nThe syntax of the strings representing symmetry operations MUST conform to regular expressions given in appendix The Symmetry Operation String Regular Expressions.\nThe interpretation of the strings MUST follow the conventions of the IUCr CIF core dictionary (IUCr, 2023).\nIn particular, this property MUST explicitly provide all symmetry operations needed to generate all the atoms in the unit cell from the atoms in the asymmetric unit, for the setting used.\nThis symmetry operation set MUST always include the `\"x,y,z\"` identity operation.\nThe symmetry operations are to be applied to fractional atom coordinates.\nIn case only Cartesian coordinates are available, these Cartesian coordinates must be converted to fractional coordinates before the application of the provided symmetry operations.\nIf the symmetry operation list is present, it MUST be compatible with other space group specifications (e.g. the ITC space group number, the Hall symbol, the Hermann-Mauguin symbol) if these are present.\n\n- **Type**: list of strings\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n However, the property is RECOMMENDED if coordinates are returned in a form to which these operations can or must be applied (e.g. fractional atom coordinates of an asymmetric unit).\n Moreover, the property is REQUIRED if symmetry operations are necessary to reconstruct the full model of the material and no other symmetry information (e.g., the Hall symbol) is provided that would allow the user to derive symmetry operations unambiguously.\n - MUST be null if `nperiodic_dimensions` is equal to 0.\n\n- **Examples**:\n - Space group operations for the space group with ITC number 3 (H-M symbol: P 2, extended H-M symbol: P 1 2 1, Hall symbol P 2y):\n ```\n [\"x,y,z\", \"-x,y,-z\"]\n ```\n - Space group operations for the space group with ITC number 5 (H-M symbol C 2, extended H-M symbol: C 1 2 1, Hall symbol C 2y):\n ```\n [\"x,y,z\", \"-x,y,-z\", \"x+1/2,y+1/2,z\", \"-x+1/2,y+1/2,-z\"]\n ```\n\n- **Notes**:\n The list of space group symmetry operations applies to the whole periodic array of atoms and together with the lattice translations given in the `lattice_vectors` property provides the necessary information to reconstruct all atom site positions of the periodic material.\n Thus, the symmetry operations described in this property are only applicable to material models with at least one periodic dimension.\n This property is not meant to represent arbitrary symmetries of molecules, non-periodic (finite) collections of atoms or non-crystallographic symmetry.\n\n- **Bibliographic References**:\n\n Bradley, C. J. and Cracknell, A. P. (1972) The Mathematical Theory of Symmetry in Solids. Oxford, Clarendon Press (paperback edition 2010) 745 p. ISBN 978-0-19-958258-7.\n\n IUCr (2023) Core dictionary (coreCIF) version 2.4.5; data name _space_group_symop_operation_xyz. Available from: https://www.iucr.org/__data/iucr/cifdic_html/1/cif_core.dic/Ispace_group_symop_operation_xyz.html [Accessed 2023-06-18T16:46+03:00].", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "space_group_hall": { "type": "string", "title": "Space Group Hall", "description": "A Hall space group symbol representing the symmetry of the structure as defined in (Hall, 1981, 1981a).\nThe change-of-basis operations are used as defined in the International Tables of Crystallography (ITC) Vol. B, Sect. 1.4, Appendix A1.4.2 (IUCr, 2001).\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - Each component of the Hall symbol MUST be separated by a single space symbol.\n - If there exists a standard Hall symbol which represents the symmetry it SHOULD be used.\n - MUST be null if `nperiodic_dimensions` is not equal to 3.\n\n- **Bibliographic References**:\n\n Hall, S. R. (1981) Space-group notation with an explicit origin. Acta Crystallographica Section A, 37, 517-525, International Union of Crystallography (IUCr), DOI: https://doi.org/10.1107/s0567739481001228\n\n Hall, S. R. (1981a) Space-group notation with an explicit origin; erratum. Acta Crystallographica Section A, 37, 921-921, International Union of Crystallography (IUCr), DOI: https://doi.org/10.1107/s0567739481001976\n\n IUCr (2001). International Tables for Crystallography vol. B. Reciprocal Space. Ed. U. Shmueli. 2-nd edition. Dordrecht/Boston/London, Kluwer Academic Publishers.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "space_group_symbol_hermann_mauguin": { "type": "string", "title": "Space Group Symbol Hermann Mauguin", "description": "A human- and machine-readable string containing the short Hermann-Mauguin (H-M) symbol which specifies the space group of the structure in the response.\nThe H-M symbol SHOULD aim to convey the closest representation of the symmetry information that can be specified using the short format used in the International Tables for Crystallography vol. A (IUCr, 2005), Table 4.3.2.1 as described in the accompanying text.\nThe symbol MAY be a non-standard short H-M symbol.\nThe H-M symbol does not unambiguously communicate the axis, cell, and origin choice, and the given symbol SHOULD NOT be amended to convey this information.\n\nTo encode as character strings, the following adaptations MUST be made when representing H-M symbols given in their typesetted form:\n - the overbar above the numbers MUST be changed to the minus sign in front of the digit (e.g. '-2');\n - subscripts that denote screw axes are written as digits immediately after the axis designator without a space (e.g. 'P 32')\n - the space group generators MUST be separated by a single space (e.g. 'P 21 21 2');\n - there MUST be no spaces in the space group generator designation (i.e. use 'P 21/m', not the 'P 21 / m');\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n\n- **Examples**:\n - `C 2`\n - `P 21 21 21`\n\n- **Bibliographic References**:\n\nIUCr (2005). International Tables for Crystallography vol. A. Space-Group Symmetry. Ed. Theo Hahn. 5-th edition. Dordrecht, Springer.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "space_group_it_number": { "type": "integer", @@ -3643,8 +3643,8 @@ "minimum": 1.0, "title": "Space Group It Number", "description": "Space group number for the structure assigned by the International Tables for Crystallography Vol. A.\n- **Type**: integer\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - The integer value MUST be between 1 and 230.\n - MUST be null if `nperiodic_dimensions` is not equal to 3.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "cartesian_site_positions": { "items": { @@ -3658,18 +3658,18 @@ "type": "array", "title": "Cartesian Site Positions", "description": "Cartesian positions of each site in the structure.\nA site is usually used to describe positions of atoms; what atoms can be encountered at a given site is conveyed by the `species_at_sites` property, and the species themselves are described in the `species` property.\n\n- **Type**: list of list of floats\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - It MUST be a list of length equal to the number of sites in the structure, where every element is a list of the three Cartesian coordinates of a site expressed as float values in the unit angstrom (\u00c5).\n - An entry MAY have multiple sites at the same Cartesian position (for a relevant use of this, see e.g., the property `assemblies`).\n\n- **Examples**:\n - `[[0,0,0],[0,0,2]]` indicates a structure with two sites, one sitting at the origin and one along the (positive) *z*-axis, 2 \u00c5 away from the origin.", - "x-optimade-support": "should", "x-optimade-queryable": "optional", - "x-optimade-unit": "\u00c5", - "nullable": true + "x-optimade-support": "should", + "nullable": true, + "x-optimade-unit": "\u00c5" }, "nsites": { "type": "integer", "title": "Nsites", "description": "An integer specifying the length of the `cartesian_site_positions` property.\n\n- **Type**: integer\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `42`\n\n- **Query examples**:\n - Match only structures with exactly 4 sites: `nsites=4`\n - Match structures that have between 2 and 7 sites: `nsites>=2 AND nsites<=7`", - "nullable": true, + "x-optimade-queryable": "must", "x-optimade-support": "should", - "x-optimade-queryable": "must" + "nullable": true }, "species": { "items": { @@ -3678,9 +3678,9 @@ "type": "array", "title": "Species", "description": "A list describing the species of the sites of this structure.\nSpecies can represent pure chemical elements, virtual-crystal atoms representing a statistical occupation of a given site by multiple chemical elements, and/or a location to which there are attached atoms, i.e., atoms whose precise location are unknown beyond that they are attached to that position (frequently used to indicate hydrogen atoms attached to another element, e.g., a carbon with three attached hydrogens might represent a methyl group, -CH3).\n\n- **Type**: list of dictionary with keys:\n - `name`: string (REQUIRED)\n - `chemical_symbols`: list of strings (REQUIRED)\n - `concentration`: list of float (REQUIRED)\n - `attached`: list of strings (REQUIRED)\n - `nattached`: list of integers (OPTIONAL)\n - `mass`: list of floats (OPTIONAL)\n - `original_name`: string (OPTIONAL).\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - Each list member MUST be a dictionary with the following keys:\n - **name**: REQUIRED; gives the name of the species; the **name** value MUST be unique in the `species` list;\n - **chemical_symbols**: REQUIRED; MUST be a list of strings of all chemical elements composing this species.\n Each item of the list MUST be one of the following:\n - a valid chemical-element symbol, or\n - the special value `\"X\"` to represent a non-chemical element, or\n - the special value `\"vacancy\"` to represent that this site has a non-zero probability of having a vacancy (the respective probability is indicated in the `concentration` list, see below).\n\n If any one entry in the `species` list has a `chemical_symbols` list that is longer than 1 element, the correct flag MUST be set in the list `structure_features`.\n\n - **concentration**: REQUIRED; MUST be a list of floats, with same length as `chemical_symbols`.\n The numbers represent the relative concentration of the corresponding chemical symbol in this species.\n The numbers SHOULD sum to one. Cases in which the numbers do not sum to one typically fall only in the following two categories:\n\n - Numerical errors when representing float numbers in fixed precision, e.g. for two chemical symbols with concentrations `1/3` and `2/3`, the concentration might look something like `[0.33333333333, 0.66666666666]`. If the client is aware that the sum is not one because of numerical precision, it can renormalize the values so that the sum is exactly one.\n - Experimental errors in the data present in the database. In this case, it is the responsibility of the client to decide how to process the data.\n\n Note that concentrations are uncorrelated between different sites (even of the same species).\n\n - **attached**: OPTIONAL; if provided MUST be a list of length 1 or more of strings of chemical symbols for the elements attached to this site, or \"X\" for a non-chemical element.\n\n - **nattached**: OPTIONAL; if provided MUST be a list of length 1 or more of integers indicating the number of attached atoms of the kind specified in the value of the `attached` key.\n\n The implementation MUST include either both or none of the `attached` and `nattached` keys, and if they are provided, they MUST be of the same length.\n Furthermore, if they are provided, the `structure_features` property MUST include the string `site_attachments`.\n\n - **mass**: OPTIONAL. If present MUST be a list of floats, with the same length as `chemical_symbols`, providing element masses expressed in a.m.u.\n Elements denoting vacancies MUST have masses equal to 0.\n\n - **original_name**: OPTIONAL. Can be any valid Unicode string, and SHOULD contain (if specified) the name of the species that is used internally in the source database.\n\n Note: With regards to \"source database\", we refer to the immediate source being queried via the OPTIMADE API implementation.\n\n The main use of this field is for source databases that use species names, containing characters that are not allowed (see description of the list property `species_at_sites`).\n\n - For systems that have only species formed by a single chemical symbol, and that have at most one species per chemical symbol, SHOULD use the chemical symbol as species name (e.g., `\"Ti\"` for titanium, `\"O\"` for oxygen, etc.)\n However, note that this is OPTIONAL, and client implementations MUST NOT assume that the key corresponds to a chemical symbol, nor assume that if the species name is a valid chemical symbol, that it represents a species with that chemical symbol.\n This means that a species `{\"name\": \"C\", \"chemical_symbols\": [\"Ti\"], \"concentration\": [1.0]}` is valid and represents a titanium species (and *not* a carbon species).\n - It is NOT RECOMMENDED that a structure includes species that do not have at least one corresponding site.\n\n- **Examples**:\n - `[ {\"name\": \"Ti\", \"chemical_symbols\": [\"Ti\"], \"concentration\": [1.0]} ]`: any site with this species is occupied by a Ti atom.\n - `[ {\"name\": \"Ti\", \"chemical_symbols\": [\"Ti\", \"vacancy\"], \"concentration\": [0.9, 0.1]} ]`: any site with this species is occupied by a Ti atom with 90 % probability, and has a vacancy with 10 % probability.\n - `[ {\"name\": \"BaCa\", \"chemical_symbols\": [\"vacancy\", \"Ba\", \"Ca\"], \"concentration\": [0.05, 0.45, 0.5], \"mass\": [0.0, 137.327, 40.078]} ]`: any site with this species is occupied by a Ba atom with 45 % probability, a Ca atom with 50 % probability, and by a vacancy with 5 % probability. The mass of this site is (on average) 88.5 a.m.u.\n - `[ {\"name\": \"C12\", \"chemical_symbols\": [\"C\"], \"concentration\": [1.0], \"mass\": [12.0]} ]`: any site with this species is occupied by a carbon isotope with mass 12.\n - `[ {\"name\": \"C13\", \"chemical_symbols\": [\"C\"], \"concentration\": [1.0], \"mass\": [13.0]} ]`: any site with this species is occupied by a carbon isotope with mass 13.\n - `[ {\"name\": \"CH3\", \"chemical_symbols\": [\"C\"], \"concentration\": [1.0], \"attached\": [\"H\"], \"nattached\": [3]} ]`: any site with this species is occupied by a methyl group, -CH3, which is represented without specifying precise positions of the hydrogen atoms.", - "nullable": true, + "x-optimade-queryable": "optional", "x-optimade-support": "should", - "x-optimade-queryable": "optional" + "nullable": true }, "species_at_sites": { "items": { @@ -3689,9 +3689,9 @@ "type": "array", "title": "Species At Sites", "description": "Name of the species at each site (where values for sites are specified with the same order of the property `cartesian_site_positions`).\nThe properties of the species are found in the property `species`.\n\n- **Type**: list of strings.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - MUST have length equal to the number of sites in the structure (first dimension of the list property `cartesian_site_positions`).\n - Each species name mentioned in the `species_at_sites` list MUST be described in the list property `species` (i.e. for each value in the `species_at_sites` list there MUST exist exactly one dictionary in the `species` list with the `name` attribute equal to the corresponding `species_at_sites` value).\n - Each site MUST be associated only to a single species.\n **Note**: However, species can represent mixtures of atoms, and multiple species MAY be defined for the same chemical element.\n This latter case is useful when different atoms of the same type need to be grouped or distinguished, for instance in simulation codes to assign different initial spin states.\n\n- **Examples**:\n - `[\"Ti\",\"O2\"]` indicates that the first site is hosting a species labeled `\"Ti\"` and the second a species labeled `\"O2\"`.\n - `[\"Ac\", \"Ac\", \"Ag\", \"Ir\"]` indicating the first two sites contains the `\"Ac\"` species, while the third and fourth sites contain the `\"Ag\"` and `\"Ir\"` species, respectively.", - "nullable": true, + "x-optimade-queryable": "optional", "x-optimade-support": "should", - "x-optimade-queryable": "optional" + "nullable": true }, "assemblies": { "items": { @@ -3700,8 +3700,8 @@ "type": "array", "title": "Assemblies", "description": "A description of groups of sites that are statistically correlated.\n\n- **Type**: list of dictionary with keys:\n - `sites_in_groups`: list of list of integers (REQUIRED)\n - `group_probabilities`: list of floats (REQUIRED)\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - The property SHOULD be `null` for entries that have no partial occupancies.\n - If present, the correct flag MUST be set in the list `structure_features`.\n - Client implementations MUST check its presence (as its presence changes the interpretation of the structure).\n - If present, it MUST be a list of dictionaries, each of which represents an assembly and MUST have the following two keys:\n - **sites_in_groups**: Index of the sites (0-based) that belong to each group for each assembly.\n\n Example: `[[1], [2]]`: two groups, one with the second site, one with the third.\n Example: `[[1,2], [3]]`: one group with the second and third site, one with the fourth.\n\n - **group_probabilities**: Statistical probability of each group. It MUST have the same length as `sites_in_groups`.\n It SHOULD sum to one.\n See below for examples of how to specify the probability of the occurrence of a vacancy.\n The possible reasons for the values not to sum to one are the same as already specified above for the `concentration` of each `species`.\n\n - If a site is not present in any group, it means that it is present with 100 % probability (as if no assembly was specified).\n - A site MUST NOT appear in more than one group.\n\n- **Examples** (for each entry of the assemblies list):\n - `{\"sites_in_groups\": [[0], [1]], \"group_probabilities: [0.3, 0.7]}`: the first site and the second site never occur at the same time in the unit cell.\n Statistically, 30 % of the times the first site is present, while 70 % of the times the second site is present.\n - `{\"sites_in_groups\": [[1,2], [3]], \"group_probabilities: [0.3, 0.7]}`: the second and third site are either present together or not present; they form the first group of atoms for this assembly.\n The second group is formed by the fourth site.\n Sites of the first group (the second and the third) are never present at the same time as the fourth site.\n 30 % of times sites 1 and 2 are present (and site 3 is absent); 70 % of times site 3 is present (and sites 1 and 2 are absent).\n\n- **Notes**:\n - Assemblies are essential to represent, for instance, the situation where an atom can statistically occupy two different positions (sites).\n\n - By defining groups, it is possible to represent, e.g., the case where a functional molecule (and not just one atom) is either present or absent (or the case where it it is present in two conformations)\n\n - Considerations on virtual alloys and on vacancies: In the special case of a virtual alloy, these specifications allow two different, equivalent ways of specifying them.\n For instance, for a site at the origin with 30 % probability of being occupied by Si, 50 % probability of being occupied by Ge, and 20 % of being a vacancy, the following two representations are possible:\n\n - Using a single species:\n ```json\n {\n \"cartesian_site_positions\": [[0,0,0]],\n \"species_at_sites\": [\"SiGe-vac\"],\n \"species\": [\n {\n \"name\": \"SiGe-vac\",\n \"chemical_symbols\": [\"Si\", \"Ge\", \"vacancy\"],\n \"concentration\": [0.3, 0.5, 0.2]\n }\n ]\n // ...\n }\n ```\n\n - Using multiple species and the assemblies:\n ```json\n {\n \"cartesian_site_positions\": [ [0,0,0], [0,0,0], [0,0,0] ],\n \"species_at_sites\": [\"Si\", \"Ge\", \"vac\"],\n \"species\": [\n { \"name\": \"Si\", \"chemical_symbols\": [\"Si\"], \"concentration\": [1.0] },\n { \"name\": \"Ge\", \"chemical_symbols\": [\"Ge\"], \"concentration\": [1.0] },\n { \"name\": \"vac\", \"chemical_symbols\": [\"vacancy\"], \"concentration\": [1.0] }\n ],\n \"assemblies\": [\n {\n \"sites_in_groups\": [ [0], [1], [2] ],\n \"group_probabilities\": [0.3, 0.5, 0.2]\n }\n ]\n // ...\n }\n ```\n\n - It is up to the database provider to decide which representation to use, typically depending on the internal format in which the structure is stored.\n However, given a structure identified by a unique ID, the API implementation MUST always provide the same representation for it.\n\n - The probabilities of occurrence of different assemblies are uncorrelated.\n So, for instance in the following case with two assemblies:\n ```json\n {\n \"assemblies\": [\n {\n \"sites_in_groups\": [ [0], [1] ],\n \"group_probabilities\": [0.2, 0.8],\n },\n {\n \"sites_in_groups\": [ [2], [3] ],\n \"group_probabilities\": [0.3, 0.7]\n }\n ]\n }\n ```\n\n Site 0 is present with a probability of 20 % and site 1 with a probability of 80 %. These two sites are correlated (either site 0 or 1 is present). Similarly, site 2 is present with a probability of 30 % and site 3 with a probability of 70 %.\n These two sites are correlated (either site 2 or 3 is present).\n However, the presence or absence of sites 0 and 1 is not correlated with the presence or absence of sites 2 and 3 (in the specific example, the pair of sites (0, 2) can occur with 0.2*0.3 = 6 % probability; the pair (0, 3) with 0.2*0.7 = 14 % probability; the pair (1, 2) with 0.8*0.3 = 24 % probability; and the pair (1, 3) with 0.8*0.7 = 56 % probability).", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "structure_features": { "items": { @@ -3710,8 +3710,8 @@ "type": "array", "title": "Structure Features", "description": "A list of strings that flag which special features are used by the structure.\n\n- **Type**: list of strings\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property.\n Filters on the list MUST support all mandatory HAS-type queries.\n Filter operators for comparisons on the string components MUST support equality, support for other comparison operators are OPTIONAL.\n - MUST be an empty list if no special features are used.\n - MUST be sorted alphabetically.\n - If a special feature listed below is used, the list MUST contain the corresponding string.\n - If a special feature listed below is not used, the list MUST NOT contain the corresponding string.\n - **List of strings used to indicate special structure features**:\n - `disorder`: this flag MUST be present if any one entry in the `species` list has a `chemical_symbols` list that is longer than 1 element.\n - `implicit_atoms`: this flag MUST be present if the structure contains atoms that are not assigned to sites via the property `species_at_sites` (e.g., because their positions are unknown).\n When this flag is present, the properties related to the chemical formula will likely not match the type and count of atoms represented by the `species_at_sites`, `species` and `assemblies` properties.\n - `site_attachments`: this flag MUST be present if any one entry in the `species` list includes `attached` and `nattached`.\n - `assemblies`: this flag MUST be present if the property `assemblies` is present.\n\n- **Examples**: A structure having implicit atoms and using assemblies: `[\"assemblies\", \"implicit_atoms\"]`", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" } }, "type": "object", diff --git a/optimade/models/utils.py b/optimade/models/utils.py index cc15d5758..b88240ec7 100644 --- a/optimade/models/utils.py +++ b/optimade/models/utils.py @@ -422,5 +422,5 @@ def reduce_formula(formula: str) -> str: translation = "1/2|[12]/3|[1-3]/4|[1-5]/6" translation_appended = f"[-+]? [xyz] ([-+][xyz])? ([-+] ({translation}) )?" translation_prepended = f"[-+]? ({translation}) ([-+] [xyz] ([-+][xyz])? )?" -symop = f"({translation_appended}|{translation_prepended})" +symop = f"({translation_appended}|{translation_prepended})".replace(" ", "") SPACE_GROUP_SYMMETRY_OPERATION_REGEX = f"^{symop},{symop},{symop}$" From fb581b8201fa092f6e8716090e14396eb60858a5 Mon Sep 17 00:00:00 2001 From: Matthew Evans Date: Thu, 4 Jan 2024 12:30:34 +0000 Subject: [PATCH 18/19] Fix outstanding discrepancies with specification --- openapi/openapi.json | 81 +++++++++++++++++++---------------- optimade/models/structures.py | 81 ++++++++++++++++++++++++----------- 2 files changed, 101 insertions(+), 61 deletions(-) diff --git a/openapi/openapi.json b/openapi/openapi.json index 7a61435bd..821cb078b 100644 --- a/openapi/openapi.json +++ b/openapi/openapi.json @@ -2735,8 +2735,8 @@ "format": "uri", "title": "Url", "description": "The URL of the reference.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "address": { "type": "string", @@ -3341,8 +3341,8 @@ "title": "Mass", "description": "If present MUST be a list of floats expressed in a.m.u.\nElements denoting vacancies MUST have masses equal to 0.", "x-optimade-queryable": "optional", - "x-optimade-unit": "a.m.u.", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-unit": "a.m.u." }, "original_name": { "type": "string", @@ -3504,9 +3504,9 @@ "format": "date-time", "title": "Last Modified", "description": "Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n - As part of JSON response format: `\"2007-04-05T14:30:20Z\"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)", + "nullable": true, "x-optimade-queryable": "must", - "x-optimade-support": "should", - "nullable": true + "x-optimade-support": "should" }, "elements": { "items": { @@ -3515,17 +3515,17 @@ "type": "array", "title": "Elements", "description": "The chemical symbols of the different elements present in the structure.\n\n- **Type**: list of strings.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - The strings are the chemical symbols, i.e., either a single uppercase letter or an uppercase letter followed by a number of lowercase letters.\n - The order MUST be alphabetical.\n - MUST refer to the same elements in the same order, and therefore be of the same length, as `elements_ratios`, if the latter is provided.\n - Note: This property SHOULD NOT contain the string \"X\" to indicate non-chemical elements or \"vacancy\" to indicate vacancies (in contrast to the field `chemical_symbols` for the `species` property).\n\n- **Examples**:\n - `[\"Si\"]`\n - `[\"Al\",\"O\",\"Si\"]`\n\n- **Query examples**:\n - A filter that matches all records of structures that contain Si, Al **and** O, and possibly other elements: `elements HAS ALL \"Si\", \"Al\", \"O\"`.\n - To match structures with exactly these three elements, use `elements HAS ALL \"Si\", \"Al\", \"O\" AND elements LENGTH 3`.\n - Note: length queries on this property can be equivalently formulated by filtering on the `nelements`_ property directly.", + "nullable": true, "x-optimade-queryable": "must", - "x-optimade-support": "should", - "nullable": true + "x-optimade-support": "should" }, "nelements": { "type": "integer", "title": "Nelements", "description": "Number of different elements in the structure as an integer.\n\n- **Type**: integer\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - MUST be equal to the lengths of the list properties `elements` and `elements_ratios`, if they are provided.\n\n- **Examples**:\n - `3`\n\n- **Querying**:\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`.", + "nullable": true, "x-optimade-queryable": "must", - "x-optimade-support": "should", - "nullable": true + "x-optimade-support": "should" }, "elements_ratios": { "items": { @@ -3534,26 +3534,26 @@ "type": "array", "title": "Elements Ratios", "description": "Relative proportions of different elements in the structure.\n\n- **Type**: list of floats\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - Composed by the proportions of elements in the structure as a list of floating point numbers.\n - The sum of the numbers MUST be 1.0 (within floating point accuracy)\n - MUST refer to the same elements in the same order, and therefore be of the same length, as `elements`, if the latter is provided.\n\n- **Examples**:\n - `[1.0]`\n - `[0.3333333333333333, 0.2222222222222222, 0.4444444444444444]`\n\n- **Query examples**:\n - Note: Useful filters can be formulated using the set operator syntax for correlated values.\n However, since the values are floating point values, the use of equality comparisons is generally inadvisable.\n - OPTIONAL: a filter that matches structures where approximately 1/3 of the atoms in the structure are the element Al is: `elements:elements_ratios HAS ALL \"Al\":>0.3333, \"Al\":<0.3334`.", + "nullable": true, "x-optimade-queryable": "must", - "x-optimade-support": "should", - "nullable": true + "x-optimade-support": "should" }, "chemical_formula_descriptive": { "type": "string", "title": "Chemical Formula Descriptive", "description": "The chemical formula for a structure as a string in a form chosen by the API implementation.\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - The chemical formula is given as a string consisting of properly capitalized element symbols followed by integers or decimal numbers, balanced parentheses, square, and curly brackets `(`,`)`, `[`,`]`, `{`, `}`, commas, the `+`, `-`, `:` and `=` symbols. The parentheses are allowed to be followed by a number. Spaces are allowed anywhere except within chemical symbols. The order of elements and any groupings indicated by parentheses or brackets are chosen freely by the API implementation.\n - The string SHOULD be arithmetically consistent with the element ratios in the `chemical_formula_reduced` property.\n - It is RECOMMENDED, but not mandatory, that symbols, parentheses and brackets, if used, are used with the meanings prescribed by [IUPAC's Nomenclature of Organic Chemistry](https://www.qmul.ac.uk/sbcs/iupac/bibliog/blue.html).\n\n- **Examples**:\n - `\"(H2O)2 Na\"`\n - `\"NaCl\"`\n - `\"CaCO3\"`\n - `\"CCaO3\"`\n - `\"(CH3)3N+ - [CH2]2-OH = Me3N+ - CH2 - CH2OH\"`\n\n- **Query examples**:\n - Note: the free-form nature of this property is likely to make queries on it across different databases inconsistent.\n - A filter that matches an exactly given formula: `chemical_formula_descriptive=\"(H2O)2 Na\"`.\n - A filter that does a partial match: `chemical_formula_descriptive CONTAINS \"H2O\"`.", + "nullable": true, "x-optimade-queryable": "must", - "x-optimade-support": "should", - "nullable": true + "x-optimade-support": "should" }, "chemical_formula_reduced": { "type": "string", "pattern": "(^$)|^([A-Z][a-z]?([2-9]|[1-9]\\d+)?)+$", "title": "Chemical Formula Reduced", "description": "The reduced chemical formula for a structure as a string with element symbols and integer chemical proportion numbers.\nThe proportion number MUST be omitted if it is 1.\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property.\n However, support for filters using partial string matching with this property is OPTIONAL (i.e., BEGINS WITH, ENDS WITH, and CONTAINS).\n Intricate queries on formula components are instead suggested to be formulated using set-type filter operators on the multi valued `elements` and `elements_ratios` properties.\n - Element symbols MUST have proper capitalization (e.g., `\"Si\"`, not `\"SI\"` for \"silicon\").\n - Elements MUST be placed in alphabetical order, followed by their integer chemical proportion number.\n - For structures with no partial occupation, the chemical proportion numbers are the smallest integers for which the chemical proportion is exactly correct.\n - For structures with partial occupation, the chemical proportion numbers are integers that within reasonable approximation indicate the correct chemical proportions. The precise details of how to perform the rounding is chosen by the API implementation.\n - No spaces or separators are allowed.\n\n- **Examples**:\n - `\"H2NaO\"`\n - `\"ClNa\"`\n - `\"CCaO3\"`\n\n- **Query examples**:\n - A filter that matches an exactly given formula is `chemical_formula_reduced=\"H2NaO\"`.", + "nullable": true, "x-optimade-queryable": "must", - "x-optimade-support": "should", - "nullable": true + "x-optimade-support": "should" }, "chemical_formula_hill": { "type": "string", @@ -3568,9 +3568,9 @@ "pattern": "(^$)|^([A-Z][a-z]?([2-9]|[1-9]\\d+)?)+$", "title": "Chemical Formula Anonymous", "description": "The anonymous formula is the `chemical_formula_reduced`, but where the elements are instead first ordered by their chemical proportion number, and then, in order left to right, replaced by anonymous symbols A, B, C, ..., Z, Aa, Ba, ..., Za, Ab, Bb, ... and so on.\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property.\n However, support for filters using partial string matching with this property is OPTIONAL (i.e., BEGINS WITH, ENDS WITH, and CONTAINS).\n\n- **Examples**:\n - `\"A2B\"`\n - `\"A42B42C16D12E10F9G5\"`\n\n- **Querying**:\n - A filter that matches an exactly given formula is `chemical_formula_anonymous=\"A2B\"`.", + "nullable": true, "x-optimade-queryable": "must", - "x-optimade-support": "should", - "nullable": true + "x-optimade-support": "should" }, "dimension_types": { "items": { @@ -3581,17 +3581,17 @@ "minItems": 3, "title": "Dimension Types", "description": "List of three integers.\nFor each of the three directions indicated by the three lattice vectors (see property `lattice_vectors`), this list indicates if the direction is periodic (value `1`) or non-periodic (value `0`).\nNote: the elements in this list each refer to the direction of the corresponding entry in `lattice_vectors` and *not* the Cartesian x, y, z directions.\n\n- **Type**: list of integers.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - MUST be a list of length 3.\n - Each integer element MUST assume only the value 0 or 1.\n\n- **Examples**:\n - For a molecule: `[0, 0, 0]`\n - For a wire along the direction specified by the third lattice vector: `[0, 0, 1]`\n - For a 2D surface/slab, periodic on the plane defined by the first and third lattice vectors: `[1, 0, 1]`\n - For a bulk 3D system: `[1, 1, 1]`", - "x-optimade-queryable": "optional", "x-optimade-support": "should", - "nullable": true + "nullable": true, + "x-optimade-queryable": "optional" }, "nperiodic_dimensions": { "type": "integer", "title": "Nperiodic Dimensions", "description": "An integer specifying the number of periodic dimensions in the structure, equivalent to the number of non-zero entries in `dimension_types`.\n\n- **Type**: integer\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - The integer value MUST be between 0 and 3 inclusive and MUST be equal to the sum of the items in the `dimension_types` property.\n - This property only reflects the treatment of the lattice vectors provided for the structure, and not any physical interpretation of the dimensionality of its contents.\n\n- **Examples**:\n - `2` should be indicated in cases where `dimension_types` is any of `[1, 1, 0]`, `[1, 0, 1]`, `[0, 1, 1]`.\n\n- **Query examples**:\n - Match only structures with exactly 3 periodic dimensions: `nperiodic_dimensions=3`\n - Match all structures with 2 or fewer periodic dimensions: `nperiodic_dimensions<=2`", + "nullable": true, "x-optimade-queryable": "must", - "x-optimade-support": "should", - "nullable": true + "x-optimade-support": "should" }, "lattice_vectors": { "items": { @@ -3607,10 +3607,10 @@ "minItems": 3, "title": "Lattice Vectors", "description": "The three lattice vectors in Cartesian coordinates, in \u00e5ngstr\u00f6m (\u00c5).\n\n- **Type**: list of list of floats or unknown values.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - MUST be a list of three vectors *a*, *b*, and *c*, where each of the vectors MUST BE a list of the vector's coordinates along the x, y, and z Cartesian coordinates.\n (Therefore, the first index runs over the three lattice vectors and the second index runs over the x, y, z Cartesian coordinates).\n - For databases that do not define an absolute Cartesian system (e.g., only defining the length and angles between vectors), the first lattice vector SHOULD be set along *x* and the second on the *xy*-plane.\n - MUST always contain three vectors of three coordinates each, independently of the elements of property `dimension_types`.\n The vectors SHOULD by convention be chosen so the determinant of the `lattice_vectors` matrix is different from zero.\n The vectors in the non-periodic directions have no significance beyond fulfilling these requirements.\n - The coordinates of the lattice vectors of non-periodic dimensions (i.e., those dimensions for which `dimension_types` is `0`) MAY be given as a list of all `null` values.\n If a lattice vector contains the value `null`, all coordinates of that lattice vector MUST be `null`.\n\n- **Examples**:\n - `[[4.0,0.0,0.0],[0.0,4.0,0.0],[0.0,1.0,4.0]]` represents a cell, where the first vector is `(4, 0, 0)`, i.e., a vector aligned along the `x` axis of length 4 \u00c5; the second vector is `(0, 4, 0)`; and the third vector is `(0, 1, 4)`.", - "x-optimade-queryable": "optional", "x-optimade-support": "should", + "x-optimade-unit": "\u00c5", "nullable": true, - "x-optimade-unit": "\u00c5" + "x-optimade-queryable": "optional" }, "space_group_symmetry_operations_xyz": { "items": { @@ -3619,21 +3619,28 @@ }, "type": "array", "title": "Space Group Symmetry Operations Xyz", - "description": "A list of symmetry operations given as general position x, y and z coordinates in algebraic form.\n\nEach symmetry operation is described by a string that gives that symmetry operation in Jones' faithful representation (Bradley & Cracknell, 1972: pp. 35-37), adapted for computer string notation.\nThe letters x, y and z that are typesetted with overbars in printed text represent coordinate values multiplied by -1 and are encoded as -x, -y and -z, respectively.\nThe syntax of the strings representing symmetry operations MUST conform to regular expressions given in appendix The Symmetry Operation String Regular Expressions.\nThe interpretation of the strings MUST follow the conventions of the IUCr CIF core dictionary (IUCr, 2023).\nIn particular, this property MUST explicitly provide all symmetry operations needed to generate all the atoms in the unit cell from the atoms in the asymmetric unit, for the setting used.\nThis symmetry operation set MUST always include the `\"x,y,z\"` identity operation.\nThe symmetry operations are to be applied to fractional atom coordinates.\nIn case only Cartesian coordinates are available, these Cartesian coordinates must be converted to fractional coordinates before the application of the provided symmetry operations.\nIf the symmetry operation list is present, it MUST be compatible with other space group specifications (e.g. the ITC space group number, the Hall symbol, the Hermann-Mauguin symbol) if these are present.\n\n- **Type**: list of strings\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n However, the property is RECOMMENDED if coordinates are returned in a form to which these operations can or must be applied (e.g. fractional atom coordinates of an asymmetric unit).\n Moreover, the property is REQUIRED if symmetry operations are necessary to reconstruct the full model of the material and no other symmetry information (e.g., the Hall symbol) is provided that would allow the user to derive symmetry operations unambiguously.\n - MUST be null if `nperiodic_dimensions` is equal to 0.\n\n- **Examples**:\n - Space group operations for the space group with ITC number 3 (H-M symbol: P 2, extended H-M symbol: P 1 2 1, Hall symbol P 2y):\n ```\n [\"x,y,z\", \"-x,y,-z\"]\n ```\n - Space group operations for the space group with ITC number 5 (H-M symbol C 2, extended H-M symbol: C 1 2 1, Hall symbol C 2y):\n ```\n [\"x,y,z\", \"-x,y,-z\", \"x+1/2,y+1/2,z\", \"-x+1/2,y+1/2,-z\"]\n ```\n\n- **Notes**:\n The list of space group symmetry operations applies to the whole periodic array of atoms and together with the lattice translations given in the `lattice_vectors` property provides the necessary information to reconstruct all atom site positions of the periodic material.\n Thus, the symmetry operations described in this property are only applicable to material models with at least one periodic dimension.\n This property is not meant to represent arbitrary symmetries of molecules, non-periodic (finite) collections of atoms or non-crystallographic symmetry.\n\n- **Bibliographic References**:\n\n Bradley, C. J. and Cracknell, A. P. (1972) The Mathematical Theory of Symmetry in Solids. Oxford, Clarendon Press (paperback edition 2010) 745 p. ISBN 978-0-19-958258-7.\n\n IUCr (2023) Core dictionary (coreCIF) version 2.4.5; data name _space_group_symop_operation_xyz. Available from: https://www.iucr.org/__data/iucr/cifdic_html/1/cif_core.dic/Ispace_group_symop_operation_xyz.html [Accessed 2023-06-18T16:46+03:00].", + "description": "A list of symmetry operations given as general position x, y and z coordinates in algebraic form.\n\nEach symmetry operation is described by a string that gives that symmetry operation in Jones' faithful representation (Bradley & Cracknell, 1972: pp. 35-37), adapted for computer string notation.\nThe letters x, y and z that are typesetted with overbars in printed text represent coordinate values multiplied by -1 and are encoded as -x, -y and -z, respectively.\nThe syntax of the strings representing symmetry operations MUST conform to regular expressions given in appendix The Symmetry Operation String Regular Expressions.\nThe interpretation of the strings MUST follow the conventions of the IUCr CIF core dictionary (IUCr, 2023).\nIn particular, this property MUST explicitly provide all symmetry operations needed to generate all the atoms in the unit cell from the atoms in the asymmetric unit, for the setting used.\nThis symmetry operation set MUST always include the `\"x,y,z\"` identity operation.\nThe symmetry operations are to be applied to fractional atom coordinates.\nIn case only Cartesian coordinates are available, these Cartesian coordinates must be converted to fractional coordinates before the application of the provided symmetry operations.\nIf the symmetry operation list is present, it MUST be compatible with other space group specifications (e.g. the ITC space group number, the Hall symbol, the Hermann-Mauguin symbol) if these are present.\n\n- **Type**: list of strings\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n\n - The property is RECOMMENDED if coordinates are returned in a form to which these operations can or must be applied (e.g. fractional atom coordinates of an asymmetric unit).\n - The property is REQUIRED if symmetry operations are necessary to reconstruct the full model of the material and no other symmetry information (e.g., the Hall symbol) is provided that would allow the user to derive symmetry operations unambiguously.\n - MUST be null if `nperiodic_dimensions` is equal to 0.\n\n- **Examples**:\n\n - Space group operations for the space group with ITC number 3 (H-M symbol `P 2`, extended H-M symbol `P 1 2 1`, Hall symbol `P 2y`): `[\"x,y,z\", \"-x,y,-z\"]`\n - Space group operations for the space group with ITC number 5 (H-M symbol `C 2`, extended H-M symbol `C 1 2 1`, Hall symbol `C 2y`): `[\"x,y,z\", \"-x,y,-z\", \"x+1/2,y+1/2,z\", \"-x+1/2,y+1/2,-z\"]`\n\n- **Notes**:\n The list of space group symmetry operations applies to the whole periodic array of atoms and together with the lattice translations given in the `lattice_vectors` property provides the necessary information to reconstruct all atom site positions of the periodic material.\n Thus, the symmetry operations described in this property are only applicable to material models with at least one periodic dimension.\n This property is not meant to represent arbitrary symmetries of molecules, non-periodic (finite) collections of atoms or non-crystallographic symmetry.\n\n- **Bibliographic References**:\n\n Bradley, C. J. and Cracknell, A. P. (1972) The Mathematical Theory of Symmetry in Solids. Oxford, Clarendon Press (paperback edition 2010) 745 p. ISBN 978-0-19-958258-7.\n\n IUCr (2023) Core dictionary (coreCIF) version 2.4.5; data name _space_group_symop_operation_xyz. Available from: https://www.iucr.org/__data/iucr/cifdic_html/1/cif_core.dic/Ispace_group_symop_operation_xyz.html [Accessed 2023-06-18T16:46+03:00].", "x-optimade-queryable": "optional", "x-optimade-support": "optional" }, - "space_group_hall": { + "space_group_symbol_hall": { "type": "string", - "title": "Space Group Hall", - "description": "A Hall space group symbol representing the symmetry of the structure as defined in (Hall, 1981, 1981a).\nThe change-of-basis operations are used as defined in the International Tables of Crystallography (ITC) Vol. B, Sect. 1.4, Appendix A1.4.2 (IUCr, 2001).\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - Each component of the Hall symbol MUST be separated by a single space symbol.\n - If there exists a standard Hall symbol which represents the symmetry it SHOULD be used.\n - MUST be null if `nperiodic_dimensions` is not equal to 3.\n\n- **Bibliographic References**:\n\n Hall, S. R. (1981) Space-group notation with an explicit origin. Acta Crystallographica Section A, 37, 517-525, International Union of Crystallography (IUCr), DOI: https://doi.org/10.1107/s0567739481001228\n\n Hall, S. R. (1981a) Space-group notation with an explicit origin; erratum. Acta Crystallographica Section A, 37, 921-921, International Union of Crystallography (IUCr), DOI: https://doi.org/10.1107/s0567739481001976\n\n IUCr (2001). International Tables for Crystallography vol. B. Reciprocal Space. Ed. U. Shmueli. 2-nd edition. Dordrecht/Boston/London, Kluwer Academic Publishers.", + "title": "Space Group Symbol Hall", + "description": "A Hall space group symbol representing the symmetry of the structure as defined in (Hall, 1981, 1981a).\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - The change-of-basis operations are used as defined in the International Tables of Crystallography (ITC) Vol. B, Sect. 1.4, Appendix A1.4.2 (IUCr, 2001).\n - Each component of the Hall symbol MUST be separated by a single space symbol.\n - If there exists a standard Hall symbol which represents the symmetry it SHOULD be used.\n - MUST be null if `nperiodic_dimensions` is not equal to 3.\n\n- **Examples**:\n\n - Space group symbols with explicit origin (the Hall symbols):\n\n - `P 2c -2ac`\n - `-I 4bd 2ab 3`\n\n - Space group symbols with change-of-basis operations:\n\n - `P 2yb (-1/2*x+z,1/2*x,y)`\n - `-I 4 2 (1/2*x+1/2*y,-1/2*x+1/2*y,z)`\n\n- **Bibliographic References**:\n\n Hall, S. R. (1981) Space-group notation with an explicit origin. Acta Crystallographica Section A, 37, 517-525, International Union of Crystallography (IUCr), DOI: https://doi.org/10.1107/s0567739481001228\n\n Hall, S. R. (1981a) Space-group notation with an explicit origin; erratum. Acta Crystallographica Section A, 37, 921-921, International Union of Crystallography (IUCr), DOI: https://doi.org/10.1107/s0567739481001976\n\n IUCr (2001). International Tables for Crystallography vol. B. Reciprocal Space. Ed. U. Shmueli. 2-nd edition. Dordrecht/Boston/London, Kluwer Academic Publishers.", "x-optimade-queryable": "optional", "x-optimade-support": "optional" }, "space_group_symbol_hermann_mauguin": { "type": "string", "title": "Space Group Symbol Hermann Mauguin", - "description": "A human- and machine-readable string containing the short Hermann-Mauguin (H-M) symbol which specifies the space group of the structure in the response.\nThe H-M symbol SHOULD aim to convey the closest representation of the symmetry information that can be specified using the short format used in the International Tables for Crystallography vol. A (IUCr, 2005), Table 4.3.2.1 as described in the accompanying text.\nThe symbol MAY be a non-standard short H-M symbol.\nThe H-M symbol does not unambiguously communicate the axis, cell, and origin choice, and the given symbol SHOULD NOT be amended to convey this information.\n\nTo encode as character strings, the following adaptations MUST be made when representing H-M symbols given in their typesetted form:\n - the overbar above the numbers MUST be changed to the minus sign in front of the digit (e.g. '-2');\n - subscripts that denote screw axes are written as digits immediately after the axis designator without a space (e.g. 'P 32')\n - the space group generators MUST be separated by a single space (e.g. 'P 21 21 2');\n - there MUST be no spaces in the space group generator designation (i.e. use 'P 21/m', not the 'P 21 / m');\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n\n- **Examples**:\n - `C 2`\n - `P 21 21 21`\n\n- **Bibliographic References**:\n\nIUCr (2005). International Tables for Crystallography vol. A. Space-Group Symmetry. Ed. Theo Hahn. 5-th edition. Dordrecht, Springer.", + "description": "A human- and machine-readable string containing the short Hermann-Mauguin (H-M) symbol which specifies the space group of the structure in the response.\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - The H-M symbol SHOULD aim to convey the closest representation of the symmetry information that can be specified using the short format used in the International Tables for Crystallography vol. A (IUCr, 2005), Table 4.3.2.1 as described in the accompanying text.\n - The symbol MAY be a non-standard short H-M symbol.\n - The H-M symbol does not unambiguously communicate the axis, cell, and origin choice, and the given symbol SHOULD NOT be amended to convey this information.\n - To encode as character strings, the following adaptations MUST be made when representing H-M symbols given in their typesetted form:\n\n - the overbar above the numbers MUST be changed to the minus sign in front of the digit (e.g. '-2');\n - subscripts that denote screw axes are written as digits immediately after the axis designator without a space (e.g. 'P 32')\n - the space group generators MUST be separated by a single space (e.g. 'P 21 21 2');\n - there MUST be no spaces in the space group generator designation (i.e. use 'P 21/m', not the 'P 21 / m');\n\n- **Examples**:\n - `C 2`\n - `P 21 21 21`\n\n- **Bibliographic References**:\n\n IUCr (2005). International Tables for Crystallography vol. A. Space-Group Symmetry. Ed. Theo Hahn. 5-th edition. Dordrecht, Springer.", + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" + }, + "space_group_symbol_hermann_mauguin_extended": { + "type": "string", + "title": "Space Group Symbol Hermann Mauguin Extended", + "description": "A human- and machine-readable string containing the extended Hermann-Mauguin (H-M) symbol which specifies the space group of the structure in the response.\n\n- **Type**: string\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - The H-M symbols SHOULD be given as specified in the International Tables for Crystallography vol. A (IUCr, 2005), Table 4.3.2.1.\n - The change-of-basis operation SHOULD be provided for the non-standard axis and cell choices.\n - The extended H-M symbol does not unambiguously communicate the origin choice, and the given symbol SHOULD NOT be amended to convey this information.\n - The description of the change-of-basis SHOULD follow conventions of the ITC Vol. B, Sect. 1.4, Appendix A1.4.2 (IUCr, 2001).\n - The same character string encoding conventions MUST be used as for the specification of the `space_group_symbol_hermann_mauguin` property.\n\n- **Examples**:\n\n - `C 1 2 1`\n\n- **Bibliographic References**:\n\n IUCr (2001). International Tables for Crystallography vol. B. Reciprocal Space. Ed. U. Shmueli. 2-nd edition. Dordrecht/Boston/London, Kluwer Academic Publishers.", "x-optimade-queryable": "optional", "x-optimade-support": "optional" }, @@ -3658,18 +3665,18 @@ "type": "array", "title": "Cartesian Site Positions", "description": "Cartesian positions of each site in the structure.\nA site is usually used to describe positions of atoms; what atoms can be encountered at a given site is conveyed by the `species_at_sites` property, and the species themselves are described in the `species` property.\n\n- **Type**: list of list of floats\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - It MUST be a list of length equal to the number of sites in the structure, where every element is a list of the three Cartesian coordinates of a site expressed as float values in the unit angstrom (\u00c5).\n - An entry MAY have multiple sites at the same Cartesian position (for a relevant use of this, see e.g., the property `assemblies`).\n\n- **Examples**:\n - `[[0,0,0],[0,0,2]]` indicates a structure with two sites, one sitting at the origin and one along the (positive) *z*-axis, 2 \u00c5 away from the origin.", - "x-optimade-queryable": "optional", "x-optimade-support": "should", + "x-optimade-unit": "\u00c5", "nullable": true, - "x-optimade-unit": "\u00c5" + "x-optimade-queryable": "optional" }, "nsites": { "type": "integer", "title": "Nsites", "description": "An integer specifying the length of the `cartesian_site_positions` property.\n\n- **Type**: integer\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `42`\n\n- **Query examples**:\n - Match only structures with exactly 4 sites: `nsites=4`\n - Match structures that have between 2 and 7 sites: `nsites>=2 AND nsites<=7`", + "nullable": true, "x-optimade-queryable": "must", - "x-optimade-support": "should", - "nullable": true + "x-optimade-support": "should" }, "species": { "items": { @@ -3678,9 +3685,9 @@ "type": "array", "title": "Species", "description": "A list describing the species of the sites of this structure.\nSpecies can represent pure chemical elements, virtual-crystal atoms representing a statistical occupation of a given site by multiple chemical elements, and/or a location to which there are attached atoms, i.e., atoms whose precise location are unknown beyond that they are attached to that position (frequently used to indicate hydrogen atoms attached to another element, e.g., a carbon with three attached hydrogens might represent a methyl group, -CH3).\n\n- **Type**: list of dictionary with keys:\n - `name`: string (REQUIRED)\n - `chemical_symbols`: list of strings (REQUIRED)\n - `concentration`: list of float (REQUIRED)\n - `attached`: list of strings (REQUIRED)\n - `nattached`: list of integers (OPTIONAL)\n - `mass`: list of floats (OPTIONAL)\n - `original_name`: string (OPTIONAL).\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - Each list member MUST be a dictionary with the following keys:\n - **name**: REQUIRED; gives the name of the species; the **name** value MUST be unique in the `species` list;\n - **chemical_symbols**: REQUIRED; MUST be a list of strings of all chemical elements composing this species.\n Each item of the list MUST be one of the following:\n - a valid chemical-element symbol, or\n - the special value `\"X\"` to represent a non-chemical element, or\n - the special value `\"vacancy\"` to represent that this site has a non-zero probability of having a vacancy (the respective probability is indicated in the `concentration` list, see below).\n\n If any one entry in the `species` list has a `chemical_symbols` list that is longer than 1 element, the correct flag MUST be set in the list `structure_features`.\n\n - **concentration**: REQUIRED; MUST be a list of floats, with same length as `chemical_symbols`.\n The numbers represent the relative concentration of the corresponding chemical symbol in this species.\n The numbers SHOULD sum to one. Cases in which the numbers do not sum to one typically fall only in the following two categories:\n\n - Numerical errors when representing float numbers in fixed precision, e.g. for two chemical symbols with concentrations `1/3` and `2/3`, the concentration might look something like `[0.33333333333, 0.66666666666]`. If the client is aware that the sum is not one because of numerical precision, it can renormalize the values so that the sum is exactly one.\n - Experimental errors in the data present in the database. In this case, it is the responsibility of the client to decide how to process the data.\n\n Note that concentrations are uncorrelated between different sites (even of the same species).\n\n - **attached**: OPTIONAL; if provided MUST be a list of length 1 or more of strings of chemical symbols for the elements attached to this site, or \"X\" for a non-chemical element.\n\n - **nattached**: OPTIONAL; if provided MUST be a list of length 1 or more of integers indicating the number of attached atoms of the kind specified in the value of the `attached` key.\n\n The implementation MUST include either both or none of the `attached` and `nattached` keys, and if they are provided, they MUST be of the same length.\n Furthermore, if they are provided, the `structure_features` property MUST include the string `site_attachments`.\n\n - **mass**: OPTIONAL. If present MUST be a list of floats, with the same length as `chemical_symbols`, providing element masses expressed in a.m.u.\n Elements denoting vacancies MUST have masses equal to 0.\n\n - **original_name**: OPTIONAL. Can be any valid Unicode string, and SHOULD contain (if specified) the name of the species that is used internally in the source database.\n\n Note: With regards to \"source database\", we refer to the immediate source being queried via the OPTIMADE API implementation.\n\n The main use of this field is for source databases that use species names, containing characters that are not allowed (see description of the list property `species_at_sites`).\n\n - For systems that have only species formed by a single chemical symbol, and that have at most one species per chemical symbol, SHOULD use the chemical symbol as species name (e.g., `\"Ti\"` for titanium, `\"O\"` for oxygen, etc.)\n However, note that this is OPTIONAL, and client implementations MUST NOT assume that the key corresponds to a chemical symbol, nor assume that if the species name is a valid chemical symbol, that it represents a species with that chemical symbol.\n This means that a species `{\"name\": \"C\", \"chemical_symbols\": [\"Ti\"], \"concentration\": [1.0]}` is valid and represents a titanium species (and *not* a carbon species).\n - It is NOT RECOMMENDED that a structure includes species that do not have at least one corresponding site.\n\n- **Examples**:\n - `[ {\"name\": \"Ti\", \"chemical_symbols\": [\"Ti\"], \"concentration\": [1.0]} ]`: any site with this species is occupied by a Ti atom.\n - `[ {\"name\": \"Ti\", \"chemical_symbols\": [\"Ti\", \"vacancy\"], \"concentration\": [0.9, 0.1]} ]`: any site with this species is occupied by a Ti atom with 90 % probability, and has a vacancy with 10 % probability.\n - `[ {\"name\": \"BaCa\", \"chemical_symbols\": [\"vacancy\", \"Ba\", \"Ca\"], \"concentration\": [0.05, 0.45, 0.5], \"mass\": [0.0, 137.327, 40.078]} ]`: any site with this species is occupied by a Ba atom with 45 % probability, a Ca atom with 50 % probability, and by a vacancy with 5 % probability. The mass of this site is (on average) 88.5 a.m.u.\n - `[ {\"name\": \"C12\", \"chemical_symbols\": [\"C\"], \"concentration\": [1.0], \"mass\": [12.0]} ]`: any site with this species is occupied by a carbon isotope with mass 12.\n - `[ {\"name\": \"C13\", \"chemical_symbols\": [\"C\"], \"concentration\": [1.0], \"mass\": [13.0]} ]`: any site with this species is occupied by a carbon isotope with mass 13.\n - `[ {\"name\": \"CH3\", \"chemical_symbols\": [\"C\"], \"concentration\": [1.0], \"attached\": [\"H\"], \"nattached\": [3]} ]`: any site with this species is occupied by a methyl group, -CH3, which is represented without specifying precise positions of the hydrogen atoms.", + "nullable": true, "x-optimade-queryable": "optional", - "x-optimade-support": "should", - "nullable": true + "x-optimade-support": "should" }, "species_at_sites": { "items": { @@ -3689,9 +3696,9 @@ "type": "array", "title": "Species At Sites", "description": "Name of the species at each site (where values for sites are specified with the same order of the property `cartesian_site_positions`).\nThe properties of the species are found in the property `species`.\n\n- **Type**: list of strings.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - MUST have length equal to the number of sites in the structure (first dimension of the list property `cartesian_site_positions`).\n - Each species name mentioned in the `species_at_sites` list MUST be described in the list property `species` (i.e. for each value in the `species_at_sites` list there MUST exist exactly one dictionary in the `species` list with the `name` attribute equal to the corresponding `species_at_sites` value).\n - Each site MUST be associated only to a single species.\n **Note**: However, species can represent mixtures of atoms, and multiple species MAY be defined for the same chemical element.\n This latter case is useful when different atoms of the same type need to be grouped or distinguished, for instance in simulation codes to assign different initial spin states.\n\n- **Examples**:\n - `[\"Ti\",\"O2\"]` indicates that the first site is hosting a species labeled `\"Ti\"` and the second a species labeled `\"O2\"`.\n - `[\"Ac\", \"Ac\", \"Ag\", \"Ir\"]` indicating the first two sites contains the `\"Ac\"` species, while the third and fourth sites contain the `\"Ag\"` and `\"Ir\"` species, respectively.", + "nullable": true, "x-optimade-queryable": "optional", - "x-optimade-support": "should", - "nullable": true + "x-optimade-support": "should" }, "assemblies": { "items": { diff --git a/optimade/models/structures.py b/optimade/models/structures.py index f71aa071f..925023c62 100644 --- a/optimade/models/structures.py +++ b/optimade/models/structures.py @@ -543,19 +543,15 @@ class StructureResourceAttributes(EntryResourceAttributes): - **Requirements/Conventions**: - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`. - However, the property is RECOMMENDED if coordinates are returned in a form to which these operations can or must be applied (e.g. fractional atom coordinates of an asymmetric unit). - Moreover, the property is REQUIRED if symmetry operations are necessary to reconstruct the full model of the material and no other symmetry information (e.g., the Hall symbol) is provided that would allow the user to derive symmetry operations unambiguously. + + - The property is RECOMMENDED if coordinates are returned in a form to which these operations can or must be applied (e.g. fractional atom coordinates of an asymmetric unit). + - The property is REQUIRED if symmetry operations are necessary to reconstruct the full model of the material and no other symmetry information (e.g., the Hall symbol) is provided that would allow the user to derive symmetry operations unambiguously. - MUST be null if `nperiodic_dimensions` is equal to 0. - **Examples**: - - Space group operations for the space group with ITC number 3 (H-M symbol: P 2, extended H-M symbol: P 1 2 1, Hall symbol P 2y): - ``` - ["x,y,z", "-x,y,-z"] - ``` - - Space group operations for the space group with ITC number 5 (H-M symbol C 2, extended H-M symbol: C 1 2 1, Hall symbol C 2y): - ``` - ["x,y,z", "-x,y,-z", "x+1/2,y+1/2,z", "-x+1/2,y+1/2,-z"] - ``` + + - Space group operations for the space group with ITC number 3 (H-M symbol `P 2`, extended H-M symbol `P 1 2 1`, Hall symbol `P 2y`): `["x,y,z", "-x,y,-z"]` + - Space group operations for the space group with ITC number 5 (H-M symbol `C 2`, extended H-M symbol `C 1 2 1`, Hall symbol `C 2y`): `["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 `lattice_vectors` property provides the necessary information to reconstruct all atom site positions of the periodic material. @@ -571,20 +567,32 @@ class StructureResourceAttributes(EntryResourceAttributes): queryable=SupportLevel.OPTIONAL, ) - space_group_hall: Optional[str] = OptimadeField( + space_group_symbol_hall: Optional[str] = OptimadeField( None, description="""A Hall space group symbol representing the symmetry of the structure as defined in (Hall, 1981, 1981a). -The change-of-basis operations are used as defined in the International Tables of Crystallography (ITC) Vol. B, Sect. 1.4, Appendix A1.4.2 (IUCr, 2001). - **Type**: string - **Requirements/Conventions**: - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`. - **Query**: Support for queries on this property is OPTIONAL. + - The change-of-basis operations are used as defined in the International Tables of Crystallography (ITC) Vol. B, Sect. 1.4, Appendix A1.4.2 (IUCr, 2001). - Each component of the Hall symbol MUST be separated by a single space symbol. - If there exists a standard Hall symbol which represents the symmetry it SHOULD be used. - MUST be null if `nperiodic_dimensions` is not equal to 3. +- **Examples**: + + - Space group symbols with explicit origin (the Hall symbols): + + - `P 2c -2ac` + - `-I 4bd 2ab 3` + + - Space group symbols with change-of-basis operations: + + - `P 2yb (-1/2*x+z,1/2*x,y)` + - `-I 4 2 (1/2*x+1/2*y,-1/2*x+1/2*y,z)` + - **Bibliographic References**: Hall, S. R. (1981) Space-group notation with an explicit origin. Acta Crystallographica Section A, 37, 517-525, International Union of Crystallography (IUCr), DOI: https://doi.org/10.1107/s0567739481001228 @@ -599,21 +607,20 @@ class StructureResourceAttributes(EntryResourceAttributes): space_group_symbol_hermann_mauguin: Optional[str] = OptimadeField( None, description="""A human- and machine-readable string containing the short Hermann-Mauguin (H-M) symbol which specifies the space group of the structure in the response. -The H-M symbol SHOULD aim to convey the closest representation of the symmetry information that can be specified using the short format used in the International Tables for Crystallography vol. A (IUCr, 2005), Table 4.3.2.1 as described in the accompanying text. -The symbol MAY be a non-standard short H-M symbol. -The H-M symbol does not unambiguously communicate the axis, cell, and origin choice, and the given symbol SHOULD NOT be amended to convey this information. - -To encode as character strings, the following adaptations MUST be made when representing H-M symbols given in their typesetted form: - - the overbar above the numbers MUST be changed to the minus sign in front of the digit (e.g. '-2'); - - subscripts that denote screw axes are written as digits immediately after the axis designator without a space (e.g. 'P 32') - - the space group generators MUST be separated by a single space (e.g. 'P 21 21 2'); - - there MUST be no spaces in the space group generator designation (i.e. use 'P 21/m', not the 'P 21 / m'); - - **Type**: string - **Requirements/Conventions**: - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`. - **Query**: Support for queries on this property is OPTIONAL. + - The H-M symbol SHOULD aim to convey the closest representation of the symmetry information that can be specified using the short format used in the International Tables for Crystallography vol. A (IUCr, 2005), Table 4.3.2.1 as described in the accompanying text. + - The symbol MAY be a non-standard short H-M symbol. + - The H-M symbol does not unambiguously communicate the axis, cell, and origin choice, and the given symbol SHOULD NOT be amended to convey this information. + - To encode as character strings, the following adaptations MUST be made when representing H-M symbols given in their typesetted form: + + - the overbar above the numbers MUST be changed to the minus sign in front of the digit (e.g. '-2'); + - subscripts that denote screw axes are written as digits immediately after the axis designator without a space (e.g. 'P 32') + - the space group generators MUST be separated by a single space (e.g. 'P 21 21 2'); + - there MUST be no spaces in the space group generator designation (i.e. use 'P 21/m', not the 'P 21 / m'); - **Examples**: - `C 2` @@ -621,7 +628,33 @@ class StructureResourceAttributes(EntryResourceAttributes): - **Bibliographic References**: -IUCr (2005). International Tables for Crystallography vol. A. Space-Group Symmetry. Ed. Theo Hahn. 5-th edition. Dordrecht, Springer.""", + IUCr (2005). International Tables for Crystallography vol. A. Space-Group Symmetry. Ed. Theo Hahn. 5-th edition. Dordrecht, Springer.""", + support=SupportLevel.OPTIONAL, + queryable=SupportLevel.OPTIONAL, + ) + + space_group_symbol_hermann_mauguin_extended: Optional[str] = OptimadeField( + None, + description="""A human- and machine-readable string containing the extended Hermann-Mauguin (H-M) symbol which specifies the space group of the structure in the response. + +- **Type**: string +- **Requirements/Conventions**: + + - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`. + - **Query**: Support for queries on this property is OPTIONAL. + - The H-M symbols SHOULD be given as specified in the International Tables for Crystallography vol. A (IUCr, 2005), Table 4.3.2.1. + - 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 `space_group_symbol_hermann_mauguin` property. + +- **Examples**: + + - `C 1 2 1` + +- **Bibliographic References**: + + IUCr (2001). International Tables for Crystallography vol. B. Reciprocal Space. Ed. U. Shmueli. 2-nd edition. Dordrecht/Boston/London, Kluwer Academic Publishers.""", support=SupportLevel.OPTIONAL, queryable=SupportLevel.OPTIONAL, ) @@ -1057,7 +1090,7 @@ def check_periodic_dimensions(cls, v, values): return v - @validator("space_group_hall", "space_group_it_number") + @validator("space_group_symbol_hall", "space_group_it_number") def check_space_group_vs_nperiodic_dimensions(cls, v, values, field): if v is not None and values.get("nperiodic_dimensions", 3) != 3: raise ValueError(f"{field.name} provided but `nperiodic_dimensions!=3`") From 0480e57c466260e94cd8876bf390d530aa4d724c Mon Sep 17 00:00:00 2001 From: Matthew Evans Date: Thu, 4 Jan 2024 12:39:33 +0000 Subject: [PATCH 19/19] Update test with new number of properties --- tests/server/test_client.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/server/test_client.py b/tests/server/test_client.py index 406366f84..0a7b40ac2 100644 --- a/tests/server/test_client.py +++ b/tests/server/test_client.py @@ -480,7 +480,7 @@ def test_list_properties( results = cli.list_properties("structures") for database in results: - assert len(results[database]) == 22 + assert len(results[database]) == 27 results = cli.search_property("structures", "site") for database in results: