From c22e48b2791b85d822e8ff509cce52bba8383a84 Mon Sep 17 00:00:00 2001 From: Matthew Evans Date: Mon, 22 Jun 2020 15:26:04 +0100 Subject: [PATCH 1/8] Added task for pulling and converting current spec into markdown --- tasks.py | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/tasks.py b/tasks.py index 31bedd931..c69f89d5e 100644 --- a/tasks.py +++ b/tasks.py @@ -121,6 +121,18 @@ def parse_spec_for_filters(_): handle.write(_filter + "\n") +@task +def get_markdown_spec(ctx): + print("Attempting to run pandoc...") + ctx.run( + "pandoc " + "-f rst -t markdown_strict " + "--wrap=preserve --columns=50000 " + "https://raw.githubusercontent.com/Materials-Consortia/OPTIMADE/develop/optimade.rst " + "> optimade.md" + ) + + @task def generate_openapi(_): """Update OpenAPI schema in file 'local_openapi.json'""" From d56f30a27782d4e0cf24f9936a1d37ef958a86bb Mon Sep 17 00:00:00 2001 From: Matthew Evans Date: Mon, 22 Jun 2020 18:56:04 +0100 Subject: [PATCH 2/8] Converted and updated descriptions of all models --- openapi/index_openapi.json | 54 +-- openapi/openapi.json | 138 +++--- optimade/models/baseinfo.py | 2 +- optimade/models/entries.py | 112 ++--- optimade/models/index_metadb.py | 12 +- optimade/models/jsonapi.py | 11 +- optimade/models/links.py | 24 +- optimade/models/optimade_json.py | 26 +- optimade/models/references.py | 50 +-- optimade/models/structures.py | 704 ++++++++++++++++--------------- 10 files changed, 566 insertions(+), 567 deletions(-) diff --git a/openapi/index_openapi.json b/openapi/index_openapi.json index 9b65d6f69..8398e289f 100644 --- a/openapi/index_openapi.json +++ b/openapi/index_openapi.json @@ -346,12 +346,12 @@ "id": { "title": "Id", "type": "string", - "description": "An entry's ID as defined in section `Definition of Terms`_.\n- **Type**: string.\n- **Requirements/Conventions**:\n\n - **Support**: REQUIRED, MUST NOT be :val:`null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - See section `Definition of Terms`_.\n\n- **Examples**:\n\n - :val:`\"db/1234567\"`\n - :val:`\"cod/2000000\"`\n - :val:`\"cod/2000000@1234567\"`\n - :val:`\"nomad/L1234567890\"`\n - :val:`\"42\"`" + "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\"`" }, "type": { "title": "Type", "type": "string", - "description": "The name of the type of an entry.\n- **Type**: string.\n- **Requirements/Conventions**:\n\n - **Support**: REQUIRED, MUST NOT be :val:`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 :endpoint:`//` under the versioned base URL.\n\n- **Example**: :val:`\"structures\"`" + "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\"`" }, "links": { "title": "Links", @@ -378,7 +378,7 @@ "$ref": "#/components/schemas/EntryResourceAttributes" } ], - "description": "a dictionary, containing key-value pairs representing the entry's properties, except for type and id.\n\nDatabase-provider-specific properties need to include the database-provider-specific prefix\n(see appendix `Database-Provider-Specific Namespace Prefixes`_)." + "description": "A dictionary, containing key-value pairs representing the entry's properties, except for `type` and `id`.\nDatabase-provider-specific properties need to include the database-provider-specific prefix (see section on Database-Provider-Specific Namespace Prefixes)." }, "relationships": { "title": "Relationships", @@ -387,10 +387,10 @@ "$ref": "#/components/schemas/EntryRelationships" } ], - "description": "a dictionary containing references to other entries according to the description in section `Relationships`_\nencoded as `JSON API Relationships `__.\nThe OPTIONAL human-readable description of the relationship MAY be provided in the :field:`description` field inside the :field:`meta` dictionary." + "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": "Resource objects appear in a JSON:API document to represent resources." + "description": "Resource objects appear in a JSON API document to represent resources." }, "EntryResourceAttributes": { "title": "EntryResourceAttributes", @@ -402,12 +402,12 @@ "immutable_id": { "title": "Immutable Id", "type": "string", - "description": "The entry's immutable ID (e.g., an UUID).\nThis is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants.\nThis ID maps to the version-specific record, in case it changes in the future.\n- **Type**: string.\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL, i.e., MAY be :val:`null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n\n - :val:`\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - :val:`\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)" + "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.)" }, "last_modified": { "title": "Last Modified", "type": "string", - "description": "Date and time representing when the entry was last modified.\n- **Type**: timestamp.\n- **Requirements/Conventions**:\n\n - **Support**: SHOULD be supported, i.e., SHOULD NOT be :val:`null`. Is REQUIRED in this implementation, i.e., MUST NOT be :val:`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 :query-param:`response_fields` is present and does not include this property.\n\n- **Example**:\n\n - As part of JSON response format: :VAL:`\"2007-04-05T14:30Z\"` (i.e., encoded as an `RFC 3339 Internet Date/Time Format `__ 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" } }, @@ -709,7 +709,7 @@ "is_index": { "title": "Is Index", "type": "boolean", - "description": "If true, this is an index meta-database base URL (see section Index Meta-Database). If this member is not provided, the client MUST assume this is not an index meta-database base URL (i.e., the default is for is_index to be false)." + "description": "If true, this is an index meta-database base URL (see section Index Meta-Database). If this member is not provided, the client MUST assume this is not an index meta-database base URL (i.e., the default is for `is_index` to be false)." } }, "description": "Attributes for Base URL Info endpoint for an Index Meta-Database" @@ -757,7 +757,7 @@ "additionalProperties": { "$ref": "#/components/schemas/IndexRelationship" }, - "description": "Reference to the child identifier object under the links endpoint that the provider has chosen as their 'default' OPTIMADE API database. A client SHOULD present this database as the first choice when an end-user chooses this provider." + "description": "Reference to the child identifier object under the `links` endpoint that the provider has chosen as their 'default' OPTIMADE API database.\nA client SHOULD present this database as the first choice when an end-user chooses this provider." } }, "description": "Index Meta-Database Base URL Info endpoint resource" @@ -840,7 +840,7 @@ "$ref": "#/components/schemas/RelatedLinksResource" } ], - "description": "JSON API resource linkage. It MUST be either null or contain a single Links identifier object with the fields 'id' and 'type'" + "description": "JSON API resource linkage.\nIt MUST be either `null` or contain a single Links identifier object with the fields `id` and `type`" } }, "description": "Index Meta-Database relationship" @@ -905,7 +905,7 @@ "id": { "title": "Id", "type": "string", - "description": "An entry's ID as defined in section `Definition of Terms`_.\n- **Type**: string.\n- **Requirements/Conventions**:\n\n - **Support**: REQUIRED, MUST NOT be :val:`null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - See section `Definition of Terms`_.\n\n- **Examples**:\n\n - :val:`\"db/1234567\"`\n - :val:`\"cod/2000000\"`\n - :val:`\"cod/2000000@1234567\"`\n - :val:`\"nomad/L1234567890\"`\n - :val:`\"42\"`" + "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\"`" }, "type": { "title": "Type", @@ -937,7 +937,7 @@ "$ref": "#/components/schemas/LinksResourceAttributes" } ], - "description": "a dictionary containing key-value pairs representing the entry's properties." + "description": "A dictionary containing key-value pairs representing the entry's properties." }, "relationships": { "title": "Relationships", @@ -946,7 +946,7 @@ "$ref": "#/components/schemas/EntryRelationships" } ], - "description": "a dictionary containing references to other entries according to the description in section `Relationships`_\nencoded as `JSON API Relationships `__.\nThe OPTIONAL human-readable description of the relationship MAY be provided in the :field:`description` field inside the :field:`meta` dictionary." + "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": "A Links endpoint resource object" @@ -965,12 +965,12 @@ "name": { "title": "Name", "type": "string", - "description": "Human-readable name for the OPTIMADE API implementation a client may provide in a list to an end-user." + "description": "Human-readable name for the OPTIMADE API implementation, e.g., for use in clients to show the name to the end-user." }, "description": { "title": "Description", "type": "string", - "description": "Human-readable description for the OPTIMADE API implementation a client may provide in a list to an end-user." + "description": "Human-readable description for the OPTIMADE API implementation, e.g., for use in clients to show a description to the end-user." }, "base_url": { "title": "Base Url", @@ -1018,7 +1018,7 @@ "external", "providers" ], - "description": "The link type of the represented resource in relation to this implementation. MUST be one of these values: 'child', 'root', 'external', 'providers'." + "description": "The link type of the represented resource in relation to this implementation.\nMUST be one of these values: 'child', 'root', 'external', 'providers'." }, "aggregate": { "title": "Aggregate", @@ -1028,13 +1028,13 @@ "staging", "no" ], - "description": "A string indicating whether a client that is following links to aggregate results from different OPTIMADE implementations should follow this link or not.\nThis flag SHOULD NOT be indicated for links where :property:`link_type` is not :val:`child`.\n\nIf not specified, clients MAY assume that the value is :val:`ok`.\nIf specified, and the value is anything different than :val:`ok`, the client MUST assume that the server is suggesting not to follow the link during aggregation by default (also if the value is not among the known ones, in case a future specification adds new accepted values).\n\nSpecific values indicate the reason why the server is providing the suggestion.\nA client MAY follow the link anyway if it has reason to do so (e.g., if the client is looking for all test databases, it MAY follow the links marked with :property:`aggregate`=:val:`test`).\n\nIf specified, it MUST be one of the values listed in section Link Aggregate Options.", + "description": "A string indicating whether a client that is following links to aggregate results from different OPTIMADE implementations should follow this link or not.\nThis flag SHOULD NOT be indicated for links where `link_type` is not `child`.\n\nIf not specified, clients MAY assume that the value is `ok`.\nIf specified, and the value is anything different than `ok`, the client MUST assume that the server is suggesting not to follow the link during aggregation by default (also if the value is not among the known ones, in case a future specification adds new accepted values).\n\nSpecific values indicate the reason why the server is providing the suggestion.\nA client MAY follow the link anyway if it has reason to do so (e.g., if the client is looking for all test databases, it MAY follow the links marked with `aggregate`=`test`).\n\nIf specified, it MUST be one of the values listed in section [Link Aggregate Options](#link-aggregate-options).", "default": "ok" }, "no_aggregate_reason": { "title": "No Aggregate Reason", "type": "string", - "description": "An OPTIONAL human-readable string indicating the reason for suggesting not to aggregate results following the link.\nIt SHOULD NOT be present if :property:`aggregate`=:val:`ok`." + "description": "An OPTIONAL human-readable string indicating the reason for suggesting not to aggregate results following the link.\nIt SHOULD NOT be present if `aggregate`=`ok`." } }, "description": "Links endpoint resource object attributes" @@ -1362,7 +1362,7 @@ "description": "A related resource link" } }, - "description": "A resource object **MAY** contain references to other resource objects (\"relationships\").\nRelationships may be to-one or to-many. Relationships can be specified by including a member in a resource's links object." + "description": "A resource object **MAY** contain references to other resource objects (\"relationships\").\nRelationships may be to-one or to-many.\nRelationships can be specified by including a member in a resource's links object." }, "Relationships": { "title": "Relationships", @@ -1422,10 +1422,10 @@ "$ref": "#/components/schemas/Relationships" } ], - "description": "a relationships object describing relationships between the resource and other JSON:API resources." + "description": "a relationships object describing relationships between the resource and other JSON API resources." } }, - "description": "Resource objects appear in a JSON:API document to represent resources." + "description": "Resource objects appear in a JSON API document to represent resources." }, "ResourceLinks": { "title": "ResourceLinks", @@ -1482,19 +1482,19 @@ "time_stamp": { "title": "Time Stamp", "type": "string", - "description": "a string containing the date and time at which the query was exexcuted", + "description": "a timestamp containing the date and time at which the query was executed.", "format": "date-time" }, "data_returned": { "title": "Data Returned", "minimum": 0.0, "type": "integer", - "description": "an integer containing the number of data objects returned for the query." + "description": "an integer containing the total number of data resource objects returned for the current `filter` query, independent of pagination." }, "more_data_available": { "title": "More Data Available", "type": "boolean", - "description": "`false` if all data has been returned, and `true` if not." + "description": "`false` if all data resource objects for this `filter` query have been returned in the response or if it is the last page of a paginated response, and `true` otherwise." }, "provider": { "title": "Provider", @@ -1508,7 +1508,7 @@ "data_available": { "title": "Data Available", "type": "integer", - "description": "an integer containing the total number of data objects available in the database" + "description": "an integer containing the total number of data resource objects available in the database for the endpoint." }, "last_id": { "title": "Last Id", @@ -1536,7 +1536,7 @@ "items": { "$ref": "#/components/schemas/Warnings" }, - "description": "List of warning resource objects representing non-critical errors or warnings. A warning resource object is defined similarly to a JSON API error object, but MUST also include the field type, which MUST have the value \"warning\". The field detail MUST be present and SHOULD contain a non-critical message, e.g., reporting unrecognized search attributes or deprecated features. The field status, representing a HTTP response status code, MUST NOT be present for a warning resource object. This is an exclusive field for error resource objects." + "description": "A list of warning resource objects representing non-critical errors or warnings.\nA warning resource object is defined similarly to a [JSON API error object](http://jsonapi.org/format/1.0/#error-objects), but MUST also include the field `type`, which MUST have the value `\"warning\"`.\nThe field `detail` MUST be present and SHOULD contain a non-critical message, e.g., reporting unrecognized search attributes or deprecated features.\nThe field `status`, representing a HTTP response status code, MUST NOT be present for a warning resource object.\nThis is an exclusive field for error resource objects." } }, "description": "A [JSON API meta member](https://jsonapi.org/format/1.0#document-meta)\nthat contains JSON API meta objects of non-standard\nmeta-information.\n\nOPTIONAL additional information global to the query that is not\nspecified in this document, MUST start with a\ndatabase-provider-specific prefix." @@ -1769,7 +1769,7 @@ "description": "Warnings must be of type \"warning\"" } }, - "description": "OPTIMADE-specific warning class based on OPTIMADE-specific JSON API Error.\nFrom the specification:\n\n A warning resource object is defined similarly to a JSON API\n error object, but MUST also include the field type, which MUST\n have the value \"warning\". The field detail MUST be present and\n SHOULD contain a non-critical message, e.g., reporting\n unrecognized search attributes or deprecated features.\n\nNote: Must be named \"Warnings\", since \"Warning\" is a built-in Python class." + "description": "OPTIMADE-specific warning class based on OPTIMADE-specific JSON API Error.\n\nFrom the specification:\n\n A warning resource object is defined similarly to a JSON API\n error object, but MUST also include the field type, which MUST\n have the value \"warning\". The field detail MUST be present and\n SHOULD contain a non-critical message, e.g., reporting\n unrecognized search attributes or deprecated features.\n\nNote: Must be named \"Warnings\", since \"Warning\" is a built-in Python class." } } } diff --git a/openapi/openapi.json b/openapi/openapi.json index d92170481..ee8fce893 100644 --- a/openapi/openapi.json +++ b/openapi/openapi.json @@ -887,7 +887,7 @@ "type": "integer" } }, - "description": "Index of the sites (0-based) that belong to each group for each assembly.\n\nExample: :val:`[[1], [2]]`: two groups, one with the second site, one with the third.\nExample: :val:`[[1,2], [3]]`: one group with the second and third site, one with the fourth." + "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." }, "group_probabilities": { "title": "Group Probabilities", @@ -895,10 +895,10 @@ "items": { "type": "number" }, - "description": "Statistical probability of each group. It MUST have the same length as :property:`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 :property:`concentration` of each :property:`species`, see property `species`_." + "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`, see property [species](#species)." } }, - "description": "A description of groups of sites that are statistically correlated.\n\n- **Examples** (for each entry of the assemblies list):\n\n - :val:`{\"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 - :val:`{\"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)." + "description": "A description of groups of sites that are statistically correlated.\n\n- **Examples** (for each entry of the assemblies list):\n\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. 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)." }, "Attributes": { "title": "Attributes", @@ -988,7 +988,7 @@ "is_index": { "title": "Is Index", "type": "boolean", - "description": "If true, this is an index meta-database base URL (see section Index Meta-Database). If this member is not provided, the client MUST assume this is not an index meta-database base URL (i.e., the default is for is_index to be false).", + "description": "If true, this is an index meta-database base URL (see section Index Meta-Database). If this member is not provided, the client MUST assume this is not an index meta-database base URL (i.e., the default is for `is_index` to be false).", "default": false } }, @@ -1037,10 +1037,10 @@ "$ref": "#/components/schemas/Relationships" } ], - "description": "a relationships object describing relationships between the resource and other JSON:API resources." + "description": "a relationships object describing relationships between the resource and other JSON API resources." } }, - "description": "Resource objects appear in a JSON:API document to represent resources." + "description": "Resource objects appear in a JSON API document to represent resources." }, "BaseRelationshipMeta": { "title": "BaseRelationshipMeta", @@ -1097,17 +1097,17 @@ "description": { "title": "Description", "type": "string", - "description": "description of the entry property" + "description": "A human-readable description of the entry property" }, "unit": { "title": "Unit", "type": "string", - "description": "the physical unit of the entry property" + "description": "The physical unit of the entry property.\nIt is RECOMMENDED that non-standard (non-SI) units are described in the description for the property." }, "sortable": { "title": "Sortable", "type": "boolean", - "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`." + "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`." }, "type": { "title": "Type", @@ -1121,7 +1121,7 @@ "dictionary", "unknown" ], - "description": "Data type of value. Must equal a valid OPTIMADE data type as listed and defined under 'Data types'." + "description": "String.\nThe type of the property's value.\n\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`.\nData type of value. Must equal a valid OPTIMADE data type as listed and defined under 'Data types'." } } }, @@ -1141,12 +1141,12 @@ "items": { "type": "string" }, - "description": "list of available output formats." + "description": "List of output formats available for this type of entry." }, "description": { "title": "Description", "type": "string", - "description": "description of the entry" + "description": "Description of the entry" }, "properties": { "title": "Properties", @@ -1154,7 +1154,7 @@ "additionalProperties": { "$ref": "#/components/schemas/EntryInfoProperty" }, - "description": "a dictionary describing queryable properties for this entry type, where each key is a property ID." + "description": "A dictionary describing queryable properties for this entry type, where each key is a property name." }, "output_fields_by_format": { "title": "Output Fields By Format", @@ -1165,7 +1165,7 @@ "type": "string" } }, - "description": "a dictionary of available output fields for this entry type, where the keys are the values of the `formats` list and the values are the keys of the `properties` dictionary." + "description": "Dictionary of available output fields for this entry type, where the keys are the values of the `formats` list and the values are the keys of the `properties` dictionary." } } }, @@ -1270,12 +1270,12 @@ "id": { "title": "Id", "type": "string", - "description": "An entry's ID as defined in section `Definition of Terms`_.\n- **Type**: string.\n- **Requirements/Conventions**:\n\n - **Support**: REQUIRED, MUST NOT be :val:`null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - See section `Definition of Terms`_.\n\n- **Examples**:\n\n - :val:`\"db/1234567\"`\n - :val:`\"cod/2000000\"`\n - :val:`\"cod/2000000@1234567\"`\n - :val:`\"nomad/L1234567890\"`\n - :val:`\"42\"`" + "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\"`" }, "type": { "title": "Type", "type": "string", - "description": "The name of the type of an entry.\n- **Type**: string.\n- **Requirements/Conventions**:\n\n - **Support**: REQUIRED, MUST NOT be :val:`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 :endpoint:`//` under the versioned base URL.\n\n- **Example**: :val:`\"structures\"`" + "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\"`" }, "links": { "title": "Links", @@ -1302,7 +1302,7 @@ "$ref": "#/components/schemas/EntryResourceAttributes" } ], - "description": "a dictionary, containing key-value pairs representing the entry's properties, except for type and id.\n\nDatabase-provider-specific properties need to include the database-provider-specific prefix\n(see appendix `Database-Provider-Specific Namespace Prefixes`_)." + "description": "A dictionary, containing key-value pairs representing the entry's properties, except for `type` and `id`.\nDatabase-provider-specific properties need to include the database-provider-specific prefix (see section on Database-Provider-Specific Namespace Prefixes)." }, "relationships": { "title": "Relationships", @@ -1311,10 +1311,10 @@ "$ref": "#/components/schemas/EntryRelationships" } ], - "description": "a dictionary containing references to other entries according to the description in section `Relationships`_\nencoded as `JSON API Relationships `__.\nThe OPTIONAL human-readable description of the relationship MAY be provided in the :field:`description` field inside the :field:`meta` dictionary." + "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": "Resource objects appear in a JSON:API document to represent resources." + "description": "Resource objects appear in a JSON API document to represent resources." }, "EntryResourceAttributes": { "title": "EntryResourceAttributes", @@ -1326,12 +1326,12 @@ "immutable_id": { "title": "Immutable Id", "type": "string", - "description": "The entry's immutable ID (e.g., an UUID).\nThis is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants.\nThis ID maps to the version-specific record, in case it changes in the future.\n- **Type**: string.\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL, i.e., MAY be :val:`null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n\n - :val:`\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - :val:`\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)" + "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.)" }, "last_modified": { "title": "Last Modified", "type": "string", - "description": "Date and time representing when the entry was last modified.\n- **Type**: timestamp.\n- **Requirements/Conventions**:\n\n - **Support**: SHOULD be supported, i.e., SHOULD NOT be :val:`null`. Is REQUIRED in this implementation, i.e., MUST NOT be :val:`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 :query-param:`response_fields` is present and does not include this property.\n\n- **Example**:\n\n - As part of JSON response format: :VAL:`\"2007-04-05T14:30Z\"` (i.e., encoded as an `RFC 3339 Internet Date/Time Format `__ 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" } }, @@ -1701,7 +1701,7 @@ "id": { "title": "Id", "type": "string", - "description": "An entry's ID as defined in section `Definition of Terms`_.\n- **Type**: string.\n- **Requirements/Conventions**:\n\n - **Support**: REQUIRED, MUST NOT be :val:`null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - See section `Definition of Terms`_.\n\n- **Examples**:\n\n - :val:`\"db/1234567\"`\n - :val:`\"cod/2000000\"`\n - :val:`\"cod/2000000@1234567\"`\n - :val:`\"nomad/L1234567890\"`\n - :val:`\"42\"`" + "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\"`" }, "type": { "title": "Type", @@ -1733,7 +1733,7 @@ "$ref": "#/components/schemas/LinksResourceAttributes" } ], - "description": "a dictionary containing key-value pairs representing the entry's properties." + "description": "A dictionary containing key-value pairs representing the entry's properties." }, "relationships": { "title": "Relationships", @@ -1742,7 +1742,7 @@ "$ref": "#/components/schemas/EntryRelationships" } ], - "description": "a dictionary containing references to other entries according to the description in section `Relationships`_\nencoded as `JSON API Relationships `__.\nThe OPTIONAL human-readable description of the relationship MAY be provided in the :field:`description` field inside the :field:`meta` dictionary." + "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": "A Links endpoint resource object" @@ -1761,12 +1761,12 @@ "name": { "title": "Name", "type": "string", - "description": "Human-readable name for the OPTIMADE API implementation a client may provide in a list to an end-user." + "description": "Human-readable name for the OPTIMADE API implementation, e.g., for use in clients to show the name to the end-user." }, "description": { "title": "Description", "type": "string", - "description": "Human-readable description for the OPTIMADE API implementation a client may provide in a list to an end-user." + "description": "Human-readable description for the OPTIMADE API implementation, e.g., for use in clients to show a description to the end-user." }, "base_url": { "title": "Base Url", @@ -1814,7 +1814,7 @@ "external", "providers" ], - "description": "The link type of the represented resource in relation to this implementation. MUST be one of these values: 'child', 'root', 'external', 'providers'." + "description": "The link type of the represented resource in relation to this implementation.\nMUST be one of these values: 'child', 'root', 'external', 'providers'." }, "aggregate": { "title": "Aggregate", @@ -1824,13 +1824,13 @@ "staging", "no" ], - "description": "A string indicating whether a client that is following links to aggregate results from different OPTIMADE implementations should follow this link or not.\nThis flag SHOULD NOT be indicated for links where :property:`link_type` is not :val:`child`.\n\nIf not specified, clients MAY assume that the value is :val:`ok`.\nIf specified, and the value is anything different than :val:`ok`, the client MUST assume that the server is suggesting not to follow the link during aggregation by default (also if the value is not among the known ones, in case a future specification adds new accepted values).\n\nSpecific values indicate the reason why the server is providing the suggestion.\nA client MAY follow the link anyway if it has reason to do so (e.g., if the client is looking for all test databases, it MAY follow the links marked with :property:`aggregate`=:val:`test`).\n\nIf specified, it MUST be one of the values listed in section Link Aggregate Options.", + "description": "A string indicating whether a client that is following links to aggregate results from different OPTIMADE implementations should follow this link or not.\nThis flag SHOULD NOT be indicated for links where `link_type` is not `child`.\n\nIf not specified, clients MAY assume that the value is `ok`.\nIf specified, and the value is anything different than `ok`, the client MUST assume that the server is suggesting not to follow the link during aggregation by default (also if the value is not among the known ones, in case a future specification adds new accepted values).\n\nSpecific values indicate the reason why the server is providing the suggestion.\nA client MAY follow the link anyway if it has reason to do so (e.g., if the client is looking for all test databases, it MAY follow the links marked with `aggregate`=`test`).\n\nIf specified, it MUST be one of the values listed in section [Link Aggregate Options](#link-aggregate-options).", "default": "ok" }, "no_aggregate_reason": { "title": "No Aggregate Reason", "type": "string", - "description": "An OPTIONAL human-readable string indicating the reason for suggesting not to aggregate results following the link.\nIt SHOULD NOT be present if :property:`aggregate`=:val:`ok`." + "description": "An OPTIONAL human-readable string indicating the reason for suggesting not to aggregate results following the link.\nIt SHOULD NOT be present if `aggregate`=`ok`." } }, "description": "Links endpoint resource object attributes" @@ -2130,12 +2130,12 @@ "id": { "title": "Id", "type": "string", - "description": "An entry's ID as defined in section `Definition of Terms`_.\n- **Type**: string.\n- **Requirements/Conventions**:\n\n - **Support**: REQUIRED, MUST NOT be :val:`null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - See section `Definition of Terms`_.\n\n- **Examples**:\n\n - :val:`\"db/1234567\"`\n - :val:`\"cod/2000000\"`\n - :val:`\"cod/2000000@1234567\"`\n - :val:`\"nomad/L1234567890\"`\n - :val:`\"42\"`" + "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\"`" }, "type": { "title": "Type", "type": "string", - "description": "The name of the type of an entry. Any entry MUST be able to be fetched using the `base URL `_ type and ID at the url :endpoint:`//`.\n- **Type**: string.\n- **Requirements/Conventions**:\n\n - **Support**: REQUIRED, MUST NOT be :val:`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 :endpoint:`//` under the versioned base URL.\n\n- **Example**: :val:`\"structures\"`" + "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\"`" }, "links": { "title": "Links", @@ -2165,10 +2165,10 @@ "$ref": "#/components/schemas/EntryRelationships" } ], - "description": "a dictionary containing references to other entries according to the description in section `Relationships`_\nencoded as `JSON API Relationships `__.\nThe OPTIONAL human-readable description of the relationship MAY be provided in the :field:`description` field inside the :field:`meta` dictionary." + "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": "The :entry:`references` entries describe bibliographic references.\nThe following properties are used to provide the bibliographic details:\n\n- **address**, **annote**, **booktitle**, **chapter**, **crossref**, **edition**, **howpublished**, **institution**, **journal**, **key**, **month**,\n **note**, **number**, **organization**, **pages**, **publisher**, **school**, **series**, **title**, **type**, **volume**, **year**:\n Meanings of these properties match the `BibTeX specification `__, values are strings;\n\n- **authors** and **editors**: lists of *person objects* which are dictionaries with the following keys:\n\n - **name**: Full name of the person, REQUIRED.\n - **firstname**, **lastname**: Parts of the person's name, OPTIONAL.\n\n- **doi** and **url**: values are strings.\n\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL, i.e., any of the properties MAY be :val:`null`.\n - **Query**: Support for queries on any of these properties is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - Every references entry MUST contain at least one of the properties." + "description": "The `references` entries describe bibliographic references.\nThe following properties are used to provide the bibliographic details:\n\n- **address**, **annote**, **booktitle**, **chapter**, **crossref**, **edition**, **howpublished**, **institution**, **journal**, **key**, **month**, **note**, **number**, **organization**, **pages**, **publisher**, **school**, **series**, **title**, **volume**, **year**: meanings of these properties match the [BibTeX specification](http://bibtexml.sourceforge.net/btxdoc.pdf), values are strings;\n- **bib_type**: type of the reference, corresponding to **type** property in the BibTeX specification, value is string;\n- **authors** and **editors**: lists of *person objects* which are dictionaries with the following keys:\n - **name**: Full name of the person, REQUIRED.\n - **firstname**, **lastname**: Parts of the person's name, OPTIONAL.\n- **doi** and **url**: values are strings.\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., any of the properties MAY be `null`.\n - **Query**: Support for queries on any of these properties is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - Every references entry MUST contain at least one of the properties." }, "ReferenceResourceAttributes": { "title": "ReferenceResourceAttributes", @@ -2180,12 +2180,12 @@ "immutable_id": { "title": "Immutable Id", "type": "string", - "description": "The entry's immutable ID (e.g., an UUID).\nThis is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants.\nThis ID maps to the version-specific record, in case it changes in the future.\n- **Type**: string.\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL, i.e., MAY be :val:`null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n\n - :val:`\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - :val:`\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)" + "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.)" }, "last_modified": { "title": "Last Modified", "type": "string", - "description": "Date and time representing when the entry was last modified.\n- **Type**: timestamp.\n- **Requirements/Conventions**:\n\n - **Support**: SHOULD be supported, i.e., SHOULD NOT be :val:`null`. Is REQUIRED in this implementation, i.e., MUST NOT be :val:`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 :query-param:`response_fields` is present and does not include this property.\n\n- **Example**:\n\n - As part of JSON response format: :VAL:`\"2007-04-05T14:30Z\"` (i.e., encoded as an `RFC 3339 Internet Date/Time Format `__ 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" }, "authors": { @@ -2536,7 +2536,7 @@ "description": "A related resource link" } }, - "description": "A resource object **MAY** contain references to other resource objects (\"relationships\").\nRelationships may be to-one or to-many. Relationships can be specified by including a member in a resource's links object." + "description": "A resource object **MAY** contain references to other resource objects (\"relationships\").\nRelationships may be to-one or to-many.\nRelationships can be specified by including a member in a resource's links object." }, "Relationships": { "title": "Relationships", @@ -2596,10 +2596,10 @@ "$ref": "#/components/schemas/Relationships" } ], - "description": "a relationships object describing relationships between the resource and other JSON:API resources." + "description": "a relationships object describing relationships between the resource and other JSON API resources." } }, - "description": "Resource objects appear in a JSON:API document to represent resources." + "description": "Resource objects appear in a JSON API document to represent resources." }, "ResourceLinks": { "title": "ResourceLinks", @@ -2656,19 +2656,19 @@ "time_stamp": { "title": "Time Stamp", "type": "string", - "description": "a string containing the date and time at which the query was exexcuted", + "description": "a timestamp containing the date and time at which the query was executed.", "format": "date-time" }, "data_returned": { "title": "Data Returned", "minimum": 0.0, "type": "integer", - "description": "an integer containing the number of data objects returned for the query." + "description": "an integer containing the total number of data resource objects returned for the current `filter` query, independent of pagination." }, "more_data_available": { "title": "More Data Available", "type": "boolean", - "description": "`false` if all data has been returned, and `true` if not." + "description": "`false` if all data resource objects for this `filter` query have been returned in the response or if it is the last page of a paginated response, and `true` otherwise." }, "provider": { "title": "Provider", @@ -2682,7 +2682,7 @@ "data_available": { "title": "Data Available", "type": "integer", - "description": "an integer containing the total number of data objects available in the database" + "description": "an integer containing the total number of data resource objects available in the database for the endpoint." }, "last_id": { "title": "Last Id", @@ -2710,7 +2710,7 @@ "items": { "$ref": "#/components/schemas/Warnings" }, - "description": "List of warning resource objects representing non-critical errors or warnings. A warning resource object is defined similarly to a JSON API error object, but MUST also include the field type, which MUST have the value \"warning\". The field detail MUST be present and SHOULD contain a non-critical message, e.g., reporting unrecognized search attributes or deprecated features. The field status, representing a HTTP response status code, MUST NOT be present for a warning resource object. This is an exclusive field for error resource objects." + "description": "A list of warning resource objects representing non-critical errors or warnings.\nA warning resource object is defined similarly to a [JSON API error object](http://jsonapi.org/format/1.0/#error-objects), but MUST also include the field `type`, which MUST have the value `\"warning\"`.\nThe field `detail` MUST be present and SHOULD contain a non-critical message, e.g., reporting unrecognized search attributes or deprecated features.\nThe field `status`, representing a HTTP response status code, MUST NOT be present for a warning resource object.\nThis is an exclusive field for error resource objects." } }, "description": "A [JSON API meta member](https://jsonapi.org/format/1.0#document-meta)\nthat contains JSON API meta objects of non-standard\nmeta-information.\n\nOPTIONAL additional information global to the query that is not\nspecified in this document, MUST start with a\ndatabase-provider-specific prefix." @@ -2749,7 +2749,7 @@ "items": { "type": "string" }, - "description": "MUST be a list of strings of all chemical elements composing this species.\n\n- It MUST be one of the following:\n\n - a valid chemical-element name, or\n - the special value :val:`\"X\"` to represent a non-chemical element, or\n - the special value :val:`\"vacancy\"` to represent that this site has a non-zero probability of having a vacancy (the respective probability is indicated in the :property:`concentration` list, see below).\n\n- If any one entry in the :property:`species` list has a :property:`chemical_symbols` list that is longer than 1 element, the correct flag MUST be set in the list :property:`structure_features` (see property `structure_features`_)." + "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 name, 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` (see property [structure_features](#structure_features))." }, "concentration": { "title": "Concentration", @@ -2757,7 +2757,7 @@ "items": { "type": "number" }, - "description": "MUST be a list of floats, with same length as :property:`chemical_symbols`. The numbers represent the relative concentration of the corresponding chemical symbol in this species.\nThe 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 :val:`1/3` and :val:`2/3`, the concentration might look something like :val:`[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)." + "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)." }, "mass": { "title": "Mass", @@ -2767,7 +2767,7 @@ "original_name": { "title": "Original Name", "type": "string", - "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.\nThe 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`_)." + "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." }, "attached": { "title": "Attached", @@ -2786,7 +2786,7 @@ "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." } }, - "description": "A list describing the species of the sites of this structure.\nSpecies can be pure chemical elements, or virtual-crystal atoms representing a statistical occupation of a given site by multiple chemical elements.\n\n- **Examples**:\n\n - :val:`[ {\"name\": \"Ti\", \"chemical_symbols\": [\"Ti\"], \"concentration\": [1.0]} ]`: any site with this species is occupied by a Ti atom.\n - :val:`[ {\"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 - :val:`[ {\"name\": \"BaCa\", \"chemical_symbols\": [\"vacancy\", \"Ba\", \"Ca\"], \"concentration\": [0.05, 0.45, 0.5], \"mass\": 88.5} ]`: 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 - :val:`[ {\"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 - :val:`[ {\"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." + "description": "A list describing the species of the sites of this structure.\nSpecies can represent pure chemical elements, virtual-crystal atoms representing a\nstatistical occupation of a given site by multiple chemical elements, and/or a\nlocation to which there are attached atoms, i.e., atoms whose precise location are\nunknown beyond that they are attached to that position (frequently used to indicate\nhydrogen atoms attached to another element, e.g., a carbon with three attached\nhydrogens might represent a methyl group, -CH3).\n\n- **Examples**:\n\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\": 88.5} ]`: 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." }, "StructureRelationship": { "title": "StructureRelationship", @@ -2844,12 +2844,12 @@ "id": { "title": "Id", "type": "string", - "description": "An entry's ID as defined in section `Definition of Terms`_.\n- **Type**: string.\n- **Requirements/Conventions**:\n\n - **Support**: REQUIRED, MUST NOT be :val:`null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - See section `Definition of Terms`_.\n\n- **Examples**:\n\n - :val:`\"db/1234567\"`\n - :val:`\"cod/2000000\"`\n - :val:`\"cod/2000000@1234567\"`\n - :val:`\"nomad/L1234567890\"`\n - :val:`\"42\"`" + "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\"`" }, "type": { "title": "Type", "type": "string", - "description": "The name of the type of an entry. Any entry MUST be able to be fetched using the `base URL `_ type and ID at the url :endpoint:`//`.\n- **Type**: string.\n- **Requirements/Conventions**:\n\n - **Support**: REQUIRED, MUST NOT be :val:`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 :endpoint:`//` under the versioned base URL.\n\n- **Example**: :val:`\"structures\"`" + "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\"`" }, "links": { "title": "Links", @@ -2879,7 +2879,7 @@ "$ref": "#/components/schemas/EntryRelationships" } ], - "description": "a dictionary containing references to other entries according to the description in section `Relationships`_\nencoded as `JSON API Relationships `__.\nThe OPTIONAL human-readable description of the relationship MAY be provided in the :field:`description` field inside the :field:`meta` dictionary." + "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." @@ -2906,12 +2906,12 @@ "immutable_id": { "title": "Immutable Id", "type": "string", - "description": "The entry's immutable ID (e.g., an UUID).\nThis is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants.\nThis ID maps to the version-specific record, in case it changes in the future.\n- **Type**: string.\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL, i.e., MAY be :val:`null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n\n - :val:`\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - :val:`\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)" + "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.)" }, "last_modified": { "title": "Last Modified", "type": "string", - "description": "Date and time representing when the entry was last modified.\n- **Type**: timestamp.\n- **Requirements/Conventions**:\n\n - **Support**: SHOULD be supported, i.e., SHOULD NOT be :val:`null`. Is REQUIRED in this implementation, i.e., MUST NOT be :val:`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 :query-param:`response_fields` is present and does not include this property.\n\n- **Example**:\n\n - As part of JSON response format: :VAL:`\"2007-04-05T14:30Z\"` (i.e., encoded as an `RFC 3339 Internet Date/Time Format `__ 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" }, "elements": { @@ -2920,12 +2920,12 @@ "items": { "type": "string" }, - "description": "Names of the different elements present in the structure.\n- **Type**: list of strings.\n- **Requirements/Conventions**:\n\n - **Support**: SHOULD be supported, i.e., SHOULD NOT be :val:`null`. Is REQUIRED in this implementation, i.e., MUST NOT be :val:`null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter operators.\n - The strings are the chemical symbols, written as uppercase letter plus optional lowercase letters.\n - The order MUST be alphabetical.\n - Note: This may not contain the \"x\" that is suggested in chemical_symbols for the :property:`species` property.\n\n- **Examples**:\n\n - :val:`[\"Si\"]`\n - :val:`[\"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: :filter:`elements HAS ALL \"Si\", \"Al\", \"O\"`.\n - To match structures with exactly these three elements, use :filter:`elements HAS ALL \"Si\", \"Al\", \"O\" AND LENGTH elements = 3`." + "description": "Names 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 - 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`." }, "nelements": { "title": "Nelements", "type": "integer", - "description": "Number of different elements in the structure as an integer.\n- **Type**: integer\n- **Requirements/Conventions**:\n\n - **Support**: SHOULD be supported, i.e., SHOULD NOT be :val:`null`. Is REQUIRED in this implementation, i.e., MUST NOT be :val:`null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter operators.\n\n- **Example**: :val:`3`\n- **Querying**:\n\n - Note: queries on this property can equivalently be formulated using :filter-fragment:`LENGTH elements`.\n - A filter that matches structures that have exactly 4 elements: :filter:`nelements=4`.\n - A filter that matches structures that have between 2 and 7 elements: :filter:`nelements>=2 AND nelements<=7`." + "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\n- **Example**: `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`." }, "elements_ratios": { "title": "Elements Ratios", @@ -2933,27 +2933,27 @@ "items": { "type": "number" }, - "description": "Relative proportions of different elements in the structure.\n- **Type**: list of floats\n- **Requirements/Conventions**:\n\n - **Support**: SHOULD be supported, i.e., SHOULD NOT be :val:`null`. Is REQUIRED in this implementation, i.e., MUST NOT be :val:`null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter operators.\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\n- **Examples**:\n\n - :val:`[1.0]`\n - :val:`[0.3333333333333333, 0.2222222222222222, 0.4444444444444444]`\n\n- **Query examples**:\n\n - Note: useful filters can be formulated using the set operator syntax for correlated values. However, since the values are floating point values, the use of equality comparisons is generally not recommended.\n - A filter that matches structures where approximately 1/3 of the atoms in the structure are the element Al is: :filter:`elements:elements_ratios HAS ALL \"Al\":>0.3333, \"Al\":<0.3334`." + "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\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`." }, "chemical_formula_descriptive": { "title": "Chemical Formula Descriptive", "type": "string", - "description": "The chemical formula for a structure as a string in a form chosen by the API implementation.\n- **Type**: string\n- **Requirements/Conventions**:\n\n - **Support**: SHOULD be supported, i.e., SHOULD NOT be :val:`null`. Is REQUIRED in this implementation, i.e., MUST NOT be :val:`null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter operators.\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.\n The parentheses are allowed to be followed by a number.\n Spaces are allowed anywhere except within chemical symbols.\n 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 :property:`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 `__.\n\n- **Examples**:\n\n - :val:`\"(H2O)2 Na\"`\n - :val:`\"NaCl\"`\n - :val:`\"CaCO3\"`\n - :val:`\"CCaO3\"`\n - :val:`\"(CH3)3N+ - [CH2]2-OH = Me3N+ - CH2 - CH2OH\"`\n\n- **Query examples**:\n\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: :filter:`chemical_formula_descriptive=\"(H2O)2 Na\"`.\n - A filter that does a partial match: :filter:`chemical_formula_descriptive CONTAINS \"H2O\"`." + "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\"`." }, "chemical_formula_reduced": { "title": "Chemical Formula Reduced", "type": "string", - "description": "The reduced chemical formula for a structure as a string with element symbols and integer chemical proportion numbers.\n The proportion number MUST be omitted if it is 1.\n- **Type**: string\n- **Requirements/Conventions**:\n\n - **Support**: SHOULD be supported, i.e., SHOULD NOT be :val:`null`. Is REQUIRED in this implementation, i.e., MUST NOT be :val:`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 querying on formula components are instead recommended to be formulated using set-type filter operators on the multi valued :property:`elements` and :property:`elements_proportions` properties.\n - Element names MUST have proper capitalization (e.g., :val:`\"Si\"`, not :VAL:`\"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\n - :val:`\"H2NaO\"`\n - :val:`\"ClNa\"`\n - :val:`\"CCaO3\"`\n\n- **Query examples**:\n\n - A filter that matches an exactly given formula is :filter:`chemical_formula_reduced=\"H2NaO\"`." + "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 names 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\"`." }, "chemical_formula_hill": { "title": "Chemical Formula Hill", "type": "string", - "description": "The chemical formula for a structure in `Hill form `__ with element symbols followed by integer chemical proportion numbers.\n The proportion number MUST be omitted if it is 1.\n- **Type**: string\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL, i.e., MAY be :val:`null`.\n - **Query**: Support for queries on these properties are OPTIONAL. If supported, only a subset of filter operators 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, :property:`chemical_formula_hill` is :val:`\"H2O2\"` (i.e., not :val:`\"HO\"`, nor :val:`\"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 names MUST have proper capitalization (e.g., :val:`\"Si\"`, not :VAL:`\"SI\"` for \"silicon\").\n - Elements MUST be placed in `Hill order `__, 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 - :val:`\"H2O2\"`\n\n- **Query examples**:\n\n - A filter that matches an exactly given formula is :filter:`chemical_formula_hill=\"H2O2\"`." + "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 names 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\"`." }, "chemical_formula_anonymous": { "title": "Chemical Formula Anonymous", "type": "string", - "description": "The anonymous formula is the :property:`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- **Type**: string\n- **Requirements/Conventions**:\n\n - **Support**: SHOULD be supported, i.e., SHOULD NOT be :val:`null`. Is REQUIRED in this implementation, i.e., MUST NOT be :val:`null`.\n - **Query**: MUST be a queryable property. 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\n - :val:`\"A2B\"`\n - :val:`\"A42B42C16D12E10F9G5\"`\n\n- **Querying**:\n - A filter that matches an exactly given formula is :filter:`chemical_formula_anonymous=\"A2B\"`." + "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\"`." }, "dimension_types": { "title": "Dimension Types", @@ -2981,12 +2981,12 @@ "type": "integer" } ], - "description": "List of three integers.\n For each of the three directions indicated by the three lattice vectors (see property `lattice_vectors`_).\n This list indicates if the direction is periodic (value :val:`1`) or non-periodic (value :val:`0`).\n Note: the elements in this list each refer to the direction of the corresponding entry in property `lattice_vectors`_ and *not* the Cartesian x, y, z directions.\n- **Type**: list of integers.\n- **Requirements/Conventions**:\n\n - **Support**: SHOULD be supported, i.e., SHOULD NOT be :val:`null`. Is REQUIRED in this implementation, i.e., MUST NOT be :val:`null`.\n - **Query**: MUST be a queryable property. Support for equality comparison is REQUIRED, support for other comparison operators are 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\n - For a molecule: :val:`[0, 0, 0]`\n - For a wire along the direction specified by the third lattice vector: :val:`[0, 0, 1]`\n - For a 2D surface/slab, periodic on the plane defined by the first and third lattice vectors: :val:`[1, 0, 1]`\n - For a bulk 3D system: :val:`[1, 1, 1]`" + "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]`" }, "nperiodic_dimensions": { "title": "Nperiodic Dimensions", "type": "integer", - "description": "An integer specifying the number of periodic dimensions in the structure, equivalent to the number of non-zero entries in :property:`dimension_types`.\n- **Type**: integer\n- **Requirements/Conventions**:\n\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be :val:`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\n - :val:`2` should be indicated in cases where :property:`dimension_types` is any of :val:`[1, 1, 0]`, :val:`[1, 0, 1]`, :val:`[0, 1, 1]`.\n\n- **Query examples**:\n\n - Match only structures with exactly 3 periodic dimensions: :filter:`nperiodic_dimensions=3`\n - Match all structures with 2 or fewer periodic dimensions: :filter:`nperiodic_dimensions<=2`" + "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`" }, "lattice_vectors": { "title": "Lattice Vectors", @@ -3035,7 +3035,7 @@ ] } ], - "description": "The three lattice vectors in Cartesian coordinates, in \u00e5ngstr\u00f6m (\u00c5).\n- **Type**: list of list of floats.\n- **Requirements/Conventions**:\n\n - **Support**: SHOULD be supported, i.e., SHOULD NOT be :val:`null`. Is REQUIRED in this implementation, i.e., MUST NOT be :val:`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 - This property MUST be an array of dimensions 3 times 3 regardless of the elements of :property:`dimension_types`.\n The vectors SHOULD by convention be chosen so the determinant of the :property:`lattice_vectors` matrix is different from zero.\n The vectors in the non-periodic directions have no significance beyond fulfilling these requirements.\n - All three elements of the inner lists of floats MAY be :val:`null` for non-periodic dimensions, i.e., those dimensions for which :property:`dimension_types` is :val:`0`.\n\n- **Examples**:\n\n - :val:`[[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 :val:`(4, 0, 0)`, i.e., a vector aligned along the :val:`x` axis of length 4 \u00c5; the second vector is :val:`(0, 4, 0)`; and the third vector is :val:`(0, 1, 4)`." + "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)`." }, "cartesian_site_positions": { "title": "Cartesian Site Positions", @@ -3054,12 +3054,12 @@ } ] }, - "description": "Cartesian positions of each site. A site is an atom, a site potentially occupied by an atom, or a placeholder for a virtual mixture of atoms (e.g., in a virtual crystal approximation).\n- **Type**: list of list of floats\n- **Requirements/Conventions**:\n\n - **Support**: SHOULD be supported, i.e., SHOULD NOT be :val:`null`. Is REQUIRED in this implementation, i.e., MUST NOT be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL. If supported, filters MAY support only a subset of comparison operators.\n - It MUST be a list of length N times 3, where N is the number of sites in the structure.\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 - If a component of the position is unknown, the :val:`null` value should be provided instead (see section `Properties with unknown value`_).\n Otherwise, it should be a float value, expressed in angstrom (\u00c5).\n If at least one of the coordinates is unknown, the correct flag in the list property `structure_features`_ MUST be set.\n - **Notes**: (for implementers) While this is unrelated to this OPTIMADE specification: If you decide to store internally the :property: `cartesian_site_positions` as a float array, you might want to represent :val:`null` values with :field-val:`NaN` values.\n The latter being valid float numbers in the IEEE 754 standard in `IEEE 754-1985 `__ and in the updated version `IEEE 754-2008 `__.\n\n- **Examples**:\n\n - :val:`[[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." + "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." }, "nsites": { "title": "Nsites", "type": "integer", - "description": "An integer specifying the length of the :property:`cartesian_site_positions` property.\n- **Type**: integer\n- **Requirements/Conventions**:\n\n - **Support**: SHOULD be supported, i.e., SHOULD NOT be :val:`null`. Is REQUIRED in this implementation, i.e., MUST NOT be :val:`null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter operators.\n\n- **Examples**:\n\n - :val:`42`\n\n- **Query examples**:\n\n - Match only structures with exactly 4 sites: :filter:`nsites=4`\n - Match structures that have between 2 and 7 sites: :filter:`nsites>=2 AND nsites<=7`" + "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`" }, "species": { "title": "Species", @@ -3067,7 +3067,7 @@ "items": { "$ref": "#/components/schemas/Species" }, - "description": "A list describing the species of the sites of this structure. Species can be pure chemical elements, or virtual-crystal atoms representing a statistical occupation of a given site by multiple chemical elements.\n- **Type**: list of dictionary with keys:\n\n - :property:`name`: string (REQUIRED)\n - :property:`chemical_symbols`: list of strings (REQUIRED)\n - :property:`concentration`: list of float (REQUIRED)\n - :property:`mass`: float (OPTIONAL)\n - :property:`original_name`: string (OPTIONAL).\n\n- **Requirements/Conventions**:\n\n - **Support**: SHOULD be supported, i.e., SHOULD NOT be :val:`null`. Is REQUIRED in this implementation, i.e., MUST NOT be :val:`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\n - **name**: REQUIRED; gives the name of the species; the **name** value MUST be unique in the :property:`species` list;\n\n - **chemical_symbols**: REQUIRED; MUST be a list of strings of all chemical elements composing this species.\n\n - It MUST be one of the following:\n\n - a valid chemical-element name, or\n - the special value :val:`\"X\"` to represent a non-chemical element, or\n - the special value :val:`\"vacancy\"` to represent that this site has a non-zero probability of having a vacancy (the respective probability is indicated in the :property:`concentration` list, see below).\n\n - If any one entry in the :property:`species` list has a :property:`chemical_symbols` list that is longer than 1 element, the correct flag MUST be set in the list :property:`structure_features` (see property `structure_features`_).\n\n - **concentration**: REQUIRED; MUST be a list of floats, with same length as :property:`chemical_symbols`. 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 :val:`1/3` and :val:`2/3`, the concentration might look something like :val:`[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 site (even of the same species).\n\n - **mass**: OPTIONAL. If present MUST be a float expressed in a.m.u.\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 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., :val:`\"Ti\"` for titanium, :val:`\"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 :val:`{\"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\n - :val:`[ {\"name\": \"Ti\", \"chemical_symbols\": [\"Ti\"], \"concentration\": [1.0]} ]`: any site with this species is occupied by a Ti atom.\n - :val:`[ {\"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 - :val:`[ {\"name\": \"BaCa\", \"chemical_symbols\": [\"vacancy\", \"Ba\", \"Ca\"], \"concentration\": [0.05, 0.45, 0.5], \"mass\": 88.5} ]`: 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 - :val:`[ {\"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 - :val:`[ {\"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." + "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 - `mass`: float (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 name, 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` (see property [structure_features](#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](#structure_features) property MUST include the string `site_attachments`.\n\n - **mass**: OPTIONAL. If present MUST be a float expressed in a.m.u.\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](#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\": 88.5} ]`: 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." }, "species_at_sites": { "title": "Species At Sites", @@ -3075,7 +3075,7 @@ "items": { "type": "string" }, - "description": "Name of the species at each site (where values for sites are specified with the same order of the property `cartesian_site_positions`_).\n The properties of the species are found in the property `species`_.\n- **Type**: list of strings.\n- **Requirements/Conventions**:\n\n - **Support**: SHOULD be supported, i.e., SHOULD NOT be :val:`null`. Is REQUIRED in this implementation, i.e., MUST NOT be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL. 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 MUST have a unique name.\n - Each species name mentioned in the :property:`species_at_sites` list MUST be described in the list property `species`_ (i.e. for each value in the :property:`species_at_sites` list there MUST exist exactly one dictionary in the :property:`species` list with the :property:`name` attribute equal to the corresponding :property:`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\n - :val:`[\"Ti\",\"O2\"]` indicates that the first site is hosting a species labeled :val:`\"Ti\"` and the second a species labeled :val:`\"O2\"`." + "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." }, "assemblies": { "title": "Assemblies", @@ -3083,7 +3083,7 @@ "items": { "$ref": "#/components/schemas/Assembly" }, - "description": "A description of groups of sites that are statistically correlated.\n- **Type**: list of dictionary with keys:\n\n - :property:`sites_in_groups`: list of list of integers (REQUIRED)\n - :property:`group_probabilities`: list of floats (REQUIRED)\n\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 supported, filters MAY support only a subset of comparison operators.\n - If present, the correct flag MUST be set in the list :property:`structure_features` (see property `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\n - **sites_in_groups**: Index of the sites (0-based) that belong to each group for each assembly.\n\n Example: :val:`[[1], [2]]`: two groups, one with the second site, one with the third.\n\n Example: :val:`[[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 :property:`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 :property:`concentration` of each :property:`species`, see property `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\n - :val:`{\"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 - :val:`{\"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\n - Assemblies are essential to represent, for instance, the situation where an atom can statistically occupy two different positions (sites).\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 - 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\n .. code:: jsonc\n\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\n .. code:: jsonc\n\n {\n \"cartesian_site_positions\": [ [0,0,0], [0,0,0], [0,0,0] ],\n \"species_at_sites\": [\"Si\", \"Ge\", \"vac\"],\n \"species\": {\n \"Si\": { \"chemical_symbols\": [\"Si\"], \"concentration\": [1.0] },\n \"Ge\": { \"chemical_symbols\": [\"Ge\"], \"concentration\": [1.0] },\n \"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 - 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 - The probabilities of occurrence of different assemblies are uncorrelated.\n So, for instance in the following case with two assemblies:\n\n .. code:: jsonc\n\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 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)." + "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 \"Si\": { \"chemical_symbols\": [\"Si\"], \"concentration\": [1.0] },\n \"Ge\": { \"chemical_symbols\": [\"Ge\"], \"concentration\": [1.0] },\n \"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)." }, "structure_features": { "title": "Structure Features", @@ -3096,7 +3096,7 @@ "assemblies" ] }, - "description": "A list of strings that flag which special features are used by the structure.\n- **Type**: list of strings\n- **Requirements/Conventions**:\n\n - **Support**: REQUIRED, MUST NOT be :val:`null`.\n - **Query**: MUST be a queryable property. Filters on the list MUST support all mandatory HAS-type queries. 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\n - :val:`disorder`: This flag MUST be present if any one entry in the :property:`species` list has a :property:`chemical_symbols` list that is longer than 1 element.\n - :val:`assemblies`: This flag MUST be present if the property `assemblies`_ is present.\n\n- **Examples**: A structure having implicit atoms and using assemblies: :val:`[\"assemblies\", \"implicit_atoms\"]`" + "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\"]`" } }, "description": "This class contains the Field for the attributes used to represent a structure, e.g. unit cell, atoms, positions." @@ -3432,7 +3432,7 @@ "description": "Warnings must be of type \"warning\"" } }, - "description": "OPTIMADE-specific warning class based on OPTIMADE-specific JSON API Error.\nFrom the specification:\n\n A warning resource object is defined similarly to a JSON API\n error object, but MUST also include the field type, which MUST\n have the value \"warning\". The field detail MUST be present and\n SHOULD contain a non-critical message, e.g., reporting\n unrecognized search attributes or deprecated features.\n\nNote: Must be named \"Warnings\", since \"Warning\" is a built-in Python class." + "description": "OPTIMADE-specific warning class based on OPTIMADE-specific JSON API Error.\n\nFrom the specification:\n\n A warning resource object is defined similarly to a JSON API\n error object, but MUST also include the field type, which MUST\n have the value \"warning\". The field detail MUST be present and\n SHOULD contain a non-critical message, e.g., reporting\n unrecognized search attributes or deprecated features.\n\nNote: Must be named \"Warnings\", since \"Warning\" is a built-in Python class." } } } diff --git a/optimade/models/baseinfo.py b/optimade/models/baseinfo.py index 9ab54e5b4..a7c17ab57 100644 --- a/optimade/models/baseinfo.py +++ b/optimade/models/baseinfo.py @@ -74,7 +74,7 @@ class BaseInfoAttributes(BaseModel): default=False, description="If true, this is an index meta-database base URL (see section Index Meta-Database). " "If this member is not provided, the client MUST assume this is not an index meta-database base URL " - "(i.e., the default is for is_index to be false).", + "(i.e., the default is for `is_index` to be false).", ) @validator("entry_types_by_format", check_fields=False) diff --git a/optimade/models/entries.py b/optimade/models/entries.py index 41fc22280..dd7e59b4a 100644 --- a/optimade/models/entries.py +++ b/optimade/models/entries.py @@ -52,34 +52,32 @@ class EntryResourceAttributes(Attributes): immutable_id: Optional[str] = Field( None, - 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. + 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. + - **Type**: string. -- **Requirements/Conventions**: - - **Support**: OPTIONAL, i.e., MAY be :val:`null`. - - **Query**: MUST be a queryable property with support for all mandatory filter features. +- **Requirements/Conventions**: + - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`. + - **Query**: MUST be a queryable property with support for all mandatory filter features. - **Examples**: - - - :val:`"8bd3e750-b477-41a0-9b11-3a799f21b44f"` - - :val:`"fjeiwoj,54;@=%<>#32"` (Strings that are not URL-safe are allowed.)""", + - `"8bd3e750-b477-41a0-9b11-3a799f21b44f"` + - `"fjeiwoj,54;@=%<>#32"` (Strings that are not URL-safe are allowed.)""", ) last_modified: datetime = Field( ..., description="""Date and time representing when the entry was last modified. + - **Type**: timestamp. -- **Requirements/Conventions**: - - **Support**: SHOULD be supported, i.e., SHOULD NOT be :val:`null`. Is REQUIRED in this implementation, i.e., MUST NOT be :val:`null`. - - **Query**: MUST be a queryable property with support for all mandatory filter features. - - **Response**: REQUIRED in the response unless the query parameter :query-param:`response_fields` is present and does not include this property. +- **Requirements/Conventions**: + - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`. + - **Query**: MUST be a queryable property with support for all mandatory filter features. + - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property. - **Example**: - - - As part of JSON response format: :VAL:`"2007-04-05T14:30Z"` (i.e., encoded as an `RFC 3339 Internet Date/Time Format `__ string.)""", + - 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.)""", ) @@ -87,90 +85,96 @@ class EntryResource(Resource): id: str = Field( ..., - description="""An entry's ID as defined in section `Definition of Terms`_. + description="""An entry's ID as defined in section Definition of Terms. + - **Type**: string. -- **Requirements/Conventions**: - - **Support**: REQUIRED, MUST NOT be :val:`null`. - - **Query**: MUST be a queryable property with support for all mandatory filter features. - - **Response**: REQUIRED in the response. - - See section `Definition of Terms`_. +- **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. - **Examples**: - - - :val:`"db/1234567"` - - :val:`"cod/2000000"` - - :val:`"cod/2000000@1234567"` - - :val:`"nomad/L1234567890"` - - :val:`"42"`""", + - `"db/1234567"` + - `"cod/2000000"` + - `"cod/2000000@1234567"` + - `"nomad/L1234567890"` + - `"42"`""", ) type: str = Field( - ..., description="""The name of the type of an entry. + - **Type**: string. -- **Requirements/Conventions**: - - **Support**: REQUIRED, MUST NOT be :val:`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 :endpoint:`//` under the versioned base URL. +- **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. -- **Example**: :val:`"structures"`""", +- **Example**: `"structures"`""", ) attributes: EntryResourceAttributes = Field( ..., - description="""a dictionary, containing key-value pairs representing the entry's properties, except for type and id. - -Database-provider-specific properties need to include the database-provider-specific prefix -(see appendix `Database-Provider-Specific Namespace Prefixes`_).""", + description="""A dictionary, containing key-value pairs representing the entry's properties, except for `type` and `id`. +Database-provider-specific properties need to include the database-provider-specific prefix (see section on Database-Provider-Specific Namespace Prefixes).""", ) relationships: Optional[EntryRelationships] = Field( None, - description="""a dictionary containing references to other entries according to the description in section `Relationships`_ -encoded as `JSON API Relationships `__. -The OPTIONAL human-readable description of the relationship MAY be provided in the :field:`description` field inside the :field:`meta` dictionary.""", + 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). +The 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.""", ) class EntryInfoProperty(BaseModel): - description: str = Field(..., description="description of the entry property") + description: str = Field( + ..., description="A human-readable description of the entry property" + ) unit: Optional[str] = Field( - None, description="the physical unit of the entry property" + None, + description="""The physical unit of the entry property. +It is RECOMMENDED that non-standard (non-SI) units are described in the description for the property.""", ) sortable: Optional[bool] = Field( 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`.", + 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`.""", ) type: Optional[DataType] = Field( None, - description="Data type of value. Must equal a valid OPTIMADE data type as listed and defined under 'Data types'.", + description="""String. +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`. +Data type of value. Must equal a valid OPTIMADE data type as listed and defined under 'Data types'.""", ) class EntryInfoResource(BaseModel): - formats: List[str] = Field(..., description="list of available output formats.") + formats: List[str] = Field( + ..., description="List of output formats available for this type of entry." + ) - description: str = Field(..., description="description of the entry") + description: str = Field(..., description="Description of the entry") properties: Dict[str, EntryInfoProperty] = Field( ..., - description="a dictionary describing queryable properties for this " - "entry type, where each key is a property ID.", + description="A dictionary describing queryable properties for this entry type, where each key is a property name.", ) output_fields_by_format: Dict[str, List[str]] = Field( ..., - description="a dictionary of available output fields for this entry " - "type, where the keys are the values of the `formats` list " - "and the values are the keys of the `properties` dictionary.", + description="Dictionary of available output fields for this entry type, where the keys are the values of the `formats` list and the values are the keys of the `properties` dictionary.", ) diff --git a/optimade/models/index_metadb.py b/optimade/models/index_metadb.py index 701fda706..26b366f85 100644 --- a/optimade/models/index_metadb.py +++ b/optimade/models/index_metadb.py @@ -30,7 +30,7 @@ class IndexInfoAttributes(BaseInfoAttributes): const=True, description="If true, this is an index meta-database base URL (see section Index Meta-Database). " "If this member is not provided, the client MUST assume this is not an index meta-database base URL " - "(i.e., the default is for is_index to be false).", + "(i.e., the default is for `is_index` to be false).", ) @@ -45,8 +45,8 @@ class IndexRelationship(BaseModel): data: Union[None, RelatedLinksResource] = Field( ..., - description="JSON API resource linkage. It MUST be either null or contain " - "a single Links identifier object with the fields 'id' and 'type'", + description="""JSON API resource linkage. +It MUST be either `null` or contain a single Links identifier object with the fields `id` and `type`""", ) @@ -56,8 +56,6 @@ class IndexInfoResource(BaseInfoResource): attributes: IndexInfoAttributes = Field(...) relationships: Union[None, Dict[DefaultRelationship, IndexRelationship]] = Field( ..., - description="Reference to the child identifier object under the links endpoint " - "that the provider has chosen as their 'default' OPTIMADE API database. " - "A client SHOULD present this database as the first choice when an end-user " - "chooses this provider.", + description="""Reference to the child identifier object under the `links` endpoint that the provider has chosen as their 'default' OPTIMADE API database. +A client SHOULD present this database as the first choice when an end-user chooses this provider.""", ) diff --git a/optimade/models/jsonapi.py b/optimade/models/jsonapi.py index 29751c398..e5ca557b9 100644 --- a/optimade/models/jsonapi.py +++ b/optimade/models/jsonapi.py @@ -137,8 +137,11 @@ class BaseResource(BaseModel): class RelationshipLinks(BaseModel): - """A resource object **MAY** contain references to other resource objects (\"relationships\"). - Relationships may be to-one or to-many. Relationships can be specified by including a member in a resource's links object.""" + """ A resource object **MAY** contain references to other resource objects (\"relationships\"). + Relationships may be to-one or to-many. + Relationships can be specified by including a member in a resource's links object. + + """ self: Optional[Union[AnyUrl, Link]] = Field(None, description="A link to itself") related: Optional[Union[AnyUrl, Link]] = Field( @@ -237,7 +240,7 @@ def check_illegal_attributes_fields(cls, values): class Resource(BaseResource): - """Resource objects appear in a JSON:API document to represent resources.""" + """Resource objects appear in a JSON API document to represent resources.""" links: Optional[ResourceLinks] = Field( None, description="a links object containing links related to the resource." @@ -252,7 +255,7 @@ class Resource(BaseResource): ) relationships: Optional[Relationships] = Field( None, - description="a relationships object describing relationships between the resource and other JSON:API resources.", + description="a relationships object describing relationships between the resource and other JSON API resources.", ) diff --git a/optimade/models/links.py b/optimade/models/links.py index 1d48355e1..faf347792 100644 --- a/optimade/models/links.py +++ b/optimade/models/links.py @@ -41,13 +41,11 @@ class LinksResourceAttributes(Attributes): name: str = Field( ..., - description="Human-readable name for the OPTIMADE API implementation " - "a client may provide in a list to an end-user.", + description="Human-readable name for the OPTIMADE API implementation, e.g., for use in clients to show the name to the end-user.", ) description: str = Field( ..., - description="Human-readable description for the OPTIMADE API implementation " - "a client may provide in a list to an end-user.", + description="Human-readable description for the OPTIMADE API implementation, e.g., for use in clients to show a description to the end-user.", ) base_url: Union[AnyUrl, Link, None] = Field( ..., @@ -61,27 +59,28 @@ class LinksResourceAttributes(Attributes): link_type: LinkType = Field( ..., - description="The link type of the represented resource in relation to this implementation. MUST be one of these values: 'child', 'root', 'external', 'providers'.", + description="""The link type of the represented resource in relation to this implementation. +MUST be one of these values: 'child', 'root', 'external', 'providers'.""", ) aggregate: Optional[Aggregate] = Field( "ok", description="""A string indicating whether a client that is following links to aggregate results from different OPTIMADE implementations should follow this link or not. -This flag SHOULD NOT be indicated for links where :property:`link_type` is not :val:`child`. +This flag SHOULD NOT be indicated for links where `link_type` is not `child`. -If not specified, clients MAY assume that the value is :val:`ok`. -If specified, and the value is anything different than :val:`ok`, the client MUST assume that the server is suggesting not to follow the link during aggregation by default (also if the value is not among the known ones, in case a future specification adds new accepted values). +If not specified, clients MAY assume that the value is `ok`. +If specified, and the value is anything different than `ok`, the client MUST assume that the server is suggesting not to follow the link during aggregation by default (also if the value is not among the known ones, in case a future specification adds new accepted values). Specific values indicate the reason why the server is providing the suggestion. -A client MAY follow the link anyway if it has reason to do so (e.g., if the client is looking for all test databases, it MAY follow the links marked with :property:`aggregate`=:val:`test`). +A client MAY follow the link anyway if it has reason to do so (e.g., if the client is looking for all test databases, it MAY follow the links marked with `aggregate`=`test`). -If specified, it MUST be one of the values listed in section Link Aggregate Options.""", +If specified, it MUST be one of the values listed in section [Link Aggregate Options](#link-aggregate-options).""", ) no_aggregate_reason: Optional[str] = Field( None, description="""An OPTIONAL human-readable string indicating the reason for suggesting not to aggregate results following the link. -It SHOULD NOT be present if :property:`aggregate`=:val:`ok`.""", +It SHOULD NOT be present if `aggregate`=`ok`.""", ) @@ -96,8 +95,7 @@ class LinksResource(EntryResource): attributes: LinksResourceAttributes = Field( ..., - description="a dictionary containing key-value pairs representing the " - "entry's properties.", + description="A dictionary containing key-value pairs representing the entry's properties.", ) @root_validator(pre=True) diff --git a/optimade/models/optimade_json.py b/optimade/models/optimade_json.py index d64bf8d7e..54c7f6a31 100644 --- a/optimade/models/optimade_json.py +++ b/optimade/models/optimade_json.py @@ -133,6 +133,7 @@ class OptimadeError(jsonapi.Error): class Warnings(OptimadeError): """OPTIMADE-specific warning class based on OPTIMADE-specific JSON API Error. + From the specification: A warning resource object is defined similarly to a JSON API @@ -142,6 +143,7 @@ class Warnings(OptimadeError): unrecognized search attributes or deprecated features. Note: Must be named "Warnings", since "Warning" is a built-in Python class. + """ type: str = Field( @@ -236,24 +238,23 @@ class ResponseMeta(jsonapi.Meta): api_version: str = Field( ..., - description="a string containing the version of the API " - "implementation, e.g. v0.9.5", + description="a string containing the version of the API implementation, e.g. v0.9.5", ) time_stamp: datetime = Field( ..., - description="a string containing the date and time at which the query was exexcuted", + description="a timestamp containing the date and time at which the query was executed.", ) data_returned: int = Field( ..., - description="an integer containing the number of data objects " - "returned for the query.", + description="an integer containing the total number of data resource objects returned for the current `filter` query, independent of pagination.", ge=0, ) more_data_available: bool = Field( - ..., description="`false` if all data has been returned, and `true` " "if not." + ..., + description="`false` if all data resource objects for this `filter` query have been returned in the response or if it is the last page of a paginated response, and `true` otherwise.", ) provider: Provider = Field( @@ -262,8 +263,7 @@ class ResponseMeta(jsonapi.Meta): data_available: Optional[int] = Field( None, - description="an integer containing the total number of data " - "objects available in the database", + description="an integer containing the total number of data resource objects available in the database for the endpoint.", ) last_id: Optional[str] = Field( @@ -280,11 +280,11 @@ class ResponseMeta(jsonapi.Meta): warnings: Optional[List[Warnings]] = Field( None, - description="List of warning resource objects representing non-critical errors or warnings. " - "A warning resource object is defined similarly to a JSON API error object, but MUST also include the field type, " - 'which MUST have the value "warning". The field detail MUST be present and SHOULD contain a non-critical message, ' - "e.g., reporting unrecognized search attributes or deprecated features. The field status, representing a HTTP " - "response status code, MUST NOT be present for a warning resource object. This is an exclusive field for error resource objects.", + description="""A list of warning resource objects representing non-critical errors or warnings. +A warning resource object is defined similarly to a [JSON API error object](http://jsonapi.org/format/1.0/#error-objects), but MUST also include the field `type`, which MUST have the value `"warning"`. +The field `detail` MUST be present and SHOULD contain a non-critical message, e.g., reporting unrecognized search attributes or deprecated features. +The field `status`, representing a HTTP response status code, MUST NOT be present for a warning resource object. +This is an exclusive field for error resource objects.""", uniqueItems=True, ) diff --git a/optimade/models/references.py b/optimade/models/references.py index 5d07b4807..9f24dfcc6 100644 --- a/optimade/models/references.py +++ b/optimade/models/references.py @@ -111,41 +111,35 @@ class ReferenceResourceAttributes(EntryResourceAttributes): class ReferenceResource(EntryResource): - """ The :entry:`references` entries describe bibliographic references. -The following properties are used to provide the bibliographic details: + """ The `references` entries describe bibliographic references. + The following properties are used to provide the bibliographic details: + + - **address**, **annote**, **booktitle**, **chapter**, **crossref**, **edition**, **howpublished**, **institution**, **journal**, **key**, **month**, **note**, **number**, **organization**, **pages**, **publisher**, **school**, **series**, **title**, **volume**, **year**: meanings of these properties match the [BibTeX specification](http://bibtexml.sourceforge.net/btxdoc.pdf), values are strings; + - **bib_type**: type of the reference, corresponding to **type** property in the BibTeX specification, value is string; + - **authors** and **editors**: lists of *person objects* which are dictionaries with the following keys: + - **name**: Full name of the person, REQUIRED. + - **firstname**, **lastname**: Parts of the person's name, OPTIONAL. + - **doi** and **url**: values are strings. + - **Requirements/Conventions**: + - **Support**: OPTIONAL support in implementations, i.e., any of the properties MAY be `null`. + - **Query**: Support for queries on any of these properties is OPTIONAL. + If supported, filters MAY support only a subset of comparison operators. + - Every references entry MUST contain at least one of the properties. -- **address**, **annote**, **booktitle**, **chapter**, **crossref**, **edition**, **howpublished**, **institution**, **journal**, **key**, **month**, - **note**, **number**, **organization**, **pages**, **publisher**, **school**, **series**, **title**, **type**, **volume**, **year**: - Meanings of these properties match the `BibTeX specification `__, values are strings; - -- **authors** and **editors**: lists of *person objects* which are dictionaries with the following keys: - - - **name**: Full name of the person, REQUIRED. - - **firstname**, **lastname**: Parts of the person's name, OPTIONAL. - -- **doi** and **url**: values are strings. - -- **Requirements/Conventions**: - - - **Support**: OPTIONAL, i.e., any of the properties MAY be :val:`null`. - - **Query**: Support for queries on any of these properties is OPTIONAL. - If supported, filters MAY support only a subset of comparison operators. - - Every references entry MUST contain at least one of the properties.""" + """ type: str = Field( default="references", const=True, - description="""The name of the type of an entry. Any entry MUST be able to be fetched using the `base URL `_ type and ID at the url :endpoint:`//`. + description="""The name of the type of an entry. - **Type**: string. - **Requirements/Conventions**: - - - **Support**: REQUIRED, MUST NOT be :val:`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 :endpoint:`//` under the versioned base URL. - -- **Example**: :val:`"structures"`""", + - **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. +- **Example**: `"structures"`""", ) attributes: ReferenceResourceAttributes diff --git a/optimade/models/structures.py b/optimade/models/structures.py index 4f27ce724..c11ed691a 100644 --- a/optimade/models/structures.py +++ b/optimade/models/structures.py @@ -45,44 +45,47 @@ class StructureFeatures(Enum): class Species(BaseModel): - """A list describing the species of the sites of this structure. - Species can be pure chemical elements, or virtual-crystal atoms representing a statistical occupation of a given site by multiple chemical elements. + """ A list describing the species of the sites of this structure. + Species 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). - **Examples**: - - :val:`[ {"name": "Ti", "chemical_symbols": ["Ti"], "concentration": [1.0]} ]`: any site with this species is occupied by a Ti atom. - - :val:`[ {"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. - - :val:`[ {"name": "BaCa", "chemical_symbols": ["vacancy", "Ba", "Ca"], "concentration": [0.05, 0.45, 0.5], "mass": 88.5} ]`: 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. - - :val:`[ {"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. - - :val:`[ {"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. + - `[ {"name": "Ti", "chemical_symbols": ["Ti"], "concentration": [1.0]} ]`: any site with this species is occupied by a Ti atom. + - `[ {"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. + - `[ {"name": "BaCa", "chemical_symbols": ["vacancy", "Ba", "Ca"], "concentration": [0.05, 0.45, 0.5], "mass": 88.5} ]`: 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. + - `[ {"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. + - `[ {"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. + - `[ {"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. """ name: str = Field( ..., - decsription="""REQUIRED; gives the name of the species; the **name** value MUST be unique in the :property:`species` list;""", + decsription="""Gives the name of the species; the **name** value MUST be unique in the `species` list.""", ) chemical_symbols: List[str] = Field( ..., - description="""MUST be a list of strings of all chemical elements composing this species. + 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: -- It MUST be one of the following: +- a valid chemical-element name, or +- the special value `"X"` to represent a non-chemical element, or +- 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). - - a valid chemical-element name, or - - the special value :val:`"X"` to represent a non-chemical element, or - - the special value :val:`"vacancy"` to represent that this site has a non-zero probability of having a vacancy (the respective probability is indicated in the :property:`concentration` list, see below). - -- If any one entry in the :property:`species` list has a :property:`chemical_symbols` list that is longer than 1 element, the correct flag MUST be set in the list :property:`structure_features` (see property `structure_features`_).""", +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` (see property [structure_features](#structure_features)).""", ) concentration: List[float] = Field( ..., - description="""MUST be a list of floats, with same length as :property:`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: + 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: - - Numerical errors when representing float numbers in fixed precision, e.g. for two chemical symbols with concentrations :val:`1/3` and :val:`2/3`, the concentration might look something like :val:`[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. - - 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. +- 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. +- 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. Note that concentrations are uncorrelated between different site (even of the same species).""", ) @@ -97,8 +100,7 @@ class Species(BaseModel): None, 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. -Note: With regards to "source database", we refer to the immediate source being queried via the OPTIMADE API implementation. -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`_).""", +Note: With regards to "source database", we refer to the immediate source being queried via the OPTIMADE API implementation.""", ) attached: Optional[List[str]] = Field( @@ -163,12 +165,11 @@ class Assembly(BaseModel): - **Examples** (for each entry of the assemblies list): - - :val:`{"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. - Statistically, 30 % of the times the first site is present, while 70 % of the times the second site is present. - - :val:`{"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. - The second group is formed by the fourth site. - Sites of the first group (the second and the third) are never present at the same time as the fourth site. - 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). + - `{"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. + Statistically, 30 % of the times the first site is present, while 70 % of the times the second site is present. + - `{"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. + The second group is formed by the fourth site. Sites of the first group (the second and the third) are never present at the same time as the fourth site. + 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). """ @@ -176,16 +177,17 @@ class Assembly(BaseModel): ..., description="""Index of the sites (0-based) that belong to each group for each assembly. -Example: :val:`[[1], [2]]`: two groups, one with the second site, one with the third. -Example: :val:`[[1,2], [3]]`: one group with the second and third site, one with the fourth.""", +- **Examples**: + - `[[1], [2]]`: two groups, one with the second site, one with the third. + - `[[1,2], [3]]`: one group with the second and third site, one with the fourth.""", ) group_probabilities: List[float] = Field( ..., - description="""Statistical probability of each group. It MUST have the same length as :property:`sites_in_groups`. + description="""Statistical probability of each group. It MUST have the same length as `sites_in_groups`. It SHOULD sum to one. See below for examples of how to specify the probability of the occurrence of a vacancy. -The possible reasons for the values not to sum to one are the same as already specified above for the :property:`concentration` of each :property:`species`, see property `species`_.""", +The possible reasons for the values not to sum to one are the same as already specified above for the `concentration` of each `species`, see property [species](#species).""", ) @validator("sites_in_groups") @@ -214,209 +216,204 @@ class StructureResourceAttributes(EntryResourceAttributes): elements: List[str] = Field( ..., description="""Names of the different elements present in the structure. + - **Type**: list of strings. -- **Requirements/Conventions**: - - **Support**: SHOULD be supported, i.e., SHOULD NOT be :val:`null`. Is REQUIRED in this implementation, i.e., MUST NOT be :val:`null`. - - **Query**: MUST be a queryable property with support for all mandatory filter operators. - - The strings are the chemical symbols, written as uppercase letter plus optional lowercase letters. - - The order MUST be alphabetical. - - Note: This may not contain the "x" that is suggested in chemical_symbols for the :property:`species` property. +- **Requirements/Conventions**: + - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`. + - **Query**: MUST be a queryable property with support for all mandatory filter features. + - The strings are the chemical symbols, i.e., either a single uppercase letter or an uppercase letter followed by a number of lowercase letters. + - The order MUST be alphabetical. + - 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). - **Examples**: - - - :val:`["Si"]` - - :val:`["Al","O","Si"]` + - `["Si"]` + - `["Al","O","Si"]` - **Query examples**: - - A filter that matches all records of structures that contain Si, Al **and** O, and possibly other elements: :filter:`elements HAS ALL "Si", "Al", "O"`. - - To match structures with exactly these three elements, use :filter:`elements HAS ALL "Si", "Al", "O" AND LENGTH elements = 3`.""", + - A filter that matches all records of structures that contain Si, Al **and** O, and possibly other elements: `elements HAS ALL "Si", "Al", "O"`. + - To match structures with exactly these three elements, use `elements HAS ALL "Si", "Al", "O" AND elements LENGTH 3`.""", ) nelements: int = Field( ..., description="""Number of different elements in the structure as an integer. + - **Type**: integer + - **Requirements/Conventions**: + - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`. + - **Query**: MUST be a queryable property with support for all mandatory filter features. - - **Support**: SHOULD be supported, i.e., SHOULD NOT be :val:`null`. Is REQUIRED in this implementation, i.e., MUST NOT be :val:`null`. - - **Query**: MUST be a queryable property with support for all mandatory filter operators. +- **Example**: `3` -- **Example**: :val:`3` - **Querying**: - - - Note: queries on this property can equivalently be formulated using :filter-fragment:`LENGTH elements`. - - A filter that matches structures that have exactly 4 elements: :filter:`nelements=4`. - - A filter that matches structures that have between 2 and 7 elements: :filter:`nelements>=2 AND nelements<=7`.""", + - Note: queries on this property can equivalently be formulated using `elements LENGTH`. + - A filter that matches structures that have exactly 4 elements: `nelements=4`. + - A filter that matches structures that have between 2 and 7 elements: `nelements>=2 AND nelements<=7`.""", ) elements_ratios: List[float] = Field( ..., description="""Relative proportions of different elements in the structure. + - **Type**: list of floats -- **Requirements/Conventions**: - - **Support**: SHOULD be supported, i.e., SHOULD NOT be :val:`null`. Is REQUIRED in this implementation, i.e., MUST NOT be :val:`null`. - - **Query**: MUST be a queryable property with support for all mandatory filter operators. - - Composed by the proportions of elements in the structure as a list of floating point numbers. - - The sum of the numbers MUST be 1.0 (within floating point accuracy) +- **Requirements/Conventions**: + - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`. + - **Query**: MUST be a queryable property with support for all mandatory filter features. + - Composed by the proportions of elements in the structure as a list of floating point numbers. + - The sum of the numbers MUST be 1.0 (within floating point accuracy) - **Examples**: - - - :val:`[1.0]` - - :val:`[0.3333333333333333, 0.2222222222222222, 0.4444444444444444]` + - `[1.0]` + - `[0.3333333333333333, 0.2222222222222222, 0.4444444444444444]` - **Query examples**: - - - Note: useful filters can be formulated using the set operator syntax for correlated values. However, since the values are floating point values, the use of equality comparisons is generally not recommended. - - A filter that matches structures where approximately 1/3 of the atoms in the structure are the element Al is: :filter:`elements:elements_ratios HAS ALL "Al":>0.3333, "Al":<0.3334`.""", + - Note: Useful filters can be formulated using the set operator syntax for correlated values. + However, since the values are floating point values, the use of equality comparisons is generally inadvisable. + - 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`.""", ) chemical_formula_descriptive: str = Field( ..., description="""The chemical formula for a structure as a string in a form chosen by the API implementation. + - **Type**: string -- **Requirements/Conventions**: - - **Support**: SHOULD be supported, i.e., SHOULD NOT be :val:`null`. Is REQUIRED in this implementation, i.e., MUST NOT be :val:`null`. - - **Query**: MUST be a queryable property with support for all mandatory filter operators. - - 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. - - The string SHOULD be arithmetically consistent with the element ratios in the :property:`chemical_formula_reduced` property. - - 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 `__. +- **Requirements/Conventions**: + - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`. + - **Query**: MUST be a queryable property with support for all mandatory filter features. + - 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. + - The string SHOULD be arithmetically consistent with the element ratios in the `chemical_formula_reduced` property. + - 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). - **Examples**: - - - :val:`"(H2O)2 Na"` - - :val:`"NaCl"` - - :val:`"CaCO3"` - - :val:`"CCaO3"` - - :val:`"(CH3)3N+ - [CH2]2-OH = Me3N+ - CH2 - CH2OH"` + - `"(H2O)2 Na"` + - `"NaCl"` + - `"CaCO3"` + - `"CCaO3"` + - `"(CH3)3N+ - [CH2]2-OH = Me3N+ - CH2 - CH2OH"` - **Query examples**: - - - Note: the free-form nature of this property is likely to make queries on it across different databases inconsistent. - - A filter that matches an exactly given formula: :filter:`chemical_formula_descriptive="(H2O)2 Na"`. - - A filter that does a partial match: :filter:`chemical_formula_descriptive CONTAINS "H2O"`.""", + - Note: the free-form nature of this property is likely to make queries on it across different databases inconsistent. + - A filter that matches an exactly given formula: `chemical_formula_descriptive="(H2O)2 Na"`. + - A filter that does a partial match: `chemical_formula_descriptive CONTAINS "H2O"`.""", ) chemical_formula_reduced: str = Field( ..., description="""The reduced chemical formula for a structure as a string with element symbols and integer chemical proportion numbers. - The proportion number MUST be omitted if it is 1. +The proportion number MUST be omitted if it is 1. + - **Type**: string -- **Requirements/Conventions**: - - **Support**: SHOULD be supported, i.e., SHOULD NOT be :val:`null`. Is REQUIRED in this implementation, i.e., MUST NOT be :val:`null`. - - **Query**: MUST be a queryable property. - However, support for filters using partial string matching with this property is OPTIONAL (i.e., BEGINS WITH, ENDS WITH, and CONTAINS). - Intricate querying on formula components are instead recommended to be formulated using set-type filter operators on the multi valued :property:`elements` and :property:`elements_proportions` properties. - - Element names MUST have proper capitalization (e.g., :val:`"Si"`, not :VAL:`"SI"` for "silicon"). - - Elements MUST be placed in alphabetical order, followed by their integer chemical proportion number. - - For structures with no partial occupation, the chemical proportion numbers are the smallest integers for which the chemical proportion is exactly correct. - - 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. - - No spaces or separators are allowed. +- **Requirements/Conventions**: + - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`. + - **Query**: MUST be a queryable property. + However, support for filters using partial string matching with this property is OPTIONAL (i.e., BEGINS WITH, ENDS WITH, and CONTAINS). + 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. + - Element names MUST have proper capitalization (e.g., `"Si"`, not `"SI"` for "silicon"). + - Elements MUST be placed in alphabetical order, followed by their integer chemical proportion number. + - For structures with no partial occupation, the chemical proportion numbers are the smallest integers for which the chemical proportion is exactly correct. + - 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. + - No spaces or separators are allowed. - **Examples**: - - - :val:`"H2NaO"` - - :val:`"ClNa"` - - :val:`"CCaO3"` + - `"H2NaO"` + - `"ClNa"` + - `"CCaO3"` - **Query examples**: - - - A filter that matches an exactly given formula is :filter:`chemical_formula_reduced="H2NaO"`.""", + - A filter that matches an exactly given formula is `chemical_formula_reduced="H2NaO"`.""", ) chemical_formula_hill: Optional[str] = Field( None, - description="""The chemical formula for a structure in `Hill form `__ with element symbols followed by integer chemical proportion numbers. - The proportion number MUST be omitted if it is 1. + 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. + - **Type**: string -- **Requirements/Conventions**: - - **Support**: OPTIONAL, i.e., MAY be :val:`null`. - - **Query**: Support for queries on these properties are OPTIONAL. If supported, only a subset of filter operators MAY be supported. - - 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. - For example, if the structure is a repeating unit cell with four hydrogens and four oxygens that represents two hydroperoxide molecules, :property:`chemical_formula_hill` is :val:`"H2O2"` (i.e., not :val:`"HO"`, nor :val:`"H4O4"`). - - If the chemical insight needed to ascribe a Hill formula to the system is not present, the property MUST be handled as unset. - - Element names MUST have proper capitalization (e.g., :val:`"Si"`, not :VAL:`"SI"` for "silicon"). - - Elements MUST be placed in `Hill order `__, followed by their integer chemical proportion number. - Hill order means: if carbon is present, it is placed first, and if also present, hydrogen is placed second. - After that, all other elements are ordered alphabetically. - If carbon is not present, all elements are ordered alphabetically. - - 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. - - No spaces or separators are allowed. +- **Requirements/Conventions**: + - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`. + - **Query**: Support for queries on this property is OPTIONAL. + If supported, only a subset of the filter features MAY be supported. + - 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. + 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"`). + - If the chemical insight needed to ascribe a Hill formula to the system is not present, the property MUST be handled as unset. + - Element names MUST have proper capitalization (e.g., `"Si"`, not `"SI"` for "silicon"). + - Elements MUST be placed in [Hill order](https://dx.doi.org/10.1021/ja02046a005), followed by their integer chemical proportion number. + Hill order means: if carbon is present, it is placed first, and if also present, hydrogen is placed second. + After that, all other elements are ordered alphabetically. + If carbon is not present, all elements are ordered alphabetically. + - 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. + - No spaces or separators are allowed. - **Examples**: - - :val:`"H2O2"` + - `"H2O2"` - **Query examples**: - - - A filter that matches an exactly given formula is :filter:`chemical_formula_hill="H2O2"`.""", + - A filter that matches an exactly given formula is `chemical_formula_hill="H2O2"`.""", ) chemical_formula_anonymous: str = Field( ..., - description="""The anonymous formula is the :property:`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. + 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. + - **Type**: string -- **Requirements/Conventions**: - - **Support**: SHOULD be supported, i.e., SHOULD NOT be :val:`null`. Is REQUIRED in this implementation, i.e., MUST NOT be :val:`null`. - - **Query**: MUST be a queryable property. However, support for filters using partial string matching with this property is OPTIONAL (i.e., BEGINS WITH, ENDS WITH, and CONTAINS). +- **Requirements/Conventions**: + - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`. + - **Query**: MUST be a queryable property. + However, support for filters using partial string matching with this property is OPTIONAL (i.e., BEGINS WITH, ENDS WITH, and CONTAINS). - **Examples**: - - - :val:`"A2B"` - - :val:`"A42B42C16D12E10F9G5"` + - `"A2B"` + - `"A42B42C16D12E10F9G5"` - **Querying**: - - A filter that matches an exactly given formula is :filter:`chemical_formula_anonymous="A2B"`.""", + - A filter that matches an exactly given formula is `chemical_formula_anonymous="A2B"`.""", ) dimension_types: Tuple[Periodicity, Periodicity, Periodicity] = Field( ..., description="""List of three integers. - For each of the three directions indicated by the three lattice vectors (see property `lattice_vectors`_). - This list indicates if the direction is periodic (value :val:`1`) or non-periodic (value :val:`0`). - Note: the elements in this list each refer to the direction of the corresponding entry in property `lattice_vectors`_ and *not* the Cartesian x, y, z directions. +For 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`). +Note: 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. + - **Type**: list of integers. -- **Requirements/Conventions**: - - **Support**: SHOULD be supported, i.e., SHOULD NOT be :val:`null`. Is REQUIRED in this implementation, i.e., MUST NOT be :val:`null`. - - **Query**: MUST be a queryable property. Support for equality comparison is REQUIRED, support for other comparison operators are OPTIONAL. - - MUST be a list of length 3. - - Each integer element MUST assume only the value 0 or 1. +- **Requirements/Conventions**: + - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`. + - **Query**: Support for queries on this property is OPTIONAL. + - MUST be a list of length 3. + - Each integer element MUST assume only the value 0 or 1. - **Examples**: - - - For a molecule: :val:`[0, 0, 0]` - - For a wire along the direction specified by the third lattice vector: :val:`[0, 0, 1]` - - For a 2D surface/slab, periodic on the plane defined by the first and third lattice vectors: :val:`[1, 0, 1]` - - For a bulk 3D system: :val:`[1, 1, 1]`""", + - For a molecule: `[0, 0, 0]` + - For a wire along the direction specified by the third lattice vector: `[0, 0, 1]` + - For a 2D surface/slab, periodic on the plane defined by the first and third lattice vectors: `[1, 0, 1]` + - For a bulk 3D system: `[1, 1, 1]`""", ) nperiodic_dimensions: Optional[int] = Field( None, - description="""An integer specifying the number of periodic dimensions in the structure, equivalent to the number of non-zero entries in :property:`dimension_types`. + description="""An integer specifying the number of periodic dimensions in the structure, equivalent to the number of non-zero entries in `dimension_types`. + - **Type**: integer -- **Requirements/Conventions**: - - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be :val:`null`. - - **Query**: MUST be a queryable property with support for all mandatory filter features. - - 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. - - 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. +- **Requirements/Conventions**: + - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`. + - **Query**: MUST be a queryable property with support for all mandatory filter features. + - 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. + - 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. - **Examples**: - - - :val:`2` should be indicated in cases where :property:`dimension_types` is any of :val:`[1, 1, 0]`, :val:`[1, 0, 1]`, :val:`[0, 1, 1]`. + - `2` should be indicated in cases where `dimension_types` is any of `[1, 1, 0]`, `[1, 0, 1]`, `[0, 1, 1]`. - **Query examples**: - - - Match only structures with exactly 3 periodic dimensions: :filter:`nperiodic_dimensions=3` - - Match all structures with 2 or fewer periodic dimensions: :filter:`nperiodic_dimensions<=2`""", + - Match only structures with exactly 3 periodic dimensions: `nperiodic_dimensions=3` + - Match all structures with 2 or fewer periodic dimensions: `nperiodic_dimensions<=2`""", ) lattice_vectors: Optional[ @@ -424,275 +421,279 @@ class StructureResourceAttributes(EntryResourceAttributes): ] = Field( None, description="""The three lattice vectors in Cartesian coordinates, in ångström (Å). -- **Type**: list of list of floats. -- **Requirements/Conventions**: - - **Support**: SHOULD be supported, i.e., SHOULD NOT be :val:`null`. Is REQUIRED in this implementation, i.e., MUST NOT be :val:`null`. - - **Query**: Support for queries on this property is OPTIONAL. - If supported, filters MAY support only a subset of comparison operators. - - 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. - (Therefore, the first index runs over the three lattice vectors and the second index runs over the x, y, z Cartesian coordinates). - - 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. - - This property MUST be an array of dimensions 3 times 3 regardless of the elements of :property:`dimension_types`. - The vectors SHOULD by convention be chosen so the determinant of the :property:`lattice_vectors` matrix is different from zero. - The vectors in the non-periodic directions have no significance beyond fulfilling these requirements. - - All three elements of the inner lists of floats MAY be :val:`null` for non-periodic dimensions, i.e., those dimensions for which :property:`dimension_types` is :val:`0`. +- **Type**: list of list of floats or unknown values. -- **Examples**: +- **Requirements/Conventions**: + - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`. + - **Query**: Support for queries on this property is OPTIONAL. + If supported, filters MAY support only a subset of comparison operators. + - 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. + (Therefore, the first index runs over the three lattice vectors and the second index runs over the x, y, z Cartesian coordinates). + - 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. + - MUST always contain three vectors of three coordinates each, independently of the elements of property `dimension_types`. + The vectors SHOULD by convention be chosen so the determinant of the `lattice_vectors` matrix is different from zero. + The vectors in the non-periodic directions have no significance beyond fulfilling these requirements. + - 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. + If a lattice vector contains the value `null`, all coordinates of that lattice vector MUST be `null`. - - :val:`[[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 :val:`(4, 0, 0)`, i.e., a vector aligned along the :val:`x` axis of length 4 Å; the second vector is :val:`(0, 4, 0)`; and the third vector is :val:`(0, 1, 4)`.""", +- **Examples**: + - `[[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 Å; the second vector is `(0, 4, 0)`; and the third vector is `(0, 1, 4)`.""", unit="Å", ) cartesian_site_positions: List[Vector3D] = Field( ..., - description="""Cartesian positions of each site. A site is an atom, a site potentially occupied by an atom, or a placeholder for a virtual mixture of atoms (e.g., in a virtual crystal approximation). + description="""Cartesian positions of each site in the structure. +A 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. + - **Type**: list of list of floats -- **Requirements/Conventions**: - - **Support**: SHOULD be supported, i.e., SHOULD NOT be :val:`null`. Is REQUIRED in this implementation, i.e., MUST NOT be :val:`null`. - - **Query**: Support for queries on this property is OPTIONAL. If supported, filters MAY support only a subset of comparison operators. - - It MUST be a list of length N times 3, where N is the number of sites in the structure. - - An entry MAY have multiple sites at the same Cartesian position (for a relevant use of this, see e.g., the property `assemblies`_). - - If a component of the position is unknown, the :val:`null` value should be provided instead (see section `Properties with unknown value`_). - Otherwise, it should be a float value, expressed in angstrom (Å). - If at least one of the coordinates is unknown, the correct flag in the list property `structure_features`_ MUST be set. - - **Notes**: (for implementers) While this is unrelated to this OPTIMADE specification: If you decide to store internally the :property: `cartesian_site_positions` as a float array, you might want to represent :val:`null` values with :field-val:`NaN` values. - The latter being valid float numbers in the IEEE 754 standard in `IEEE 754-1985 `__ and in the updated version `IEEE 754-2008 `__. +- **Requirements/Conventions**: + - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`. + - **Query**: Support for queries on this property is OPTIONAL. + If supported, filters MAY support only a subset of comparison operators. + - 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 (Å). + - An entry MAY have multiple sites at the same Cartesian position (for a relevant use of this, see e.g., the property `assemblies`). - **Examples**: - - - :val:`[[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 Å away from the origin.""", + - `[[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 Å away from the origin.""", unit="Å", ) nsites: int = Field( ..., - description="""An integer specifying the length of the :property:`cartesian_site_positions` property. + description="""An integer specifying the length of the `cartesian_site_positions` property. + - **Type**: integer -- **Requirements/Conventions**: - - **Support**: SHOULD be supported, i.e., SHOULD NOT be :val:`null`. Is REQUIRED in this implementation, i.e., MUST NOT be :val:`null`. - - **Query**: MUST be a queryable property with support for all mandatory filter operators. +- **Requirements/Conventions**: + - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`. + - **Query**: MUST be a queryable property with support for all mandatory filter features. - **Examples**: - - - :val:`42` + - `42` - **Query examples**: - - - Match only structures with exactly 4 sites: :filter:`nsites=4` - - Match structures that have between 2 and 7 sites: :filter:`nsites>=2 AND nsites<=7`""", + - Match only structures with exactly 4 sites: `nsites=4` + - Match structures that have between 2 and 7 sites: `nsites>=2 AND nsites<=7`""", ) species: List[Species] = Field( ..., - description="""A list describing the species of the sites of this structure. Species can be pure chemical elements, or virtual-crystal atoms representing a statistical occupation of a given site by multiple chemical elements. -- **Type**: list of dictionary with keys: + description="""A list describing the species of the sites of this structure. +Species 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). - - :property:`name`: string (REQUIRED) - - :property:`chemical_symbols`: list of strings (REQUIRED) - - :property:`concentration`: list of float (REQUIRED) - - :property:`mass`: float (OPTIONAL) - - :property:`original_name`: string (OPTIONAL). +- **Type**: list of dictionary with keys: + - `name`: string (REQUIRED) + - `chemical_symbols`: list of strings (REQUIRED) + - `concentration`: list of float (REQUIRED) + - `mass`: float (OPTIONAL) + - `original_name`: string (OPTIONAL). - **Requirements/Conventions**: + - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`. + - **Query**: Support for queries on this property is OPTIONAL. + If supported, filters MAY support only a subset of comparison operators. + - Each list member MUST be a dictionary with the following keys: + - **name**: REQUIRED; gives the name of the species; the **name** value MUST be unique in the `species` list; + - **chemical_symbols**: REQUIRED; MUST be a list of strings of all chemical elements composing this species. + Each item of the list MUST be one of the following: + - a valid chemical-element name, or + - the special value `"X"` to represent a non-chemical element, or + - 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). - - **Support**: SHOULD be supported, i.e., SHOULD NOT be :val:`null`. Is REQUIRED in this implementation, i.e., MUST NOT be :val:`null`. - - **Query**: Support for queries on this property is OPTIONAL. - If supported, filters MAY support only a subset of comparison operators. - - Each list member MUST be a dictionary with the following keys: + 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` (see property [structure_features](#structure_features)). - - **name**: REQUIRED; gives the name of the species; the **name** value MUST be unique in the :property:`species` list; + - **concentration**: REQUIRED; 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: - - **chemical_symbols**: REQUIRED; MUST be a list of strings of all chemical elements composing this species. + - 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. + - 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. - - It MUST be one of the following: + Note that concentrations are uncorrelated between different sites (even of the same species). - - a valid chemical-element name, or - - the special value :val:`"X"` to represent a non-chemical element, or - - the special value :val:`"vacancy"` to represent that this site has a non-zero probability of having a vacancy (the respective probability is indicated in the :property:`concentration` list, see below). + - **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. - - If any one entry in the :property:`species` list has a :property:`chemical_symbols` list that is longer than 1 element, the correct flag MUST be set in the list :property:`structure_features` (see property `structure_features`_). + - **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. - - **concentration**: REQUIRED; MUST be a list of floats, with same length as :property:`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: + 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. + Furthermore, if they are provided, the [structure_features](#structure_features) property MUST include the string `site_attachments`. - - Numerical errors when representing float numbers in fixed precision, e.g. for two chemical symbols with concentrations :val:`1/3` and :val:`2/3`, the concentration might look something like :val:`[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. - - 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. + - **mass**: OPTIONAL. If present MUST be a float expressed in a.m.u. - Note that concentrations are uncorrelated between different site (even of the same species). + - **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. - - **mass**: OPTIONAL. If present MUST be a float expressed in a.m.u. - - **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. + Note: With regards to "source database", we refer to the immediate source being queried via the OPTIMADE API implementation. - Note: With regards to "source database", we refer to the immediate source being queried via the OPTIMADE API implementation. - 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`_). + 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](#species_at_sites)). - - 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., :val:`"Ti"` for titanium, :val:`"O"` for oxygen, etc.) - 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. - This means that a species :val:`{"name": "C", "chemical_symbols": ["Ti"], "concentration": [1.0]}` is valid and represents a titanium species (and *not* a carbon species). - - It is NOT RECOMMENDED that a structure includes species that do not have at least one corresponding site. + - 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.) + 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. + 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). + - It is NOT RECOMMENDED that a structure includes species that do not have at least one corresponding site. - **Examples**: - - - :val:`[ {"name": "Ti", "chemical_symbols": ["Ti"], "concentration": [1.0]} ]`: any site with this species is occupied by a Ti atom. - - :val:`[ {"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. - - :val:`[ {"name": "BaCa", "chemical_symbols": ["vacancy", "Ba", "Ca"], "concentration": [0.05, 0.45, 0.5], "mass": 88.5} ]`: 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. - - :val:`[ {"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. - - :val:`[ {"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.""", + - `[ {"name": "Ti", "chemical_symbols": ["Ti"], "concentration": [1.0]} ]`: any site with this species is occupied by a Ti atom. + - `[ {"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. + - `[ {"name": "BaCa", "chemical_symbols": ["vacancy", "Ba", "Ca"], "concentration": [0.05, 0.45, 0.5], "mass": 88.5} ]`: 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. + - `[ {"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. + - `[ {"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. + - `[ {"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.""", ) species_at_sites: List[str] = Field( ..., - description="""Name of the species at each site (where values for sites are specified with the same order of the property `cartesian_site_positions`_). - The properties of the species are found in the property `species`_. + description="""Name of the species at each site (where values for sites are specified with the same order of the property `cartesian_site_positions`). +The properties of the species are found in the property `species`. + - **Type**: list of strings. -- **Requirements/Conventions**: - - **Support**: SHOULD be supported, i.e., SHOULD NOT be :val:`null`. Is REQUIRED in this implementation, i.e., MUST NOT be :val:`null`. - - **Query**: Support for queries on this property is OPTIONAL. If supported, filters MAY support only a subset of comparison operators. - - MUST have length equal to the number of sites in the structure (first dimension of the list property `cartesian_site_positions`_). - - Each species MUST have a unique name. - - Each species name mentioned in the :property:`species_at_sites` list MUST be described in the list property `species`_ (i.e. for each value in the :property:`species_at_sites` list there MUST exist exactly one dictionary in the :property:`species` list with the :property:`name` attribute equal to the corresponding :property:`species_at_sites` value). - - Each site MUST be associated only to a single species. - **Note**: However, species can represent mixtures of atoms, and multiple species MAY be defined for the same chemical element. - 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. +- **Requirements/Conventions**: + - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`. + - **Query**: Support for queries on this property is OPTIONAL. + If supported, filters MAY support only a subset of comparison operators. + - MUST have length equal to the number of sites in the structure (first dimension of the list property `cartesian_site_positions`). + - 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). + - Each site MUST be associated only to a single species. + **Note**: However, species can represent mixtures of atoms, and multiple species MAY be defined for the same chemical element. + 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. - **Examples**: - - - :val:`["Ti","O2"]` indicates that the first site is hosting a species labeled :val:`"Ti"` and the second a species labeled :val:`"O2"`.""", + - `["Ti","O2"]` indicates that the first site is hosting a species labeled `"Ti"` and the second a species labeled `"O2"`. + - `["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.""", ) assemblies: Optional[List[Assembly]] = Field( None, description="""A description of groups of sites that are statistically correlated. -- **Type**: list of dictionary with keys: - - :property:`sites_in_groups`: list of list of integers (REQUIRED) - - :property:`group_probabilities`: list of floats (REQUIRED) +- **Type**: list of dictionary with keys: + - `sites_in_groups`: list of list of integers (REQUIRED) + - `group_probabilities`: list of floats (REQUIRED) - **Requirements/Conventions**: - - - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`. - - **Query**: Support for queries on this property is OPTIONAL. - If supported, filters MAY support only a subset of comparison operators. - - If present, the correct flag MUST be set in the list :property:`structure_features` (see property `structure_features`_). - - Client implementations MUST check its presence (as its presence changes the interpretation of the structure). - - If present, it MUST be a list of dictionaries, each of which represents an assembly and MUST have the following two keys: - - - **sites_in_groups**: Index of the sites (0-based) that belong to each group for each assembly. - - Example: :val:`[[1], [2]]`: two groups, one with the second site, one with the third. - - Example: :val:`[[1,2], [3]]`: one group with the second and third site, one with the fourth. - - - **group_probabilities**: Statistical probability of each group. It MUST have the same length as :property:`sites_in_groups`. - It SHOULD sum to one. - See below for examples of how to specify the probability of the occurrence of a vacancy. - The possible reasons for the values not to sum to one are the same as already specified above for the :property:`concentration` of each :property:`species`, see property `species`_. - - - If a site is not present in any group, it means that it is present with 100 % probability (as if no assembly was specified). - - A site MUST NOT appear in more than one group. + - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`. + - **Query**: Support for queries on this property is OPTIONAL. + If supported, filters MAY support only a subset of comparison operators. + - The property SHOULD be `null` for entries that have no partial occupancies. + - If present, the correct flag MUST be set in the list `structure_features`. + - Client implementations MUST check its presence (as its presence changes the interpretation of the structure). + - If present, it MUST be a list of dictionaries, each of which represents an assembly and MUST have the following two keys: + - **sites_in_groups**: Index of the sites (0-based) that belong to each group for each assembly. + + Example: `[[1], [2]]`: two groups, one with the second site, one with the third. + Example: `[[1,2], [3]]`: one group with the second and third site, one with the fourth. + + - **group_probabilities**: Statistical probability of each group. It MUST have the same length as `sites_in_groups`. + It SHOULD sum to one. + See below for examples of how to specify the probability of the occurrence of a vacancy. + The possible reasons for the values not to sum to one are the same as already specified above for the `concentration` of each `species`. + + - If a site is not present in any group, it means that it is present with 100 % probability (as if no assembly was specified). + - A site MUST NOT appear in more than one group. - **Examples** (for each entry of the assemblies list): - - - :val:`{"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. - Statistically, 30 % of the times the first site is present, while 70 % of the times the second site is present. - - :val:`{"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. - The second group is formed by the fourth site. - Sites of the first group (the second and the third) are never present at the same time as the fourth site. - 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). + - `{"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. + Statistically, 30 % of the times the first site is present, while 70 % of the times the second site is present. + - `{"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. + The second group is formed by the fourth site. + Sites of the first group (the second and the third) are never present at the same time as the fourth site. + 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). - **Notes**: + - Assemblies are essential to represent, for instance, the situation where an atom can statistically occupy two different positions (sites). + + - 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) + + - 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. + 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: + + - Using a single species: + ```json + { + "cartesian_site_positions": [[0,0,0]], + "species_at_sites": ["SiGe-vac"], + "species": [ + { + "name": "SiGe-vac", + "chemical_symbols": ["Si", "Ge", "vacancy"], + "concentration": [0.3, 0.5, 0.2] + } + ] + // ... + } + ``` + + - Using multiple species and the assemblies: + ```json + { + "cartesian_site_positions": [ [0,0,0], [0,0,0], [0,0,0] ], + "species_at_sites": ["Si", "Ge", "vac"], + "species": { + "Si": { "chemical_symbols": ["Si"], "concentration": [1.0] }, + "Ge": { "chemical_symbols": ["Ge"], "concentration": [1.0] }, + "vac": { "chemical_symbols": ["vacancy"], "concentration": [1.0] } + }, + "assemblies": [ + { + "sites_in_groups": [ [0], [1], [2] ], + "group_probabilities": [0.3, 0.5, 0.2] + } + ] + // ... + } + ``` + + - 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. + However, given a structure identified by a unique ID, the API implementation MUST always provide the same representation for it. + + - The probabilities of occurrence of different assemblies are uncorrelated. + So, for instance in the following case with two assemblies: + ```json + { + "assemblies": [ + { + "sites_in_groups": [ [0], [1] ], + "group_probabilities": [0.2, 0.8], + }, + { + "sites_in_groups": [ [2], [3] ], + "group_probabilities": [0.3, 0.7] + } + ] + } + ``` - - Assemblies are essential to represent, for instance, the situation where an atom can statistically occupy two different positions (sites). - - 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) - - 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. - 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: - - - Using a single species: - - .. code:: jsonc - - { - "cartesian_site_positions": [[0,0,0]], - "species_at_sites": ["SiGe-vac"], - "species": [ - { - "name": "SiGe-vac", - "chemical_symbols": ["Si", "Ge", "vacancy"], - "concentration": [0.3, 0.5, 0.2] - } - ] - // ... - } - - - - Using multiple species and the assemblies: - - .. code:: jsonc - - { - "cartesian_site_positions": [ [0,0,0], [0,0,0], [0,0,0] ], - "species_at_sites": ["Si", "Ge", "vac"], - "species": { - "Si": { "chemical_symbols": ["Si"], "concentration": [1.0] }, - "Ge": { "chemical_symbols": ["Ge"], "concentration": [1.0] }, - "vac": { "chemical_symbols": ["vacancy"], "concentration": [1.0] } - }, - "assemblies": [ - { - "sites_in_groups": [ [0], [1], [2] ], - "group_probabilities": [0.3, 0.5, 0.2] - } - ] - // ... - } - - - 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. - However, given a structure identified by a unique ID, the API implementation MUST always provide the same representation for it. - - The probabilities of occurrence of different assemblies are uncorrelated. - So, for instance in the following case with two assemblies: - - .. code:: jsonc - - { - "assemblies": [ - { - "sites_in_groups": [ [0], [1] ], - "group_probabilities": [0.2, 0.8], - }, - { - "sites_in_groups": [ [2], [3] ], - "group_probabilities": [0.3, 0.7] - } - ] - } - - 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 %. - These two sites are correlated (either site 2 or 3 is present). - 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).""", + 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 %. + These two sites are correlated (either site 2 or 3 is present). + 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).""", ) structure_features: List[StructureFeatures] = Field( ..., description="""A list of strings that flag which special features are used by the structure. -- **Type**: list of strings -- **Requirements/Conventions**: - - **Support**: REQUIRED, MUST NOT be :val:`null`. - - **Query**: MUST be a queryable property. Filters on the list MUST support all mandatory HAS-type queries. Filter operators for comparisons on the string components MUST support equality, support for other comparison operators are OPTIONAL. - - MUST be an empty list if no special features are used. - - MUST be sorted alphabetically. - - If a special feature listed below is used, the list MUST contain the corresponding string. - - If a special feature listed below is not used, the list MUST NOT contain the corresponding string. - - **List of strings used to indicate special structure features**: - - - :val:`disorder`: This flag MUST be present if any one entry in the :property:`species` list has a :property:`chemical_symbols` list that is longer than 1 element. - - :val:`assemblies`: This flag MUST be present if the property `assemblies`_ is present. +- **Type**: list of strings -- **Examples**: A structure having implicit atoms and using assemblies: :val:`["assemblies", "implicit_atoms"]`""", +- **Requirements/Conventions**: + - **Support**: MUST be supported by all implementations, MUST NOT be `null`. + - **Query**: MUST be a queryable property. + Filters on the list MUST support all mandatory HAS-type queries. + Filter operators for comparisons on the string components MUST support equality, support for other comparison operators are OPTIONAL. + - MUST be an empty list if no special features are used. + - MUST be sorted alphabetically. + - If a special feature listed below is used, the list MUST contain the corresponding string. + - If a special feature listed below is not used, the list MUST NOT contain the corresponding string. + - **List of strings used to indicate special structure features**: + - `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. + - `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). + 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. + - `site_attachments`: this flag MUST be present if any one entry in the `species` list includes `attached` and `nattached`. + - `assemblies`: this flag MUST be present if the property `assemblies` is present. + +- **Examples**: A structure having implicit atoms and using assemblies: `["assemblies", "implicit_atoms"]`""", ) @validator("elements", each_item=True) @@ -872,17 +873,18 @@ class StructureResource(EntryResource): type: str = Field( "structures", const=True, - description="""The name of the type of an entry. Any entry MUST be able to be fetched using the `base URL `_ type and ID at the url :endpoint:`//`. + description="""The name of the type of an entry. + - **Type**: string. -- **Requirements/Conventions**: - - **Support**: REQUIRED, MUST NOT be :val:`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 :endpoint:`//` under the versioned base URL. +- **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. -- **Example**: :val:`"structures"`""", +- **Example**: `"structures"`""", ) attributes: StructureResourceAttributes From 9d5452773605bd6e1b07a59f464eec425537845e Mon Sep 17 00:00:00 2001 From: Matthew Evans Date: Wed, 24 Jun 2020 13:13:45 +0100 Subject: [PATCH 3/8] Applied changes from code review Co-authored-by: Adam Fekete --- openapi/index_openapi.json | 10 +++++----- openapi/openapi.json | 16 ++++++++-------- optimade/models/jsonapi.py | 4 ++-- optimade/models/optimade_json.py | 8 ++++---- optimade/models/references.py | 2 +- optimade/models/structures.py | 8 +++++--- 6 files changed, 25 insertions(+), 23 deletions(-) diff --git a/openapi/index_openapi.json b/openapi/index_openapi.json index 8398e289f..c0c04d2c4 100644 --- a/openapi/index_openapi.json +++ b/openapi/index_openapi.json @@ -1422,7 +1422,7 @@ "$ref": "#/components/schemas/Relationships" } ], - "description": "a relationships object describing relationships between the resource and other JSON API resources." + "description": "Relationships object describing relationships between the resource and other JSON API resources." } }, "description": "Resource objects appear in a JSON API document to represent resources." @@ -1477,19 +1477,19 @@ "api_version": { "title": "Api Version", "type": "string", - "description": "a string containing the version of the API implementation, e.g. v0.9.5" + "description": "A string containing the version of the API implementation, e.g. v0.9.5" }, "time_stamp": { "title": "Time Stamp", "type": "string", - "description": "a timestamp containing the date and time at which the query was executed.", + "description": "A timestamp containing the date and time at which the query was executed.", "format": "date-time" }, "data_returned": { "title": "Data Returned", "minimum": 0.0, "type": "integer", - "description": "an integer containing the total number of data resource objects returned for the current `filter` query, independent of pagination." + "description": "An integer containing the total number of data resource objects returned for the current `filter` query, independent of pagination." }, "more_data_available": { "title": "More Data Available", @@ -1508,7 +1508,7 @@ "data_available": { "title": "Data Available", "type": "integer", - "description": "an integer containing the total number of data resource objects available in the database for the endpoint." + "description": "An integer containing the total number of data resource objects available in the database for the endpoint." }, "last_id": { "title": "Last Id", diff --git a/openapi/openapi.json b/openapi/openapi.json index ee8fce893..7372e8455 100644 --- a/openapi/openapi.json +++ b/openapi/openapi.json @@ -1037,7 +1037,7 @@ "$ref": "#/components/schemas/Relationships" } ], - "description": "a relationships object describing relationships between the resource and other JSON API resources." + "description": "Relationships object describing relationships between the resource and other JSON API resources." } }, "description": "Resource objects appear in a JSON API document to represent resources." @@ -2596,7 +2596,7 @@ "$ref": "#/components/schemas/Relationships" } ], - "description": "a relationships object describing relationships between the resource and other JSON API resources." + "description": "Relationships object describing relationships between the resource and other JSON API resources." } }, "description": "Resource objects appear in a JSON API document to represent resources." @@ -2651,19 +2651,19 @@ "api_version": { "title": "Api Version", "type": "string", - "description": "a string containing the version of the API implementation, e.g. v0.9.5" + "description": "A string containing the version of the API implementation, e.g. v0.9.5" }, "time_stamp": { "title": "Time Stamp", "type": "string", - "description": "a timestamp containing the date and time at which the query was executed.", + "description": "A timestamp containing the date and time at which the query was executed.", "format": "date-time" }, "data_returned": { "title": "Data Returned", "minimum": 0.0, "type": "integer", - "description": "an integer containing the total number of data resource objects returned for the current `filter` query, independent of pagination." + "description": "An integer containing the total number of data resource objects returned for the current `filter` query, independent of pagination." }, "more_data_available": { "title": "More Data Available", @@ -2682,7 +2682,7 @@ "data_available": { "title": "Data Available", "type": "integer", - "description": "an integer containing the total number of data resource objects available in the database for the endpoint." + "description": "An integer containing the total number of data resource objects available in the database for the endpoint." }, "last_id": { "title": "Last Id", @@ -2849,7 +2849,7 @@ "type": { "title": "Type", "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- **Example**: `\"structures\"`" + "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\"`" }, "links": { "title": "Links", @@ -2925,7 +2925,7 @@ "nelements": { "title": "Nelements", "type": "integer", - "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\n- **Example**: `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`." + "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\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`." }, "elements_ratios": { "title": "Elements Ratios", diff --git a/optimade/models/jsonapi.py b/optimade/models/jsonapi.py index e5ca557b9..080a26b2d 100644 --- a/optimade/models/jsonapi.py +++ b/optimade/models/jsonapi.py @@ -137,7 +137,7 @@ class BaseResource(BaseModel): class RelationshipLinks(BaseModel): - """ A resource object **MAY** contain references to other resource objects (\"relationships\"). + """A resource object **MAY** contain references to other resource objects (\"relationships\"). Relationships may be to-one or to-many. Relationships can be specified by including a member in a resource's links object. @@ -255,7 +255,7 @@ class Resource(BaseResource): ) relationships: Optional[Relationships] = Field( None, - description="a relationships object describing relationships between the resource and other JSON API resources.", + description="Relationships object describing relationships between the resource and other JSON API resources.", ) diff --git a/optimade/models/optimade_json.py b/optimade/models/optimade_json.py index 54c7f6a31..3e16c3439 100644 --- a/optimade/models/optimade_json.py +++ b/optimade/models/optimade_json.py @@ -238,17 +238,17 @@ class ResponseMeta(jsonapi.Meta): api_version: str = Field( ..., - description="a string containing the version of the API implementation, e.g. v0.9.5", + description="A string containing the version of the API implementation, e.g. v0.9.5", ) time_stamp: datetime = Field( ..., - description="a timestamp containing the date and time at which the query was executed.", + description="A timestamp containing the date and time at which the query was executed.", ) data_returned: int = Field( ..., - description="an integer containing the total number of data resource objects returned for the current `filter` query, independent of pagination.", + description="An integer containing the total number of data resource objects returned for the current `filter` query, independent of pagination.", ge=0, ) @@ -263,7 +263,7 @@ class ResponseMeta(jsonapi.Meta): data_available: Optional[int] = Field( None, - description="an integer containing the total number of data resource objects available in the database for the endpoint.", + description="An integer containing the total number of data resource objects available in the database for the endpoint.", ) last_id: Optional[str] = Field( diff --git a/optimade/models/references.py b/optimade/models/references.py index 9f24dfcc6..0ce04ccb2 100644 --- a/optimade/models/references.py +++ b/optimade/models/references.py @@ -111,7 +111,7 @@ class ReferenceResourceAttributes(EntryResourceAttributes): class ReferenceResource(EntryResource): - """ The `references` entries describe bibliographic references. + """The `references` entries describe bibliographic references. The following properties are used to provide the bibliographic details: - **address**, **annote**, **booktitle**, **chapter**, **crossref**, **edition**, **howpublished**, **institution**, **journal**, **key**, **month**, **note**, **number**, **organization**, **pages**, **publisher**, **school**, **series**, **title**, **volume**, **year**: meanings of these properties match the [BibTeX specification](http://bibtexml.sourceforge.net/btxdoc.pdf), values are strings; diff --git a/optimade/models/structures.py b/optimade/models/structures.py index c11ed691a..d944fae90 100644 --- a/optimade/models/structures.py +++ b/optimade/models/structures.py @@ -45,7 +45,7 @@ class StructureFeatures(Enum): class Species(BaseModel): - """ A list describing the species of the sites of this structure. + """A list describing the species of the sites of this structure. Species 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 @@ -245,7 +245,8 @@ class StructureResourceAttributes(EntryResourceAttributes): - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`. - **Query**: MUST be a queryable property with support for all mandatory filter features. -- **Example**: `3` +- **Examples**: + - `3` - **Querying**: - Note: queries on this property can equivalently be formulated using `elements LENGTH`. @@ -884,7 +885,8 @@ class StructureResource(EntryResource): - 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. -- **Example**: `"structures"`""", +- **Examples**: + - `"structures"`""", ) attributes: StructureResourceAttributes From a1045142f923e6b59d3e2991ad691d842e562524 Mon Sep 17 00:00:00 2001 From: Matthew Evans Date: Wed, 24 Jun 2020 13:17:56 +0100 Subject: [PATCH 4/8] Caught one last internal link --- openapi/index_openapi.json | 2 +- openapi/openapi.json | 2 +- optimade/models/links.py | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/openapi/index_openapi.json b/openapi/index_openapi.json index c0c04d2c4..ba994602a 100644 --- a/openapi/index_openapi.json +++ b/openapi/index_openapi.json @@ -1028,7 +1028,7 @@ "staging", "no" ], - "description": "A string indicating whether a client that is following links to aggregate results from different OPTIMADE implementations should follow this link or not.\nThis flag SHOULD NOT be indicated for links where `link_type` is not `child`.\n\nIf not specified, clients MAY assume that the value is `ok`.\nIf specified, and the value is anything different than `ok`, the client MUST assume that the server is suggesting not to follow the link during aggregation by default (also if the value is not among the known ones, in case a future specification adds new accepted values).\n\nSpecific values indicate the reason why the server is providing the suggestion.\nA client MAY follow the link anyway if it has reason to do so (e.g., if the client is looking for all test databases, it MAY follow the links marked with `aggregate`=`test`).\n\nIf specified, it MUST be one of the values listed in section [Link Aggregate Options](#link-aggregate-options).", + "description": "A string indicating whether a client that is following links to aggregate results from different OPTIMADE implementations should follow this link or not.\nThis flag SHOULD NOT be indicated for links where `link_type` is not `child`.\n\nIf not specified, clients MAY assume that the value is `ok`.\nIf specified, and the value is anything different than `ok`, the client MUST assume that the server is suggesting not to follow the link during aggregation by default (also if the value is not among the known ones, in case a future specification adds new accepted values).\n\nSpecific values indicate the reason why the server is providing the suggestion.\nA client MAY follow the link anyway if it has reason to do so (e.g., if the client is looking for all test databases, it MAY follow the links marked with `aggregate`=`test`).\n\nIf specified, it MUST be one of the values listed in section Link Aggregate Options.", "default": "ok" }, "no_aggregate_reason": { diff --git a/openapi/openapi.json b/openapi/openapi.json index 7372e8455..1499b7af1 100644 --- a/openapi/openapi.json +++ b/openapi/openapi.json @@ -1824,7 +1824,7 @@ "staging", "no" ], - "description": "A string indicating whether a client that is following links to aggregate results from different OPTIMADE implementations should follow this link or not.\nThis flag SHOULD NOT be indicated for links where `link_type` is not `child`.\n\nIf not specified, clients MAY assume that the value is `ok`.\nIf specified, and the value is anything different than `ok`, the client MUST assume that the server is suggesting not to follow the link during aggregation by default (also if the value is not among the known ones, in case a future specification adds new accepted values).\n\nSpecific values indicate the reason why the server is providing the suggestion.\nA client MAY follow the link anyway if it has reason to do so (e.g., if the client is looking for all test databases, it MAY follow the links marked with `aggregate`=`test`).\n\nIf specified, it MUST be one of the values listed in section [Link Aggregate Options](#link-aggregate-options).", + "description": "A string indicating whether a client that is following links to aggregate results from different OPTIMADE implementations should follow this link or not.\nThis flag SHOULD NOT be indicated for links where `link_type` is not `child`.\n\nIf not specified, clients MAY assume that the value is `ok`.\nIf specified, and the value is anything different than `ok`, the client MUST assume that the server is suggesting not to follow the link during aggregation by default (also if the value is not among the known ones, in case a future specification adds new accepted values).\n\nSpecific values indicate the reason why the server is providing the suggestion.\nA client MAY follow the link anyway if it has reason to do so (e.g., if the client is looking for all test databases, it MAY follow the links marked with `aggregate`=`test`).\n\nIf specified, it MUST be one of the values listed in section Link Aggregate Options.", "default": "ok" }, "no_aggregate_reason": { diff --git a/optimade/models/links.py b/optimade/models/links.py index faf347792..0f7a0a224 100644 --- a/optimade/models/links.py +++ b/optimade/models/links.py @@ -74,7 +74,7 @@ class LinksResourceAttributes(Attributes): Specific values indicate the reason why the server is providing the suggestion. A client MAY follow the link anyway if it has reason to do so (e.g., if the client is looking for all test databases, it MAY follow the links marked with `aggregate`=`test`). -If specified, it MUST be one of the values listed in section [Link Aggregate Options](#link-aggregate-options).""", +If specified, it MUST be one of the values listed in section Link Aggregate Options.""", ) no_aggregate_reason: Optional[str] = Field( From 9027af3ab67c0ae4dbcbeb7781476d7c325880e0 Mon Sep 17 00:00:00 2001 From: Matthew Evans Date: Wed, 24 Jun 2020 13:27:31 +0100 Subject: [PATCH 5/8] Tweaked class docstrings to fix mkdocs rendering --- openapi/openapi.json | 6 ++--- optimade/models/optimade_json.py | 2 +- optimade/models/references.py | 26 ++++++++++---------- optimade/models/structures.py | 42 +++++++++++++++----------------- 4 files changed, 37 insertions(+), 39 deletions(-) diff --git a/openapi/openapi.json b/openapi/openapi.json index 1499b7af1..7e075876f 100644 --- a/openapi/openapi.json +++ b/openapi/openapi.json @@ -898,7 +898,7 @@ "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`, see property [species](#species)." } }, - "description": "A description of groups of sites that are statistically correlated.\n\n- **Examples** (for each entry of the assemblies list):\n\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. 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)." + "description": "A description of groups of sites that are statistically correlated.\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. 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 " }, "Attributes": { "title": "Attributes", @@ -2168,7 +2168,7 @@ "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": "The `references` entries describe bibliographic references.\nThe following properties are used to provide the bibliographic details:\n\n- **address**, **annote**, **booktitle**, **chapter**, **crossref**, **edition**, **howpublished**, **institution**, **journal**, **key**, **month**, **note**, **number**, **organization**, **pages**, **publisher**, **school**, **series**, **title**, **volume**, **year**: meanings of these properties match the [BibTeX specification](http://bibtexml.sourceforge.net/btxdoc.pdf), values are strings;\n- **bib_type**: type of the reference, corresponding to **type** property in the BibTeX specification, value is string;\n- **authors** and **editors**: lists of *person objects* which are dictionaries with the following keys:\n - **name**: Full name of the person, REQUIRED.\n - **firstname**, **lastname**: Parts of the person's name, OPTIONAL.\n- **doi** and **url**: values are strings.\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., any of the properties MAY be `null`.\n - **Query**: Support for queries on any of these properties is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - Every references entry MUST contain at least one of the properties." + "description": "The `references` entries describe bibliographic references.\nThe following properties are used to provide the bibliographic details:\n\n- **address**, **annote**, **booktitle**, **chapter**, **crossref**, **edition**, **howpublished**, **institution**, **journal**, **key**, **month**, **note**, **number**, **organization**, **pages**, **publisher**, **school**, **series**, **title**, **volume**, **year**: meanings of these properties match the [BibTeX specification](http://bibtexml.sourceforge.net/btxdoc.pdf), values are strings;\n- **bib_type**: type of the reference, corresponding to **type** property in the BibTeX specification, value is string;\n- **authors** and **editors**: lists of *person objects* which are dictionaries with the following keys:\n - **name**: Full name of the person, REQUIRED.\n - **firstname**, **lastname**: Parts of the person's name, OPTIONAL.\n- **doi** and **url**: values are strings.\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., any of the properties MAY be `null`.\n - **Query**: Support for queries on any of these properties is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - Every references entry MUST contain at least one of the properties.\n\n " }, "ReferenceResourceAttributes": { "title": "ReferenceResourceAttributes", @@ -2786,7 +2786,7 @@ "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." } }, - "description": "A list describing the species of the sites of this structure.\nSpecies can represent pure chemical elements, virtual-crystal atoms representing a\nstatistical occupation of a given site by multiple chemical elements, and/or a\nlocation to which there are attached atoms, i.e., atoms whose precise location are\nunknown beyond that they are attached to that position (frequently used to indicate\nhydrogen atoms attached to another element, e.g., a carbon with three attached\nhydrogens might represent a methyl group, -CH3).\n\n- **Examples**:\n\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\": 88.5} ]`: 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." + "description": "A list describing the species of the sites of this structure.\nSpecies can represent pure chemical elements, virtual-crystal atoms representing a\nstatistical occupation of a given site by multiple chemical elements, and/or a\nlocation to which there are attached atoms, i.e., atoms whose precise location are\nunknown beyond that they are attached to that position (frequently used to indicate\nhydrogen atoms attached to another element, e.g., a carbon with three attached\nhydrogens might represent a methyl group, -CH3).\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\": 88.5} ]`: 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.\n\n " }, "StructureRelationship": { "title": "StructureRelationship", diff --git a/optimade/models/optimade_json.py b/optimade/models/optimade_json.py index 3e16c3439..4fd092a6c 100644 --- a/optimade/models/optimade_json.py +++ b/optimade/models/optimade_json.py @@ -29,7 +29,7 @@ class DataType(Enum): """Optimade Data Types - See the section "Data types" in the OPTIMADE API specification for more information. +See the section "Data types" in the OPTIMADE API specification for more information. """ STRING = "string" diff --git a/optimade/models/references.py b/optimade/models/references.py index 0ce04ccb2..49e97ce3b 100644 --- a/optimade/models/references.py +++ b/optimade/models/references.py @@ -112,19 +112,19 @@ class ReferenceResourceAttributes(EntryResourceAttributes): class ReferenceResource(EntryResource): """The `references` entries describe bibliographic references. - The following properties are used to provide the bibliographic details: - - - **address**, **annote**, **booktitle**, **chapter**, **crossref**, **edition**, **howpublished**, **institution**, **journal**, **key**, **month**, **note**, **number**, **organization**, **pages**, **publisher**, **school**, **series**, **title**, **volume**, **year**: meanings of these properties match the [BibTeX specification](http://bibtexml.sourceforge.net/btxdoc.pdf), values are strings; - - **bib_type**: type of the reference, corresponding to **type** property in the BibTeX specification, value is string; - - **authors** and **editors**: lists of *person objects* which are dictionaries with the following keys: - - **name**: Full name of the person, REQUIRED. - - **firstname**, **lastname**: Parts of the person's name, OPTIONAL. - - **doi** and **url**: values are strings. - - **Requirements/Conventions**: - - **Support**: OPTIONAL support in implementations, i.e., any of the properties MAY be `null`. - - **Query**: Support for queries on any of these properties is OPTIONAL. - If supported, filters MAY support only a subset of comparison operators. - - Every references entry MUST contain at least one of the properties. +The following properties are used to provide the bibliographic details: + +- **address**, **annote**, **booktitle**, **chapter**, **crossref**, **edition**, **howpublished**, **institution**, **journal**, **key**, **month**, **note**, **number**, **organization**, **pages**, **publisher**, **school**, **series**, **title**, **volume**, **year**: meanings of these properties match the [BibTeX specification](http://bibtexml.sourceforge.net/btxdoc.pdf), values are strings; +- **bib_type**: type of the reference, corresponding to **type** property in the BibTeX specification, value is string; +- **authors** and **editors**: lists of *person objects* which are dictionaries with the following keys: + - **name**: Full name of the person, REQUIRED. + - **firstname**, **lastname**: Parts of the person's name, OPTIONAL. +- **doi** and **url**: values are strings. +- **Requirements/Conventions**: + - **Support**: OPTIONAL support in implementations, i.e., any of the properties MAY be `null`. + - **Query**: Support for queries on any of these properties is OPTIONAL. + If supported, filters MAY support only a subset of comparison operators. + - Every references entry MUST contain at least one of the properties. """ diff --git a/optimade/models/structures.py b/optimade/models/structures.py index d944fae90..6a2f44c41 100644 --- a/optimade/models/structures.py +++ b/optimade/models/structures.py @@ -46,21 +46,20 @@ class StructureFeatures(Enum): class Species(BaseModel): """A list describing the species of the sites of this structure. - Species 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). - - - **Examples**: - - - `[ {"name": "Ti", "chemical_symbols": ["Ti"], "concentration": [1.0]} ]`: any site with this species is occupied by a Ti atom. - - `[ {"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. - - `[ {"name": "BaCa", "chemical_symbols": ["vacancy", "Ba", "Ca"], "concentration": [0.05, 0.45, 0.5], "mass": 88.5} ]`: 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. - - `[ {"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. - - `[ {"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. - - `[ {"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. +Species 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). + +- **Examples**: + - `[ {"name": "Ti", "chemical_symbols": ["Ti"], "concentration": [1.0]} ]`: any site with this species is occupied by a Ti atom. + - `[ {"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. + - `[ {"name": "BaCa", "chemical_symbols": ["vacancy", "Ba", "Ca"], "concentration": [0.05, 0.45, 0.5], "mass": 88.5} ]`: 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. + - `[ {"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. + - `[ {"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. + - `[ {"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. """ @@ -163,13 +162,12 @@ def attached_nattached_mutually_exclusive(cls, values): class Assembly(BaseModel): """A description of groups of sites that are statistically correlated. - - **Examples** (for each entry of the assemblies list): - - - `{"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. - Statistically, 30 % of the times the first site is present, while 70 % of the times the second site is present. - - `{"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. - The second group is formed by the fourth site. Sites of the first group (the second and the third) are never present at the same time as the fourth site. - 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). +- **Examples** (for each entry of the assemblies list): + - `{"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. + Statistically, 30 % of the times the first site is present, while 70 % of the times the second site is present. + - `{"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. + The second group is formed by the fourth site. Sites of the first group (the second and the third) are never present at the same time as the fourth site. + 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). """ From a88a3755f627fe7a08f8ae1200bb044039b4fe50 Mon Sep 17 00:00:00 2001 From: Matthew Evans Date: Wed, 24 Jun 2020 14:51:14 +0100 Subject: [PATCH 6/8] Changes from code review Co-authored-by: Casper Welzel Andersen --- openapi/index_openapi.json | 22 +++++++++---------- openapi/openapi.json | 36 ++++++++++++++++---------------- optimade/models/baseinfo.py | 2 +- optimade/models/entries.py | 9 +++----- optimade/models/index_metadb.py | 8 +++---- optimade/models/jsonapi.py | 16 ++++++++++---- optimade/models/links.py | 4 ++-- optimade/models/optimade_json.py | 19 +++++++---------- optimade/models/structures.py | 28 ++++++++++++------------- 9 files changed, 71 insertions(+), 73 deletions(-) diff --git a/openapi/index_openapi.json b/openapi/index_openapi.json index ba994602a..511cc56cb 100644 --- a/openapi/index_openapi.json +++ b/openapi/index_openapi.json @@ -709,7 +709,7 @@ "is_index": { "title": "Is Index", "type": "boolean", - "description": "If true, this is an index meta-database base URL (see section Index Meta-Database). If this member is not provided, the client MUST assume this is not an index meta-database base URL (i.e., the default is for `is_index` to be false)." + "description": "This must be `true` since this is an index meta-database (see section Index Meta-Database)." } }, "description": "Attributes for Base URL Info endpoint for an Index Meta-Database" @@ -757,7 +757,7 @@ "additionalProperties": { "$ref": "#/components/schemas/IndexRelationship" }, - "description": "Reference to the child identifier object under the `links` endpoint that the provider has chosen as their 'default' OPTIMADE API database.\nA client SHOULD present this database as the first choice when an end-user chooses this provider." + "description": "Reference to the Links identifier object under the `links` endpoint that the provider has chosen as their 'default' OPTIMADE API database.\nA client SHOULD present this database as the first choice when an end-user chooses this provider." } }, "description": "Index Meta-Database Base URL Info endpoint resource" @@ -840,7 +840,7 @@ "$ref": "#/components/schemas/RelatedLinksResource" } ], - "description": "JSON API resource linkage.\nIt MUST be either `null` or contain a single Links identifier object with the fields `id` and `type`" + "description": "[JSON API resource linkage](http://jsonapi.org/format/1.0/#document-links).\nIt MUST be either `null` or contain a single Links identifier object with the fields `id` and `type`" } }, "description": "Index Meta-Database relationship" @@ -937,7 +937,7 @@ "$ref": "#/components/schemas/LinksResourceAttributes" } ], - "description": "A dictionary containing key-value pairs representing the entry's properties." + "description": "A dictionary containing key-value pairs representing the Links resource's properties." }, "relationships": { "title": "Relationships", @@ -1018,7 +1018,7 @@ "external", "providers" ], - "description": "The link type of the represented resource in relation to this implementation.\nMUST be one of these values: 'child', 'root', 'external', 'providers'." + "description": "The type of the linked relation.\nMUST be one of these values: 'child', 'root', 'external', 'providers'." }, "aggregate": { "title": "Aggregate", @@ -1340,7 +1340,7 @@ ] } ], - "description": "A link to itself" + "description": "A link for the relationship itself (a 'relationship link').\nThis link allows the client to directly manipulate the relationship.\nWhen fetched successfully, this link returns the [linkage](https://jsonapi.org/format/1.0/#document-resource-object-linkage) for the related resources as its primary data.\n(See [Fetching Relationships](https://jsonapi.org/format/1.0/#fetching-relationships).)" }, "related": { "title": "Related", @@ -1359,7 +1359,7 @@ ] } ], - "description": "A related resource link" + "description": "A [related resource link](https://jsonapi.org/format/1.0/#document-resource-object-related-resource-links)." } }, "description": "A resource object **MAY** contain references to other resource objects (\"relationships\").\nRelationships may be to-one or to-many.\nRelationships can be specified by including a member in a resource's links object." @@ -1422,7 +1422,7 @@ "$ref": "#/components/schemas/Relationships" } ], - "description": "Relationships object describing relationships between the resource and other JSON API resources." + "description": "[Relationships object](https://jsonapi.org/format/1.0/#document-resource-object-relationships)\ndescribing relationships between the resource and other JSON API resources." } }, "description": "Resource objects appear in a JSON API document to represent resources." @@ -1472,12 +1472,12 @@ "$ref": "#/components/schemas/ResponseMetaQuery" } ], - "description": "information on the query that was requested" + "description": "Information on the Query that was requested" }, "api_version": { "title": "Api Version", "type": "string", - "description": "A string containing the version of the API implementation, e.g. v0.9.5" + "description": "A string containing the version of the API implementation." }, "time_stamp": { "title": "Time Stamp", @@ -1769,7 +1769,7 @@ "description": "Warnings must be of type \"warning\"" } }, - "description": "OPTIMADE-specific warning class based on OPTIMADE-specific JSON API Error.\n\nFrom the specification:\n\n A warning resource object is defined similarly to a JSON API\n error object, but MUST also include the field type, which MUST\n have the value \"warning\". The field detail MUST be present and\n SHOULD contain a non-critical message, e.g., reporting\n unrecognized search attributes or deprecated features.\n\nNote: Must be named \"Warnings\", since \"Warning\" is a built-in Python class." + "description": "OPTIMADE-specific warning class based on OPTIMADE-specific JSON API Error.\n\nFrom the specification:\n\nA warning resource object is defined similarly to a JSON API error object, but MUST also include the field type, which MUST have the value \"warning\".\nThe field detail MUST be present and SHOULD contain a non-critical message, e.g., reporting unrecognized search attributes or deprecated features.\n\nNote: Must be named \"Warnings\", since \"Warning\" is a built-in Python class." } } } diff --git a/openapi/openapi.json b/openapi/openapi.json index 7e075876f..896c90ffd 100644 --- a/openapi/openapi.json +++ b/openapi/openapi.json @@ -895,10 +895,10 @@ "items": { "type": "number" }, - "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`, see property [species](#species)." + "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`." } }, - "description": "A description of groups of sites that are statistically correlated.\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. 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 " + "description": "A description of groups of sites that are statistically correlated.\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. 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 " }, "Attributes": { "title": "Attributes", @@ -988,7 +988,7 @@ "is_index": { "title": "Is Index", "type": "boolean", - "description": "If true, this is an index meta-database base URL (see section Index Meta-Database). If this member is not provided, the client MUST assume this is not an index meta-database base URL (i.e., the default is for `is_index` to be false).", + "description": "If true, this is an index meta-database base URL (see section Index Meta-Database). If this member is not provided, the client MUST assume this is not an index meta-database base URL (i.e., the default is for `is_index` to be `false`).", "default": false } }, @@ -1037,7 +1037,7 @@ "$ref": "#/components/schemas/Relationships" } ], - "description": "Relationships object describing relationships between the resource and other JSON API resources." + "description": "[Relationships object](https://jsonapi.org/format/1.0/#document-resource-object-relationships)\ndescribing relationships between the resource and other JSON API resources." } }, "description": "Resource objects appear in a JSON API document to represent resources." @@ -1121,7 +1121,7 @@ "dictionary", "unknown" ], - "description": "String.\nThe type of the property's value.\n\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`.\nData type of value. Must equal a valid OPTIMADE data type as listed and defined under 'Data types'." + "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`." } } }, @@ -1146,7 +1146,7 @@ "description": { "title": "Description", "type": "string", - "description": "Description of the entry" + "description": "Description of the entry." }, "properties": { "title": "Properties", @@ -1733,7 +1733,7 @@ "$ref": "#/components/schemas/LinksResourceAttributes" } ], - "description": "A dictionary containing key-value pairs representing the entry's properties." + "description": "A dictionary containing key-value pairs representing the Links resource's properties." }, "relationships": { "title": "Relationships", @@ -1814,7 +1814,7 @@ "external", "providers" ], - "description": "The link type of the represented resource in relation to this implementation.\nMUST be one of these values: 'child', 'root', 'external', 'providers'." + "description": "The type of the linked relation.\nMUST be one of these values: 'child', 'root', 'external', 'providers'." }, "aggregate": { "title": "Aggregate", @@ -2514,7 +2514,7 @@ ] } ], - "description": "A link to itself" + "description": "A link for the relationship itself (a 'relationship link').\nThis link allows the client to directly manipulate the relationship.\nWhen fetched successfully, this link returns the [linkage](https://jsonapi.org/format/1.0/#document-resource-object-linkage) for the related resources as its primary data.\n(See [Fetching Relationships](https://jsonapi.org/format/1.0/#fetching-relationships).)" }, "related": { "title": "Related", @@ -2533,7 +2533,7 @@ ] } ], - "description": "A related resource link" + "description": "A [related resource link](https://jsonapi.org/format/1.0/#document-resource-object-related-resource-links)." } }, "description": "A resource object **MAY** contain references to other resource objects (\"relationships\").\nRelationships may be to-one or to-many.\nRelationships can be specified by including a member in a resource's links object." @@ -2596,7 +2596,7 @@ "$ref": "#/components/schemas/Relationships" } ], - "description": "Relationships object describing relationships between the resource and other JSON API resources." + "description": "[Relationships object](https://jsonapi.org/format/1.0/#document-resource-object-relationships)\ndescribing relationships between the resource and other JSON API resources." } }, "description": "Resource objects appear in a JSON API document to represent resources." @@ -2646,12 +2646,12 @@ "$ref": "#/components/schemas/ResponseMetaQuery" } ], - "description": "information on the query that was requested" + "description": "Information on the Query that was requested" }, "api_version": { "title": "Api Version", "type": "string", - "description": "A string containing the version of the API implementation, e.g. v0.9.5" + "description": "A string containing the version of the API implementation." }, "time_stamp": { "title": "Time Stamp", @@ -2749,7 +2749,7 @@ "items": { "type": "string" }, - "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 name, 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` (see property [structure_features](#structure_features))." + "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 name, 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`." }, "concentration": { "title": "Concentration", @@ -3035,7 +3035,7 @@ ] } ], - "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)`." + "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)`." }, "cartesian_site_positions": { "title": "Cartesian Site Positions", @@ -3054,7 +3054,7 @@ } ] }, - "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." + "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." }, "nsites": { "title": "Nsites", @@ -3067,7 +3067,7 @@ "items": { "$ref": "#/components/schemas/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 - `mass`: float (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 name, 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` (see property [structure_features](#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](#structure_features) property MUST include the string `site_attachments`.\n\n - **mass**: OPTIONAL. If present MUST be a float expressed in a.m.u.\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](#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\": 88.5} ]`: 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." + "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 - `mass`: float (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 name, 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 float expressed in a.m.u.\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\": 88.5} ]`: 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." }, "species_at_sites": { "title": "Species At Sites", @@ -3432,7 +3432,7 @@ "description": "Warnings must be of type \"warning\"" } }, - "description": "OPTIMADE-specific warning class based on OPTIMADE-specific JSON API Error.\n\nFrom the specification:\n\n A warning resource object is defined similarly to a JSON API\n error object, but MUST also include the field type, which MUST\n have the value \"warning\". The field detail MUST be present and\n SHOULD contain a non-critical message, e.g., reporting\n unrecognized search attributes or deprecated features.\n\nNote: Must be named \"Warnings\", since \"Warning\" is a built-in Python class." + "description": "OPTIMADE-specific warning class based on OPTIMADE-specific JSON API Error.\n\nFrom the specification:\n\nA warning resource object is defined similarly to a JSON API error object, but MUST also include the field type, which MUST have the value \"warning\".\nThe field detail MUST be present and SHOULD contain a non-critical message, e.g., reporting unrecognized search attributes or deprecated features.\n\nNote: Must be named \"Warnings\", since \"Warning\" is a built-in Python class." } } } diff --git a/optimade/models/baseinfo.py b/optimade/models/baseinfo.py index a7c17ab57..2b45737cc 100644 --- a/optimade/models/baseinfo.py +++ b/optimade/models/baseinfo.py @@ -74,7 +74,7 @@ class BaseInfoAttributes(BaseModel): default=False, description="If true, this is an index meta-database base URL (see section Index Meta-Database). " "If this member is not provided, the client MUST assume this is not an index meta-database base URL " - "(i.e., the default is for `is_index` to be false).", + "(i.e., the default is for `is_index` to be `false`).", ) @validator("entry_types_by_format", check_fields=False) diff --git a/optimade/models/entries.py b/optimade/models/entries.py index dd7e59b4a..7ce6bc362 100644 --- a/optimade/models/entries.py +++ b/optimade/models/entries.py @@ -150,14 +150,11 @@ class EntryInfoProperty(BaseModel): type: Optional[DataType] = Field( None, - description="""String. -The type of the property's value. - + 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`. -Data type of value. Must equal a valid OPTIMADE data type as listed and defined under 'Data types'.""", +E.g., for the entry resource `structures`, the `species` property is defined as a list of dictionaries, hence its `type` value would be `list`.""", ) @@ -167,7 +164,7 @@ class EntryInfoResource(BaseModel): ..., description="List of output formats available for this type of entry." ) - description: str = Field(..., description="Description of the entry") + description: str = Field(..., description="Description of the entry.") properties: Dict[str, EntryInfoProperty] = Field( ..., diff --git a/optimade/models/index_metadb.py b/optimade/models/index_metadb.py index 26b366f85..4d6d1b9c6 100644 --- a/optimade/models/index_metadb.py +++ b/optimade/models/index_metadb.py @@ -28,9 +28,7 @@ class IndexInfoAttributes(BaseInfoAttributes): is_index: bool = Field( default=True, const=True, - description="If true, this is an index meta-database base URL (see section Index Meta-Database). " - "If this member is not provided, the client MUST assume this is not an index meta-database base URL " - "(i.e., the default is for `is_index` to be false).", + description="This must be `true` since this is an index meta-database (see section Index Meta-Database).", ) @@ -45,7 +43,7 @@ class IndexRelationship(BaseModel): data: Union[None, RelatedLinksResource] = Field( ..., - description="""JSON API resource linkage. + description="""[JSON API resource linkage](http://jsonapi.org/format/1.0/#document-links). It MUST be either `null` or contain a single Links identifier object with the fields `id` and `type`""", ) @@ -56,6 +54,6 @@ class IndexInfoResource(BaseInfoResource): attributes: IndexInfoAttributes = Field(...) relationships: Union[None, Dict[DefaultRelationship, IndexRelationship]] = Field( ..., - description="""Reference to the child identifier object under the `links` endpoint that the provider has chosen as their 'default' OPTIMADE API database. + description="""Reference to the Links identifier object under the `links` endpoint that the provider has chosen as their 'default' OPTIMADE API database. A client SHOULD present this database as the first choice when an end-user chooses this provider.""", ) diff --git a/optimade/models/jsonapi.py b/optimade/models/jsonapi.py index 080a26b2d..f06ade5e6 100644 --- a/optimade/models/jsonapi.py +++ b/optimade/models/jsonapi.py @@ -137,15 +137,22 @@ class BaseResource(BaseModel): class RelationshipLinks(BaseModel): - """A resource object **MAY** contain references to other resource objects (\"relationships\"). + """A resource object **MAY** contain references to other resource objects ("relationships"). Relationships may be to-one or to-many. Relationships can be specified by including a member in a resource's links object. """ - self: Optional[Union[AnyUrl, Link]] = Field(None, description="A link to itself") + self: Optional[Union[AnyUrl, Link]] = Field( + None, + description="""A link for the relationship itself (a 'relationship link'). +This link allows the client to directly manipulate the relationship. +When fetched successfully, this link returns the [linkage](https://jsonapi.org/format/1.0/#document-resource-object-linkage) for the related resources as its primary data. +(See [Fetching Relationships](https://jsonapi.org/format/1.0/#fetching-relationships).)""", + ) related: Optional[Union[AnyUrl, Link]] = Field( - None, description="A related resource link" + None, + description="A [related resource link](https://jsonapi.org/format/1.0/#document-resource-object-related-resource-links).", ) @root_validator(pre=True) @@ -255,7 +262,8 @@ class Resource(BaseResource): ) relationships: Optional[Relationships] = Field( None, - description="Relationships object describing relationships between the resource and other JSON API resources.", + description="""[Relationships object](https://jsonapi.org/format/1.0/#document-resource-object-relationships) +describing relationships between the resource and other JSON API resources.""", ) diff --git a/optimade/models/links.py b/optimade/models/links.py index 0f7a0a224..437a2151d 100644 --- a/optimade/models/links.py +++ b/optimade/models/links.py @@ -59,7 +59,7 @@ class LinksResourceAttributes(Attributes): link_type: LinkType = Field( ..., - description="""The link type of the represented resource in relation to this implementation. + description="""The type of the linked relation. MUST be one of these values: 'child', 'root', 'external', 'providers'.""", ) @@ -95,7 +95,7 @@ class LinksResource(EntryResource): attributes: LinksResourceAttributes = Field( ..., - description="A dictionary containing key-value pairs representing the entry's properties.", + description="A dictionary containing key-value pairs representing the Links resource's properties.", ) @root_validator(pre=True) diff --git a/optimade/models/optimade_json.py b/optimade/models/optimade_json.py index 4fd092a6c..382954635 100644 --- a/optimade/models/optimade_json.py +++ b/optimade/models/optimade_json.py @@ -134,17 +134,13 @@ class OptimadeError(jsonapi.Error): class Warnings(OptimadeError): """OPTIMADE-specific warning class based on OPTIMADE-specific JSON API Error. - From the specification: +From the specification: - A warning resource object is defined similarly to a JSON API - error object, but MUST also include the field type, which MUST - have the value "warning". The field detail MUST be present and - SHOULD contain a non-critical message, e.g., reporting - unrecognized search attributes or deprecated features. +A warning resource object is defined similarly to a JSON API error object, but MUST also include the field type, which MUST have the value "warning". +The field detail MUST be present and SHOULD contain a non-critical message, e.g., reporting unrecognized search attributes or deprecated features. - Note: Must be named "Warnings", since "Warning" is a built-in Python class. - - """ +Note: Must be named "Warnings", since "Warning" is a built-in Python class. +""" type: str = Field( "warning", const=True, description='Warnings must be of type "warning"' @@ -233,12 +229,11 @@ class ResponseMeta(jsonapi.Meta): """ query: ResponseMetaQuery = Field( - ..., description="information on the query that was requested" + ..., description="Information on the Query that was requested" ) api_version: str = Field( - ..., - description="A string containing the version of the API implementation, e.g. v0.9.5", + ..., description="A string containing the version of the API implementation.", ) time_stamp: datetime = Field( diff --git a/optimade/models/structures.py b/optimade/models/structures.py index 6a2f44c41..2a3975882 100644 --- a/optimade/models/structures.py +++ b/optimade/models/structures.py @@ -76,7 +76,7 @@ class Species(BaseModel): - the special value `"X"` to represent a non-chemical element, or - 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). -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` (see property [structure_features](#structure_features)).""", +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`.""", ) concentration: List[float] = Field( @@ -164,10 +164,10 @@ class Assembly(BaseModel): - **Examples** (for each entry of the assemblies list): - `{"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. - Statistically, 30 % of the times the first site is present, while 70 % of the times the second site is present. + Statistically, 30 % of the times the first site is present, while 70 % of the times the second site is present. - `{"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. - The second group is formed by the fourth site. Sites of the first group (the second and the third) are never present at the same time as the fourth site. - 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). + The second group is formed by the fourth site. Sites of the first group (the second and the third) are never present at the same time as the fourth site. + 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). """ @@ -185,7 +185,7 @@ class Assembly(BaseModel): description="""Statistical probability of each group. It MUST have the same length as `sites_in_groups`. It SHOULD sum to one. See below for examples of how to specify the probability of the occurrence of a vacancy. -The possible reasons for the values not to sum to one are the same as already specified above for the `concentration` of each `species`, see property [species](#species).""", +The possible reasons for the values not to sum to one are the same as already specified above for the `concentration` of each `species`.""", ) @validator("sites_in_groups") @@ -426,13 +426,13 @@ class StructureResourceAttributes(EntryResourceAttributes): - **Requirements/Conventions**: - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`. - **Query**: Support for queries on this property is OPTIONAL. - If supported, filters MAY support only a subset of comparison operators. + If supported, filters MAY support only a subset of comparison operators. - 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. - (Therefore, the first index runs over the three lattice vectors and the second index runs over the x, y, z Cartesian coordinates). + (Therefore, the first index runs over the three lattice vectors and the second index runs over the x, y, z Cartesian coordinates). - 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. - MUST always contain three vectors of three coordinates each, independently of the elements of property `dimension_types`. - The vectors SHOULD by convention be chosen so the determinant of the `lattice_vectors` matrix is different from zero. - The vectors in the non-periodic directions have no significance beyond fulfilling these requirements. + The vectors SHOULD by convention be chosen so the determinant of the `lattice_vectors` matrix is different from zero. + The vectors in the non-periodic directions have no significance beyond fulfilling these requirements. - 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. If a lattice vector contains the value `null`, all coordinates of that lattice vector MUST be `null`. @@ -451,7 +451,7 @@ class StructureResourceAttributes(EntryResourceAttributes): - **Requirements/Conventions**: - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`. - **Query**: Support for queries on this property is OPTIONAL. - If supported, filters MAY support only a subset of comparison operators. + If supported, filters MAY support only a subset of comparison operators. - 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 (Å). - An entry MAY have multiple sites at the same Cartesian position (for a relevant use of this, see e.g., the property `assemblies`). @@ -502,7 +502,7 @@ class StructureResourceAttributes(EntryResourceAttributes): - the special value `"X"` to represent a non-chemical element, or - 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). - 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` (see property [structure_features](#structure_features)). + 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`. - **concentration**: REQUIRED; 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. @@ -517,8 +517,8 @@ class StructureResourceAttributes(EntryResourceAttributes): - **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. - 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. - Furthermore, if they are provided, the [structure_features](#structure_features) property MUST include the string `site_attachments`. + 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. + Furthermore, if they are provided, the `structure_features` property MUST include the string `site_attachments`. - **mass**: OPTIONAL. If present MUST be a float expressed in a.m.u. @@ -526,7 +526,7 @@ class StructureResourceAttributes(EntryResourceAttributes): Note: With regards to "source database", we refer to the immediate source being queried via the OPTIMADE API implementation. - 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](#species_at_sites)). + 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`). - 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.) 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. From edc65131229dc6c659ba3fa33d8f5c9b6c7c77c2 Mon Sep 17 00:00:00 2001 From: Matthew Evans Date: Wed, 24 Jun 2020 16:46:59 +0100 Subject: [PATCH 7/8] Updated descriptions of query params --- openapi/index_openapi.json | 36 ++++---- openapi/openapi.json | 140 ++++++++++++++++---------------- optimade/server/query_params.py | 138 ++++++++++++++----------------- 3 files changed, 149 insertions(+), 165 deletions(-) diff --git a/openapi/index_openapi.json b/openapi/index_openapi.json index 511cc56cb..3bfa0b3bc 100644 --- a/openapi/index_openapi.json +++ b/openapi/index_openapi.json @@ -44,36 +44,36 @@ "operationId": "get_links_v0_links_get", "parameters": [ { - "description": "A filter string, in the format described in section [API Filtering Format Specification](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#api-filtering-format-specification) of the [OPTIMADE spec](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst).", + "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](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#api-filtering-format-specification) of the [OPTIMADE spec](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst).", + "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](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#response-format) in the spec). Defaults to the format string 'json', which specifies the standard output format described in this specification.\n**Example**: http://example.com/v1/structures?response_format=xml", + "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](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#response-format) in the spec). Defaults to the format string 'json', which specifies the standard output format described in this specification.\n**Example**: http://example.com/v1/structures?response_format=xml", + "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. The email SHOULD be that of a person and not an automatic system.\n**Example**: http://example.com/v1/structures?email_address=user@example.com", + "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. The email SHOULD be that of a person and not an automatic system.\n**Example**: http://example.com/v1/structures?email_address=user@example.com", + "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": "" }, @@ -81,65 +81,65 @@ "in": "query" }, { - "description": "A comma-delimited set of fields to be provided in the output. If provided, these fields MUST be returned along with the REQUIRED fields. Other OPTIONAL fields MUST NOT be returned when this parameter is present.\n**Example**: http://example.com/v1/structures?response_fields=last_modified,nsites", + "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. If provided, these fields MUST be returned along with the REQUIRED fields. Other OPTIONAL fields MUST NOT be returned when this parameter is present.\n**Example**: http://example.com/v1/structures?response_fields=last_modified,nsites", + "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. If it does, it again MUST conform to the JSON API 1.0 specification.\n\nIf an implementation supports sorting for an [entry listing endpoint](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#entry-listing-endpoints), 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`. If 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. The 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. The field `sortable` is in addition to each property description (and the OPTIONAL field `unit`). An example is shown in section [Entry Listing Info Endpoints](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#entry-listing-info-endpoints).", + "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).\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.\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. If it does, it again MUST conform to the JSON API 1.0 specification.\n\nIf an implementation supports sorting for an [entry listing endpoint](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#entry-listing-endpoints), 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`. If 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. The 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. The field `sortable` is in addition to each property description (and the OPTIONAL field `unit`). An example is shown in section [Entry Listing Info Endpoints](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#entry-listing-info-endpoints).", + "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).\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.\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. See [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-pagination). The API implementation MUST return no more than the number specified. It MAY return fewer. The database MAY have a maximum limit and not accept larger numbers (in which case an error code -- 403 Forbidden -- MUST be returned). The default limit value is up to the API implementation to decide.\n\nA server MUST implement pagination in the case of no user-specified `sort` parameter (via the `links` response field, see section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-schema-common-fields)). A server MAY implement pagination in concert with `sort`.", + "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. See [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-pagination). The API implementation MUST return no more than the number specified. It MAY return fewer. The database MAY have a maximum limit and not accept larger numbers (in which case an error code -- 403 Forbidden -- MUST be returned). The default limit value is up to the API implementation to decide.\n\nA server MUST implement pagination in the case of no user-specified `sort` parameter (via the `links` response field, see section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-schema-common-fields)). A server MAY implement pagination in concert with `sort`.", + "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.\n**Example**: Skip 50 structures and fetch up to 100: `/structures?page_offset=50&page_limit=100`.", + "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.\n**Example**: Skip 50 structures and fetch up to 100: `/structures?page_offset=50&page_limit=100`.", + "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. It is RECOMMENDED that the first page has number 1, i.e., that `page_number` is 1-based.\n**Example**: Fetch page 2 of up to 50 structures per page: `/structures?page_number=2&page_limit=50`.", + "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", "minimum": 0.0, "type": "integer", - "description": "RECOMMENDED for use with _page-based_ pagination: using `page_number` and `page_limit` is RECOMMENDED. It is RECOMMENDED that the first page has number 1, i.e., that `page_number` is 1-based.\n**Example**: Fetch page 2 of up to 50 structures per page: `/structures?page_number=2&page_limit=50`.", + "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`.", "default": 0 }, "name": "page_number", @@ -185,12 +185,12 @@ "in": "query" }, { - "description": "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 section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#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). If 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`. This 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`. Note, 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](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#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`.", + "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).\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`.\n> Note, 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.", "required": false, "schema": { "title": "Include", "type": "string", - "description": "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 section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#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). If 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`. This 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`. Note, 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](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#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`.", + "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).\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`.\n> Note, 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.", "default": "references" }, "name": "include", diff --git a/openapi/openapi.json b/openapi/openapi.json index 896c90ffd..c695604b0 100644 --- a/openapi/openapi.json +++ b/openapi/openapi.json @@ -94,36 +94,36 @@ "operationId": "get_links_v0_links_get", "parameters": [ { - "description": "A filter string, in the format described in section [API Filtering Format Specification](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#api-filtering-format-specification) of the [OPTIMADE spec](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst).", + "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](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#api-filtering-format-specification) of the [OPTIMADE spec](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst).", + "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](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#response-format) in the spec). Defaults to the format string 'json', which specifies the standard output format described in this specification.\n**Example**: http://example.com/v1/structures?response_format=xml", + "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](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#response-format) in the spec). Defaults to the format string 'json', which specifies the standard output format described in this specification.\n**Example**: http://example.com/v1/structures?response_format=xml", + "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. The email SHOULD be that of a person and not an automatic system.\n**Example**: http://example.com/v1/structures?email_address=user@example.com", + "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. The email SHOULD be that of a person and not an automatic system.\n**Example**: http://example.com/v1/structures?email_address=user@example.com", + "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": "" }, @@ -131,65 +131,65 @@ "in": "query" }, { - "description": "A comma-delimited set of fields to be provided in the output. If provided, these fields MUST be returned along with the REQUIRED fields. Other OPTIONAL fields MUST NOT be returned when this parameter is present.\n**Example**: http://example.com/v1/structures?response_fields=last_modified,nsites", + "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. If provided, these fields MUST be returned along with the REQUIRED fields. Other OPTIONAL fields MUST NOT be returned when this parameter is present.\n**Example**: http://example.com/v1/structures?response_fields=last_modified,nsites", + "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. If it does, it again MUST conform to the JSON API 1.0 specification.\n\nIf an implementation supports sorting for an [entry listing endpoint](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#entry-listing-endpoints), 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`. If 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. The 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. The field `sortable` is in addition to each property description (and the OPTIONAL field `unit`). An example is shown in section [Entry Listing Info Endpoints](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#entry-listing-info-endpoints).", + "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).\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.\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. If it does, it again MUST conform to the JSON API 1.0 specification.\n\nIf an implementation supports sorting for an [entry listing endpoint](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#entry-listing-endpoints), 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`. If 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. The 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. The field `sortable` is in addition to each property description (and the OPTIONAL field `unit`). An example is shown in section [Entry Listing Info Endpoints](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#entry-listing-info-endpoints).", + "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).\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.\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. See [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-pagination). The API implementation MUST return no more than the number specified. It MAY return fewer. The database MAY have a maximum limit and not accept larger numbers (in which case an error code -- 403 Forbidden -- MUST be returned). The default limit value is up to the API implementation to decide.\n\nA server MUST implement pagination in the case of no user-specified `sort` parameter (via the `links` response field, see section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-schema-common-fields)). A server MAY implement pagination in concert with `sort`.", + "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. See [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-pagination). The API implementation MUST return no more than the number specified. It MAY return fewer. The database MAY have a maximum limit and not accept larger numbers (in which case an error code -- 403 Forbidden -- MUST be returned). The default limit value is up to the API implementation to decide.\n\nA server MUST implement pagination in the case of no user-specified `sort` parameter (via the `links` response field, see section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-schema-common-fields)). A server MAY implement pagination in concert with `sort`.", + "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.\n**Example**: Skip 50 structures and fetch up to 100: `/structures?page_offset=50&page_limit=100`.", + "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.\n**Example**: Skip 50 structures and fetch up to 100: `/structures?page_offset=50&page_limit=100`.", + "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. It is RECOMMENDED that the first page has number 1, i.e., that `page_number` is 1-based.\n**Example**: Fetch page 2 of up to 50 structures per page: `/structures?page_number=2&page_limit=50`.", + "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", "minimum": 0.0, "type": "integer", - "description": "RECOMMENDED for use with _page-based_ pagination: using `page_number` and `page_limit` is RECOMMENDED. It is RECOMMENDED that the first page has number 1, i.e., that `page_number` is 1-based.\n**Example**: Fetch page 2 of up to 50 structures per page: `/structures?page_number=2&page_limit=50`.", + "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`.", "default": 0 }, "name": "page_number", @@ -235,12 +235,12 @@ "in": "query" }, { - "description": "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 section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#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). If 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`. This 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`. Note, 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](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#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`.", + "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).\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`.\n> Note, 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.", "required": false, "schema": { "title": "Include", "type": "string", - "description": "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 section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#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). If 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`. This 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`. Note, 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](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#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`.", + "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).\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`.\n> Note, 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.", "default": "references" }, "name": "include", @@ -288,36 +288,36 @@ "operationId": "get_references_v0_references_get", "parameters": [ { - "description": "A filter string, in the format described in section [API Filtering Format Specification](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#api-filtering-format-specification) of the [OPTIMADE spec](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst).", + "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](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#api-filtering-format-specification) of the [OPTIMADE spec](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst).", + "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](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#response-format) in the spec). Defaults to the format string 'json', which specifies the standard output format described in this specification.\n**Example**: http://example.com/v1/structures?response_format=xml", + "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](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#response-format) in the spec). Defaults to the format string 'json', which specifies the standard output format described in this specification.\n**Example**: http://example.com/v1/structures?response_format=xml", + "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. The email SHOULD be that of a person and not an automatic system.\n**Example**: http://example.com/v1/structures?email_address=user@example.com", + "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. The email SHOULD be that of a person and not an automatic system.\n**Example**: http://example.com/v1/structures?email_address=user@example.com", + "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": "" }, @@ -325,65 +325,65 @@ "in": "query" }, { - "description": "A comma-delimited set of fields to be provided in the output. If provided, these fields MUST be returned along with the REQUIRED fields. Other OPTIONAL fields MUST NOT be returned when this parameter is present.\n**Example**: http://example.com/v1/structures?response_fields=last_modified,nsites", + "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. If provided, these fields MUST be returned along with the REQUIRED fields. Other OPTIONAL fields MUST NOT be returned when this parameter is present.\n**Example**: http://example.com/v1/structures?response_fields=last_modified,nsites", + "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. If it does, it again MUST conform to the JSON API 1.0 specification.\n\nIf an implementation supports sorting for an [entry listing endpoint](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#entry-listing-endpoints), 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`. If 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. The 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. The field `sortable` is in addition to each property description (and the OPTIONAL field `unit`). An example is shown in section [Entry Listing Info Endpoints](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#entry-listing-info-endpoints).", + "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).\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.\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. If it does, it again MUST conform to the JSON API 1.0 specification.\n\nIf an implementation supports sorting for an [entry listing endpoint](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#entry-listing-endpoints), 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`. If 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. The 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. The field `sortable` is in addition to each property description (and the OPTIONAL field `unit`). An example is shown in section [Entry Listing Info Endpoints](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#entry-listing-info-endpoints).", + "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).\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.\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. See [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-pagination). The API implementation MUST return no more than the number specified. It MAY return fewer. The database MAY have a maximum limit and not accept larger numbers (in which case an error code -- 403 Forbidden -- MUST be returned). The default limit value is up to the API implementation to decide.\n\nA server MUST implement pagination in the case of no user-specified `sort` parameter (via the `links` response field, see section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-schema-common-fields)). A server MAY implement pagination in concert with `sort`.", + "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. See [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-pagination). The API implementation MUST return no more than the number specified. It MAY return fewer. The database MAY have a maximum limit and not accept larger numbers (in which case an error code -- 403 Forbidden -- MUST be returned). The default limit value is up to the API implementation to decide.\n\nA server MUST implement pagination in the case of no user-specified `sort` parameter (via the `links` response field, see section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-schema-common-fields)). A server MAY implement pagination in concert with `sort`.", + "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.\n**Example**: Skip 50 structures and fetch up to 100: `/structures?page_offset=50&page_limit=100`.", + "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.\n**Example**: Skip 50 structures and fetch up to 100: `/structures?page_offset=50&page_limit=100`.", + "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. It is RECOMMENDED that the first page has number 1, i.e., that `page_number` is 1-based.\n**Example**: Fetch page 2 of up to 50 structures per page: `/structures?page_number=2&page_limit=50`.", + "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", "minimum": 0.0, "type": "integer", - "description": "RECOMMENDED for use with _page-based_ pagination: using `page_number` and `page_limit` is RECOMMENDED. It is RECOMMENDED that the first page has number 1, i.e., that `page_number` is 1-based.\n**Example**: Fetch page 2 of up to 50 structures per page: `/structures?page_number=2&page_limit=50`.", + "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`.", "default": 0 }, "name": "page_number", @@ -429,12 +429,12 @@ "in": "query" }, { - "description": "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 section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#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). If 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`. This 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`. Note, 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](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#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`.", + "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).\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`.\n> Note, 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.", "required": false, "schema": { "title": "Include", "type": "string", - "description": "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 section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#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). If 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`. This 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`. Note, 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](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#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`.", + "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).\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`.\n> Note, 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.", "default": "references" }, "name": "include", @@ -491,24 +491,24 @@ "in": "path" }, { - "description": "The output format requested (see section [Response Format](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#response-format) in the spec). Defaults to the format string 'json', which specifies the standard output format described in this specification.\n**Example**: http://example.com/v1/structures?response_format=xml", + "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](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#response-format) in the spec). Defaults to the format string 'json', which specifies the standard output format described in this specification.\n**Example**: http://example.com/v1/structures?response_format=xml", + "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. The email SHOULD be that of a person and not an automatic system.\n**Example**: http://example.com/v1/structures?email_address=user@example.com", + "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. The email SHOULD be that of a person and not an automatic system.\n**Example**: http://example.com/v1/structures?email_address=user@example.com", + "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": "" }, @@ -516,25 +516,25 @@ "in": "query" }, { - "description": "A comma-delimited set of fields to be provided in the output. If provided, these fields MUST be returned along with the REQUIRED fields. Other OPTIONAL fields MUST NOT be returned when this parameter is present.\n**Example**: http://example.com/v1/structures?response_fields=last_modified,nsites", + "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. If provided, these fields MUST be returned along with the REQUIRED fields. Other OPTIONAL fields MUST NOT be returned when this parameter is present.\n**Example**: http://example.com/v1/structures?response_fields=last_modified,nsites", + "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": "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 section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#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). If 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`. This 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`. Note, 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](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#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`.", + "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).\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`.\n> Note, 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.", "required": false, "schema": { "title": "Include", "type": "string", - "description": "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 section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#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). If 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`. This 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`. Note, 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](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#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`.", + "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).\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`.\n> Note, 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.", "default": "references" }, "name": "include", @@ -582,36 +582,36 @@ "operationId": "get_structures_v0_structures_get", "parameters": [ { - "description": "A filter string, in the format described in section [API Filtering Format Specification](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#api-filtering-format-specification) of the [OPTIMADE spec](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst).", + "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](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#api-filtering-format-specification) of the [OPTIMADE spec](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst).", + "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](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#response-format) in the spec). Defaults to the format string 'json', which specifies the standard output format described in this specification.\n**Example**: http://example.com/v1/structures?response_format=xml", + "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](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#response-format) in the spec). Defaults to the format string 'json', which specifies the standard output format described in this specification.\n**Example**: http://example.com/v1/structures?response_format=xml", + "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. The email SHOULD be that of a person and not an automatic system.\n**Example**: http://example.com/v1/structures?email_address=user@example.com", + "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. The email SHOULD be that of a person and not an automatic system.\n**Example**: http://example.com/v1/structures?email_address=user@example.com", + "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": "" }, @@ -619,65 +619,65 @@ "in": "query" }, { - "description": "A comma-delimited set of fields to be provided in the output. If provided, these fields MUST be returned along with the REQUIRED fields. Other OPTIONAL fields MUST NOT be returned when this parameter is present.\n**Example**: http://example.com/v1/structures?response_fields=last_modified,nsites", + "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. If provided, these fields MUST be returned along with the REQUIRED fields. Other OPTIONAL fields MUST NOT be returned when this parameter is present.\n**Example**: http://example.com/v1/structures?response_fields=last_modified,nsites", + "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. If it does, it again MUST conform to the JSON API 1.0 specification.\n\nIf an implementation supports sorting for an [entry listing endpoint](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#entry-listing-endpoints), 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`. If 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. The 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. The field `sortable` is in addition to each property description (and the OPTIONAL field `unit`). An example is shown in section [Entry Listing Info Endpoints](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#entry-listing-info-endpoints).", + "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).\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.\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. If it does, it again MUST conform to the JSON API 1.0 specification.\n\nIf an implementation supports sorting for an [entry listing endpoint](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#entry-listing-endpoints), 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`. If 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. The 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. The field `sortable` is in addition to each property description (and the OPTIONAL field `unit`). An example is shown in section [Entry Listing Info Endpoints](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#entry-listing-info-endpoints).", + "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).\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.\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. See [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-pagination). The API implementation MUST return no more than the number specified. It MAY return fewer. The database MAY have a maximum limit and not accept larger numbers (in which case an error code -- 403 Forbidden -- MUST be returned). The default limit value is up to the API implementation to decide.\n\nA server MUST implement pagination in the case of no user-specified `sort` parameter (via the `links` response field, see section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-schema-common-fields)). A server MAY implement pagination in concert with `sort`.", + "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. See [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-pagination). The API implementation MUST return no more than the number specified. It MAY return fewer. The database MAY have a maximum limit and not accept larger numbers (in which case an error code -- 403 Forbidden -- MUST be returned). The default limit value is up to the API implementation to decide.\n\nA server MUST implement pagination in the case of no user-specified `sort` parameter (via the `links` response field, see section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-schema-common-fields)). A server MAY implement pagination in concert with `sort`.", + "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.\n**Example**: Skip 50 structures and fetch up to 100: `/structures?page_offset=50&page_limit=100`.", + "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.\n**Example**: Skip 50 structures and fetch up to 100: `/structures?page_offset=50&page_limit=100`.", + "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. It is RECOMMENDED that the first page has number 1, i.e., that `page_number` is 1-based.\n**Example**: Fetch page 2 of up to 50 structures per page: `/structures?page_number=2&page_limit=50`.", + "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", "minimum": 0.0, "type": "integer", - "description": "RECOMMENDED for use with _page-based_ pagination: using `page_number` and `page_limit` is RECOMMENDED. It is RECOMMENDED that the first page has number 1, i.e., that `page_number` is 1-based.\n**Example**: Fetch page 2 of up to 50 structures per page: `/structures?page_number=2&page_limit=50`.", + "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`.", "default": 0 }, "name": "page_number", @@ -723,12 +723,12 @@ "in": "query" }, { - "description": "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 section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#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). If 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`. This 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`. Note, 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](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#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`.", + "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).\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`.\n> Note, 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.", "required": false, "schema": { "title": "Include", "type": "string", - "description": "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 section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#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). If 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`. This 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`. Note, 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](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#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`.", + "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).\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`.\n> Note, 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.", "default": "references" }, "name": "include", @@ -785,24 +785,24 @@ "in": "path" }, { - "description": "The output format requested (see section [Response Format](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#response-format) in the spec). Defaults to the format string 'json', which specifies the standard output format described in this specification.\n**Example**: http://example.com/v1/structures?response_format=xml", + "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](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#response-format) in the spec). Defaults to the format string 'json', which specifies the standard output format described in this specification.\n**Example**: http://example.com/v1/structures?response_format=xml", + "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. The email SHOULD be that of a person and not an automatic system.\n**Example**: http://example.com/v1/structures?email_address=user@example.com", + "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. The email SHOULD be that of a person and not an automatic system.\n**Example**: http://example.com/v1/structures?email_address=user@example.com", + "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": "" }, @@ -810,25 +810,25 @@ "in": "query" }, { - "description": "A comma-delimited set of fields to be provided in the output. If provided, these fields MUST be returned along with the REQUIRED fields. Other OPTIONAL fields MUST NOT be returned when this parameter is present.\n**Example**: http://example.com/v1/structures?response_fields=last_modified,nsites", + "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. If provided, these fields MUST be returned along with the REQUIRED fields. Other OPTIONAL fields MUST NOT be returned when this parameter is present.\n**Example**: http://example.com/v1/structures?response_fields=last_modified,nsites", + "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": "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 section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#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). If 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`. This 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`. Note, 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](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#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`.", + "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).\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`.\n> Note, 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.", "required": false, "schema": { "title": "Include", "type": "string", - "description": "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 section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#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). If 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`. This 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`. Note, 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](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#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`.", + "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).\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`.\n> Note, 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.", "default": "references" }, "name": "include", diff --git a/optimade/server/query_params.py b/optimade/server/query_params.py index 1d63065ae..ecc44ccef 100644 --- a/optimade/server/query_params.py +++ b/optimade/server/query_params.py @@ -12,65 +12,62 @@ def __init__( *, filter: str = Query( # pylint: disable=redefined-builtin "", - description="A filter string, in the format described in section [API Filtering Format Specification]" - "(https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#api-filtering-format-specification) " - "of the [OPTIMADE spec](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst).", + description="A filter string, in the format described in section API Filtering Format Specification of the specification.", ), response_format: str = Query( "json", - description="The output format requested (see section [Response Format](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/" - "optimade.rst#response-format) in the spec). Defaults to the format string 'json', which specifies the standard output format " - "described in this specification.\n**Example**: http://example.com/v1/structures?response_format=xml", + description="""The output format requested (see section Response Format). +Defaults to the format string 'json', which specifies the standard output format described in this specification. +Example: `http://example.com/v1/structures?response_format=xml`""", ), email_address: EmailStr = Query( "", - description="An email address of the user making the request. The email SHOULD be that of a person and not an automatic system.\n" - "**Example**: http://example.com/v1/structures?email_address=user@example.com", + description="""An email address of the user making the request. +The email SHOULD be that of a person and not an automatic system. +Example: `http://example.com/v1/structures?email_address=user@example.com`""", ), response_fields: str = Query( "", - description="A comma-delimited set of fields to be provided in the output. If provided, these fields MUST be returned along with " - "the REQUIRED fields. Other OPTIONAL fields MUST NOT be returned when this parameter is present.\n" - "**Example**: http://example.com/v1/structures?response_fields=last_modified,nsites", + description="""A comma-delimited set of fields to be provided in the output. +If provided, these fields MUST be returned along with the REQUIRED fields. +Other OPTIONAL fields MUST NOT be returned when this parameter is present. +Example: `http://example.com/v1/structures?response_fields=last_modified,nsites`""", regex=r"([a-z_][a-z_0-9]*(,[a-z_][a-z_0-9]*)*)?", ), sort: str = 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\n" - "An implementation MAY support multiple sort fields for a single query. If it does, it again MUST conform to the JSON API 1.0 specification.\n\n" - "If an implementation supports sorting for an [entry listing endpoint](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst" - "#entry-listing-endpoints), 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`. " - "If 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. The 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. The field `sortable` is in addition to each property ' - "description (and the OPTIONAL field `unit`). An example is shown in section " - "[Entry Listing Info Endpoints](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#entry-listing-info-endpoints).", + 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). +An implementation MAY support multiple sort fields for a single query. +If it does, it again MUST conform to the JSON API 1.0 specification. +If 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`. +If 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. +The 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. +The field `sortable` is in addition to each property description and other OPTIONAL fields. +An example is shown in the section Entry Listing Info Endpoints.""", regex=r"([a-z_][a-z_0-9]*(,[a-z_][a-z_0-9]*)*)?", ), page_limit: int = Query( CONFIG.page_limit, - description="Sets a numerical limit on the number of entries returned. " - "See [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-pagination). The API implementation MUST return no more than the number specified. " - "It MAY return fewer. The database MAY have a maximum limit and not accept larger numbers (in which case an error code -- 403 Forbidden -- " - "MUST be returned). The default limit value is up to the API implementation to decide.\n\n" - "A server MUST implement pagination in the case of no user-specified `sort` parameter (via the `links` response field, see section " - "[JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-schema-" - "common-fields)). A server MAY implement pagination in concert with `sort`.", + description="""Sets a numerical limit on the number of entries returned. +See [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-pagination). +The API implementation MUST return no more than the number specified. +It MAY return fewer. +The database MAY have a maximum limit and not accept larger numbers (in which case an error code -- 403 Forbidden -- MUST be returned). +The default limit value is up to the API implementation to decide. +Example: `http://example.com/optimade/v1/structures?page_limit=100`""", ge=0, ), page_offset: int = Query( 0, - description="RECOMMENDED for use with _offset-based_ pagination: using `page_offset` and `page_limit` is RECOMMENDED.\n" - "**Example**: Skip 50 structures and fetch up to 100: `/structures?page_offset=50&page_limit=100`.", + description="""RECOMMENDED for use with _offset-based_ pagination: using `page_offset` and `page_limit` is RECOMMENDED. +Example: skip 50 structures and fetch up to 100: `/structures?page_offset=50&page_limit=100`.""", ge=0, ), page_number: int = Query( 0, - description="RECOMMENDED for use with _page-based_ pagination: using `page_number` and `page_limit` is RECOMMENDED. " - "It is RECOMMENDED that the first page has number 1, i.e., that `page_number` is 1-based.\n" - "**Example**: Fetch page 2 of up to 50 structures per page: `/structures?page_number=2&page_limit=50`.", + description="""RECOMMENDED for use with _page-based_ pagination: using `page_number` and `page_limit` is RECOMMENDED. +It is RECOMMENDED that the first page has number 1, i.e., that `page_number` is 1-based." +Example: fetch page 2 of up to 50 structures per page: `/structures?page_number=2&page_limit=50`.""", ge=0, ), page_cursor: int = Query( @@ -80,9 +77,8 @@ def __init__( ), page_above: int = Query( 0, - description="RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.\n" - "**Example**: 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`.", + description="""RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED. +**Example**: 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`.""", ge=0, ), page_below: int = Query( @@ -92,22 +88,15 @@ def __init__( ), include: str = Query( "references", - description="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\n" - "All related resource objects MUST be returned as part of an array value for the top-level `included` field, see section " - "[JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-" - "schema-common-fields).\n\n" - 'The 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). If relationship paths are not supported, or a server is unable " - "to identify a relationship path a `400 Bad Request` response MUST be made.\n\n" - "The **default value** for `include` is `references`. This 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`. Note, 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](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#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`.", + 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). +All 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. + +The 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). +If relationship paths are not supported, or a server is unable to identify a relationship path a `400 Bad Request` response MUST be made. + +The **default value** for `include` is `references`. +This 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`. +> Note, 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.""", ), ): self.filter = filter @@ -132,40 +121,35 @@ def __init__( *, response_format: str = Query( "json", - description="The output format requested (see section [Response Format](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/" - "optimade.rst#response-format) in the spec). Defaults to the format string 'json', which specifies the standard output format " - "described in this specification.\n**Example**: http://example.com/v1/structures?response_format=xml", + description="""The output format requested (see section Response Format). +Defaults to the format string 'json', which specifies the standard output format described in this specification. +Example: `http://example.com/v1/structures?response_format=xml`""", ), email_address: EmailStr = Query( "", - description="An email address of the user making the request. The email SHOULD be that of a person and not an automatic system.\n" - "**Example**: http://example.com/v1/structures?email_address=user@example.com", + description="""An email address of the user making the request. +The email SHOULD be that of a person and not an automatic system. +Example: `http://example.com/v1/structures?email_address=user@example.com`""", ), response_fields: str = Query( "", - description="A comma-delimited set of fields to be provided in the output. If provided, these fields MUST be returned along with " - "the REQUIRED fields. Other OPTIONAL fields MUST NOT be returned when this parameter is present.\n" - "**Example**: http://example.com/v1/structures?response_fields=last_modified,nsites", + description="""A comma-delimited set of fields to be provided in the output. +If provided, these fields MUST be returned along with the REQUIRED fields. +Other OPTIONAL fields MUST NOT be returned when this parameter is present. +Example: `http://example.com/v1/structures?response_fields=last_modified,nsites`""", regex=r"([a-z_][a-z_0-9]*(,[a-z_][a-z_0-9]*)*)?", ), include: str = Query( "references", - description="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\n" - "All related resource objects MUST be returned as part of an array value for the top-level `included` field, see section " - "[JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-" - "schema-common-fields).\n\n" - 'The 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). If relationship paths are not supported, or a server is unable " - "to identify a relationship path a `400 Bad Request` response MUST be made.\n\n" - "The **default value** for `include` is `references`. This 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`. Note, 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](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#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`.", + 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). +All 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. + +The 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). +If relationship paths are not supported, or a server is unable to identify a relationship path a `400 Bad Request` response MUST be made. + +The **default value** for `include` is `references`. +This 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`. +> Note, 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.""", ), ): self.response_format = response_format From a99d3de2d827ca30de80d50a61ed431971bfd6a5 Mon Sep 17 00:00:00 2001 From: Casper Welzel Andersen Date: Thu, 25 Jun 2020 09:59:14 +0200 Subject: [PATCH 8/8] Revert to single-line desc for query params Also, apply review comments. --- openapi/index_openapi.json | 20 ++++----- openapi/openapi.json | 68 +++++++++++++++--------------- optimade/server/query_params.py | 73 ++++++--------------------------- 3 files changed, 57 insertions(+), 104 deletions(-) diff --git a/openapi/index_openapi.json b/openapi/index_openapi.json index 3bfa0b3bc..48e5738b0 100644 --- a/openapi/index_openapi.json +++ b/openapi/index_openapi.json @@ -94,13 +94,13 @@ "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).\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.\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.", + "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).\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.\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.", + "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", @@ -120,26 +120,26 @@ "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`.", + "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`.", + "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`.", + "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", "minimum": 0.0, "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`.", + "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`.", "default": 0 }, "name": "page_number", @@ -159,13 +159,13 @@ "in": "query" }, { - "description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.\n**Example**: 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`.", + "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.\n**Example**: 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`.", + "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", @@ -185,12 +185,12 @@ "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).\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`.\n> Note, 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.", + "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).\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`.\n> Note, 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.", + "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", diff --git a/openapi/openapi.json b/openapi/openapi.json index c695604b0..3ce69d2bd 100644 --- a/openapi/openapi.json +++ b/openapi/openapi.json @@ -144,13 +144,13 @@ "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).\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.\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.", + "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).\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.\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.", + "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", @@ -170,26 +170,26 @@ "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`.", + "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`.", + "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`.", + "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", "minimum": 0.0, "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`.", + "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`.", "default": 0 }, "name": "page_number", @@ -209,13 +209,13 @@ "in": "query" }, { - "description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.\n**Example**: 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`.", + "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.\n**Example**: 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`.", + "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", @@ -235,12 +235,12 @@ "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).\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`.\n> Note, 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.", + "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).\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`.\n> Note, 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.", + "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", @@ -338,13 +338,13 @@ "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).\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.\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.", + "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).\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.\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.", + "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", @@ -364,26 +364,26 @@ "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`.", + "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`.", + "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`.", + "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", "minimum": 0.0, "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`.", + "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`.", "default": 0 }, "name": "page_number", @@ -403,13 +403,13 @@ "in": "query" }, { - "description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.\n**Example**: 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`.", + "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.\n**Example**: 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`.", + "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", @@ -429,12 +429,12 @@ "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).\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`.\n> Note, 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.", + "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).\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`.\n> Note, 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.", + "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", @@ -529,12 +529,12 @@ "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).\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`.\n> Note, 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.", + "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).\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`.\n> Note, 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.", + "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", @@ -632,13 +632,13 @@ "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).\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.\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.", + "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).\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.\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.", + "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", @@ -658,26 +658,26 @@ "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`.", + "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`.", + "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`.", + "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", "minimum": 0.0, "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`.", + "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`.", "default": 0 }, "name": "page_number", @@ -697,13 +697,13 @@ "in": "query" }, { - "description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.\n**Example**: 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`.", + "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.\n**Example**: 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`.", + "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", @@ -723,12 +723,12 @@ "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).\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`.\n> Note, 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.", + "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).\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`.\n> Note, 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.", + "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", @@ -823,12 +823,12 @@ "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).\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`.\n> Note, 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.", + "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).\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`.\n> Note, 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.", + "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", diff --git a/optimade/server/query_params.py b/optimade/server/query_params.py index ecc44ccef..477e85c6f 100644 --- a/optimade/server/query_params.py +++ b/optimade/server/query_params.py @@ -16,58 +16,35 @@ def __init__( ), response_format: str = Query( "json", - description="""The output format requested (see section Response Format). -Defaults to the format string 'json', which specifies the standard output format described in this specification. -Example: `http://example.com/v1/structures?response_format=xml`""", + 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`", ), email_address: EmailStr = Query( "", - description="""An email address of the user making the request. -The email SHOULD be that of a person and not an automatic system. -Example: `http://example.com/v1/structures?email_address=user@example.com`""", + 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`", ), response_fields: str = Query( "", - description="""A comma-delimited set of fields to be provided in the output. -If provided, these fields MUST be returned along with the REQUIRED fields. -Other OPTIONAL fields MUST NOT be returned when this parameter is present. -Example: `http://example.com/v1/structures?response_fields=last_modified,nsites`""", + 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`", regex=r"([a-z_][a-z_0-9]*(,[a-z_][a-z_0-9]*)*)?", ), sort: str = 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). -An implementation MAY support multiple sort fields for a single query. -If it does, it again MUST conform to the JSON API 1.0 specification. -If 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`. -If 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. -The 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. -The field `sortable` is in addition to each property description and other OPTIONAL fields. -An example is shown in the section Entry Listing Info Endpoints.""", + 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.', regex=r"([a-z_][a-z_0-9]*(,[a-z_][a-z_0-9]*)*)?", ), page_limit: int = Query( CONFIG.page_limit, - description="""Sets a numerical limit on the number of entries returned. -See [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-pagination). -The API implementation MUST return no more than the number specified. -It MAY return fewer. -The database MAY have a maximum limit and not accept larger numbers (in which case an error code -- 403 Forbidden -- MUST be returned). -The default limit value is up to the API implementation to decide. -Example: `http://example.com/optimade/v1/structures?page_limit=100`""", + 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`", ge=0, ), page_offset: int = Query( 0, - description="""RECOMMENDED for use with _offset-based_ pagination: using `page_offset` and `page_limit` is RECOMMENDED. -Example: skip 50 structures and fetch up to 100: `/structures?page_offset=50&page_limit=100`.""", + 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`.", ge=0, ), page_number: int = Query( 0, - description="""RECOMMENDED for use with _page-based_ pagination: using `page_number` and `page_limit` is RECOMMENDED. -It is RECOMMENDED that the first page has number 1, i.e., that `page_number` is 1-based." -Example: fetch page 2 of up to 50 structures per page: `/structures?page_number=2&page_limit=50`.""", + 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`.", ge=0, ), page_cursor: int = Query( @@ -77,8 +54,7 @@ def __init__( ), page_above: int = Query( 0, - description="""RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED. -**Example**: 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`.""", + 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`.", ge=0, ), page_below: int = Query( @@ -88,15 +64,7 @@ def __init__( ), include: str = Query( "references", - 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). -All 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. - -The 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). -If relationship paths are not supported, or a server is unable to identify a relationship path a `400 Bad Request` response MUST be made. - -The **default value** for `include` is `references`. -This 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`. -> Note, 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.""", + 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`.', ), ): self.filter = filter @@ -121,35 +89,20 @@ def __init__( *, response_format: str = Query( "json", - description="""The output format requested (see section Response Format). -Defaults to the format string 'json', which specifies the standard output format described in this specification. -Example: `http://example.com/v1/structures?response_format=xml`""", + 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`", ), email_address: EmailStr = Query( "", - description="""An email address of the user making the request. -The email SHOULD be that of a person and not an automatic system. -Example: `http://example.com/v1/structures?email_address=user@example.com`""", + 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`", ), response_fields: str = Query( "", - description="""A comma-delimited set of fields to be provided in the output. -If provided, these fields MUST be returned along with the REQUIRED fields. -Other OPTIONAL fields MUST NOT be returned when this parameter is present. -Example: `http://example.com/v1/structures?response_fields=last_modified,nsites`""", + 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`", regex=r"([a-z_][a-z_0-9]*(,[a-z_][a-z_0-9]*)*)?", ), include: str = Query( "references", - 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). -All 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. - -The 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). -If relationship paths are not supported, or a server is unable to identify a relationship path a `400 Bad Request` response MUST be made. - -The **default value** for `include` is `references`. -This 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`. -> Note, 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.""", + 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`.', ), ): self.response_format = response_format