From d0d0a3a74842403234989059a9018d11f7dab22a Mon Sep 17 00:00:00 2001 From: Matthew Evans Date: Fri, 12 Aug 2022 12:51:41 +0100 Subject: [PATCH 1/4] Add OpenAPI schemas from `optimade-python-tools` v0.19.1 --- openapi/v1.1.0/optimade.json | 536 +++++++++++++++++++---------- openapi/v1.1.0/optimade_index.json | 175 ++++++---- 2 files changed, 450 insertions(+), 261 deletions(-) diff --git a/openapi/v1.1.0/optimade.json b/openapi/v1.1.0/optimade.json index 7270010..4801a86 100644 --- a/openapi/v1.1.0/optimade.json +++ b/openapi/v1.1.0/optimade.json @@ -2,7 +2,7 @@ "openapi": "3.0.2", "info": { "title": "OPTIMADE API", - "description": "The [Open Databases Integration for Materials Design (OPTIMADE) consortium](https://www.optimade.org/) aims to make materials databases interoperational by developing a common REST API.\n\nThis specification is generated using [`optimade-python-tools`](https://github.com/Materials-Consortia/optimade-python-tools/tree/v0.16.0) v0.16.0.", + "description": "The [Open Databases Integration for Materials Design (OPTIMADE) consortium](https://www.optimade.org/) aims to make materials databases interoperational by developing a common REST API.\n\nThis specification is generated using [`optimade-python-tools`](https://github.com/Materials-Consortia/optimade-python-tools/tree/v0.19.1) v0.19.1.", "version": "1.1.0" }, "paths": { @@ -17,7 +17,7 @@ "200": { "description": "Successful Response", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/InfoResponse" } @@ -27,7 +27,7 @@ "400": { "description": "Bad Request", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -37,7 +37,7 @@ "403": { "description": "Forbidden", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -47,7 +47,7 @@ "404": { "description": "Not Found", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -57,7 +57,7 @@ "422": { "description": "Unprocessable Entity", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -67,7 +67,7 @@ "500": { "description": "Internal Server Error", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -77,7 +77,7 @@ "501": { "description": "Not Implemented", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -87,7 +87,7 @@ "553": { "description": "Version Not Supported", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -119,7 +119,7 @@ "200": { "description": "Successful Response", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/EntryInfoResponse" } @@ -129,7 +129,7 @@ "400": { "description": "Bad Request", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -139,7 +139,7 @@ "403": { "description": "Forbidden", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -149,7 +149,7 @@ "404": { "description": "Not Found", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -159,7 +159,7 @@ "422": { "description": "Unprocessable Entity", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -169,7 +169,7 @@ "500": { "description": "Internal Server Error", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -179,7 +179,7 @@ "501": { "description": "Not Implemented", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -189,7 +189,7 @@ "553": { "description": "Version Not Supported", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -301,7 +301,7 @@ "required": false, "schema": { "title": "Page Number", - "minimum": 0.0, + "minimum": 1.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`.", "default": 0 @@ -378,7 +378,7 @@ "200": { "description": "Successful Response", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/LinksResponse" } @@ -388,7 +388,7 @@ "400": { "description": "Bad Request", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -398,7 +398,7 @@ "403": { "description": "Forbidden", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -408,7 +408,7 @@ "404": { "description": "Not Found", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -418,7 +418,7 @@ "422": { "description": "Unprocessable Entity", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -428,7 +428,7 @@ "500": { "description": "Internal Server Error", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -438,7 +438,7 @@ "501": { "description": "Not Implemented", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -448,7 +448,7 @@ "553": { "description": "Version Not Supported", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -560,7 +560,7 @@ "required": false, "schema": { "title": "Page Number", - "minimum": 0.0, + "minimum": 1.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`.", "default": 0 @@ -637,7 +637,7 @@ "200": { "description": "Successful Response", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ReferenceResponseMany" } @@ -647,7 +647,7 @@ "400": { "description": "Bad Request", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -657,7 +657,7 @@ "403": { "description": "Forbidden", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -667,7 +667,7 @@ "404": { "description": "Not Found", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -677,7 +677,7 @@ "422": { "description": "Unprocessable Entity", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -687,7 +687,7 @@ "500": { "description": "Internal Server Error", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -697,7 +697,7 @@ "501": { "description": "Not Implemented", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -707,7 +707,7 @@ "553": { "description": "Version Not Supported", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -802,7 +802,7 @@ "200": { "description": "Successful Response", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ReferenceResponseOne" } @@ -812,7 +812,7 @@ "400": { "description": "Bad Request", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -822,7 +822,7 @@ "403": { "description": "Forbidden", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -832,7 +832,7 @@ "404": { "description": "Not Found", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -842,7 +842,7 @@ "422": { "description": "Unprocessable Entity", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -852,7 +852,7 @@ "500": { "description": "Internal Server Error", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -862,7 +862,7 @@ "501": { "description": "Not Implemented", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -872,7 +872,7 @@ "553": { "description": "Version Not Supported", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -984,7 +984,7 @@ "required": false, "schema": { "title": "Page Number", - "minimum": 0.0, + "minimum": 1.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`.", "default": 0 @@ -1061,7 +1061,7 @@ "200": { "description": "Successful Response", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/StructureResponseMany" } @@ -1071,7 +1071,7 @@ "400": { "description": "Bad Request", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -1081,7 +1081,7 @@ "403": { "description": "Forbidden", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -1091,7 +1091,7 @@ "404": { "description": "Not Found", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -1101,7 +1101,7 @@ "422": { "description": "Unprocessable Entity", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -1111,7 +1111,7 @@ "500": { "description": "Internal Server Error", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -1121,7 +1121,7 @@ "501": { "description": "Not Implemented", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -1131,7 +1131,7 @@ "553": { "description": "Version Not Supported", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -1226,7 +1226,7 @@ "200": { "description": "Successful Response", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/StructureResponseOne" } @@ -1236,7 +1236,7 @@ "400": { "description": "Bad Request", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -1246,7 +1246,7 @@ "403": { "description": "Forbidden", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -1256,7 +1256,7 @@ "404": { "description": "Not Found", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -1266,7 +1266,7 @@ "422": { "description": "Unprocessable Entity", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -1276,7 +1276,7 @@ "500": { "description": "Internal Server Error", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -1286,7 +1286,7 @@ "501": { "description": "Not Implemented", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -1296,7 +1296,7 @@ "553": { "description": "Version Not Supported", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -1358,7 +1358,9 @@ "type": "integer" } }, - "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." + "description": "Index of the sites (0-based) that belong to each group for each assembly.\n\n- **Examples**:\n - `[[1], [2]]`: two groups, one with the second site, one with the third.\n - `[[1,2], [3]]`: one group with the second and third site, one with the fourth.", + "x-optimade-queryable": "optional", + "x-optimade-support": "must" }, "group_probabilities": { "title": "Group Probabilities", @@ -1366,7 +1368,9 @@ "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`." + "description": "Statistical probability of each group. It MUST have the same length as `sites_in_groups`.\nIt SHOULD sum to one.\nSee below for examples of how to specify the probability of the occurrence of a vacancy.\nThe possible reasons for the values not to sum to one are the same as already specified above for the `concentration` of each `species`.", + "x-optimade-queryable": "optional", + "x-optimade-support": "must" } }, "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)." @@ -1398,7 +1402,12 @@ "title": "Version", "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$", "type": "string", - "description": "A string containing the full version number of the API served at that versioned base URL.\nThe version number string MUST NOT be prefixed by, e.g., 'v'.\nExamples: `1.0.0`, `1.0.0-rc.2`." + "description": "A string containing the full version number of the API served at that versioned base URL.\nThe version number string MUST NOT be prefixed by, e.g., 'v'.\nExamples: `1.0.0`, `1.0.0-rc.2`.", + "example": [ + "0.10.1", + "1.0.0-rc.2", + "1.2.3-rc.5+develop" + ] } }, "description": "A JSON object containing information about an available API version" @@ -1417,7 +1426,12 @@ "title": "Api Version", "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$", "type": "string", - "description": "Presently used full version of the OPTIMADE API.\nThe version number string MUST NOT be prefixed by, e.g., \"v\".\nExamples: `1.0.0`, `1.0.0-rc.2`." + "description": "Presently used full version of the OPTIMADE API.\nThe version number string MUST NOT be prefixed by, e.g., \"v\".\nExamples: `1.0.0`, `1.0.0-rc.2`.", + "example": [ + "0.10.1", + "1.0.0-rc.2", + "1.2.3-rc.5+develop" + ] }, "available_api_versions": { "title": "Available Api Versions", @@ -1478,12 +1492,14 @@ "id": { "title": "Id", "pattern": "^/$", - "type": "string" + "type": "string", + "default": "/" }, "type": { "title": "Type", "pattern": "^info$", - "type": "string" + "type": "string", + "default": "info" }, "links": { "title": "Links", @@ -1528,7 +1544,7 @@ "description": { "title": "Description", "type": "string", - "description": "OPTIONAL human-readable description of the relationship" + "description": "OPTIONAL human-readable description of the relationship." } }, "description": "Specific meta field for base relationship resource" @@ -1669,7 +1685,7 @@ "$ref": "#/components/schemas/EntryInfoResource" } ], - "description": "OPTIMADE information for an entry endpoint" + "description": "OPTIMADE information for an entry endpoint." }, "meta": { "title": "Meta", @@ -1756,12 +1772,16 @@ "id": { "title": "Id", "type": "string", - "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`" + "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "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- **Example**: `\"structures\"`", + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "links": { "title": "Links", @@ -1812,13 +1832,17 @@ "immutable_id": { "title": "Immutable Id", "type": "string", - "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)" + "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", + "x-optimade-queryable": "must", + "x-optimade-support": "optional" }, "last_modified": { "title": "Last Modified", "type": "string", "description": "Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n - As part of JSON response format: `\"2007-04-05T14:30:20Z\"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)", - "format": "date-time" + "format": "date-time", + "x-optimade-queryable": "must", + "x-optimade-support": "should" } }, "description": "Contains key-value pairs representing the entry's properties." @@ -1890,9 +1914,9 @@ "title": "About", "anyOf": [ { - "type": "string", - "minLength": 1, "maxLength": 65536, + "minLength": 1, + "type": "string", "format": "uri" }, { @@ -1935,7 +1959,7 @@ "$ref": "#/components/schemas/ResponseMeta" } ], - "description": "A meta object containing non-standard information" + "description": "A meta object containing non-standard information." }, "errors": { "title": "Errors", @@ -2011,9 +2035,9 @@ "title": "Homepage", "anyOf": [ { - "type": "string", - "minLength": 1, "maxLength": 65536, + "minLength": 1, + "type": "string", "format": "uri" }, { @@ -2026,9 +2050,9 @@ "title": "Source Url", "anyOf": [ { - "type": "string", - "minLength": 1, "maxLength": 65536, + "minLength": 1, + "type": "string", "format": "uri" }, { @@ -2050,9 +2074,9 @@ "title": "Issue Tracker", "anyOf": [ { - "type": "string", - "minLength": 1, "maxLength": 65536, + "minLength": 1, + "type": "string", "format": "uri" }, { @@ -2095,7 +2119,7 @@ "$ref": "#/components/schemas/BaseInfoResource" } ], - "description": "The implementations /info data" + "description": "The implementations /info data." }, "meta": { "title": "Meta", @@ -2216,13 +2240,16 @@ "id": { "title": "Id", "type": "string", - "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`" + "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "type": { "title": "Type", "pattern": "^links$", "type": "string", - "description": "These objects are described in detail in the section Links Endpoint" + "description": "These objects are described in detail in the section Links Endpoint", + "default": "links" }, "links": { "title": "Links", @@ -2288,9 +2315,9 @@ "title": "Base Url", "anyOf": [ { - "type": "string", - "minLength": 1, "maxLength": 65536, + "minLength": 1, + "type": "string", "format": "uri" }, { @@ -2303,9 +2330,9 @@ "title": "Homepage", "anyOf": [ { - "type": "string", - "minLength": 1, "maxLength": 65536, + "minLength": 1, + "type": "string", "format": "uri" }, { @@ -2366,7 +2393,7 @@ } } ], - "description": "List of unique OPTIMADE links resource objects" + "description": "List of unique OPTIMADE links resource objects." }, "meta": { "title": "Meta", @@ -2512,17 +2539,23 @@ "name": { "title": "Name", "type": "string", - "description": "Full name of the person, REQUIRED." + "description": "Full name of the person, REQUIRED.", + "x-optimade-queryable": "optional", + "x-optimade-support": "must" }, "firstname": { "title": "Firstname", "type": "string", - "description": "First name of the person." + "description": "First name of the person.", + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "lastname": { "title": "Lastname", "type": "string", - "description": "Last name of the person." + "description": "Last name of the person.", + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" } }, "description": "A person, i.e., an author, editor or other." @@ -2556,9 +2589,9 @@ "title": "Homepage", "anyOf": [ { - "type": "string", - "minLength": 1, "maxLength": 65536, + "minLength": 1, + "type": "string", "format": "uri" }, { @@ -2609,7 +2642,7 @@ "description": "a meta object that contains non-standard meta-information about the relationship." } }, - "description": "Similar to normal JSON API relationship, but with addition of OPTIONAL meta field for a resource" + "description": "Similar to normal JSON API relationship, but with addition of OPTIONAL meta field for a resource." }, "ReferenceResource": { "title": "ReferenceResource", @@ -2623,13 +2656,18 @@ "id": { "title": "Id", "type": "string", - "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`" + "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "type": { "title": "Type", "pattern": "^references$", "type": "string", - "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\"`" + "description": "The name of the type of an entry.\n- **Type**: string.\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - MUST be an existing entry type.\n - The entry of type and ID MUST be returned in response to a request for `//` under the versioned base URL.\n- **Example**: `\"structures\"`", + "default": "references", + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "links": { "title": "Links", @@ -2674,13 +2712,17 @@ "immutable_id": { "title": "Immutable Id", "type": "string", - "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)" + "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", + "x-optimade-queryable": "must", + "x-optimade-support": "optional" }, "last_modified": { "title": "Last Modified", "type": "string", "description": "Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n - As part of JSON response format: `\"2007-04-05T14:30:20Z\"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)", - "format": "date-time" + "format": "date-time", + "x-optimade-queryable": "must", + "x-optimade-support": "should" }, "authors": { "title": "Authors", @@ -2688,7 +2730,9 @@ "items": { "$ref": "#/components/schemas/Person" }, - "description": "List of person objects containing the authors of the reference." + "description": "List of person objects containing the authors of the reference.", + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "editors": { "title": "Editors", @@ -2696,12 +2740,16 @@ "items": { "$ref": "#/components/schemas/Person" }, - "description": "List of person objects containing the editors of the reference." + "description": "List of person objects containing the editors of the reference.", + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "doi": { "title": "Doi", "type": "string", - "description": "The digital object identifier of the reference." + "description": "The digital object identifier of the reference.", + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "url": { "title": "Url", @@ -2709,117 +2757,163 @@ "minLength": 1, "type": "string", "description": "The URL of the reference.", - "format": "uri" + "format": "uri", + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "address": { "title": "Address", "type": "string", - "description": "Meaning of property matches the BiBTeX specification." + "description": "Meaning of property matches the BiBTeX specification.", + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "annote": { "title": "Annote", "type": "string", - "description": "Meaning of property matches the BiBTeX specification." + "description": "Meaning of property matches the BiBTeX specification.", + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "booktitle": { "title": "Booktitle", "type": "string", - "description": "Meaning of property matches the BiBTeX specification." + "description": "Meaning of property matches the BiBTeX specification.", + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "chapter": { "title": "Chapter", "type": "string", - "description": "Meaning of property matches the BiBTeX specification." + "description": "Meaning of property matches the BiBTeX specification.", + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "crossref": { "title": "Crossref", "type": "string", - "description": "Meaning of property matches the BiBTeX specification." + "description": "Meaning of property matches the BiBTeX specification.", + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "edition": { "title": "Edition", "type": "string", - "description": "Meaning of property matches the BiBTeX specification." + "description": "Meaning of property matches the BiBTeX specification.", + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "howpublished": { "title": "Howpublished", "type": "string", - "description": "Meaning of property matches the BiBTeX specification." + "description": "Meaning of property matches the BiBTeX specification.", + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "institution": { "title": "Institution", "type": "string", - "description": "Meaning of property matches the BiBTeX specification." + "description": "Meaning of property matches the BiBTeX specification.", + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "journal": { "title": "Journal", "type": "string", - "description": "Meaning of property matches the BiBTeX specification." + "description": "Meaning of property matches the BiBTeX specification.", + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "key": { "title": "Key", "type": "string", - "description": "Meaning of property matches the BiBTeX specification." + "description": "Meaning of property matches the BiBTeX specification.", + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "month": { "title": "Month", "type": "string", - "description": "Meaning of property matches the BiBTeX specification." + "description": "Meaning of property matches the BiBTeX specification.", + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "note": { "title": "Note", "type": "string", - "description": "Meaning of property matches the BiBTeX specification." + "description": "Meaning of property matches the BiBTeX specification.", + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "number": { "title": "Number", "type": "string", - "description": "Meaning of property matches the BiBTeX specification." + "description": "Meaning of property matches the BiBTeX specification.", + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "organization": { "title": "Organization", "type": "string", - "description": "Meaning of property matches the BiBTeX specification." + "description": "Meaning of property matches the BiBTeX specification.", + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "pages": { "title": "Pages", "type": "string", - "description": "Meaning of property matches the BiBTeX specification." + "description": "Meaning of property matches the BiBTeX specification.", + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "publisher": { "title": "Publisher", "type": "string", - "description": "Meaning of property matches the BiBTeX specification." + "description": "Meaning of property matches the BiBTeX specification.", + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "school": { "title": "School", "type": "string", - "description": "Meaning of property matches the BiBTeX specification." + "description": "Meaning of property matches the BiBTeX specification.", + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "series": { "title": "Series", "type": "string", - "description": "Meaning of property matches the BiBTeX specification." + "description": "Meaning of property matches the BiBTeX specification.", + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "title": { "title": "Title", "type": "string", - "description": "Meaning of property matches the BiBTeX specification." + "description": "Meaning of property matches the BiBTeX specification.", + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "bib_type": { "title": "Bib Type", "type": "string", - "description": "Type of the reference, corresponding to the **type** property in the BiBTeX specification." + "description": "Type of the reference, corresponding to the **type** property in the BiBTeX specification.", + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "volume": { "title": "Volume", "type": "string", - "description": "Meaning of property matches the BiBTeX specification." + "description": "Meaning of property matches the BiBTeX specification.", + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "year": { "title": "Year", "type": "string", - "description": "Meaning of property matches the BiBTeX specification." + "description": "Meaning of property matches the BiBTeX specification.", + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" } }, "description": "Model that stores the attributes of a reference.\n\nMany properties match the meaning described in the\n[BibTeX specification](http://bibtexml.sourceforge.net/btxdoc.pdf)." @@ -2849,7 +2943,7 @@ } } ], - "description": "List of unique OPTIMADE references entry resource objects" + "description": "List of unique OPTIMADE references entry resource objects." }, "meta": { "title": "Meta", @@ -2926,7 +3020,7 @@ "type": "object" } ], - "description": "A single references entry resource" + "description": "A single references entry resource." }, "meta": { "title": "Meta", @@ -2993,9 +3087,9 @@ "title": "Self", "anyOf": [ { - "type": "string", - "minLength": 1, "maxLength": 65536, + "minLength": 1, + "type": "string", "format": "uri" }, { @@ -3008,9 +3102,9 @@ "title": "Related", "anyOf": [ { - "type": "string", - "minLength": 1, "maxLength": 65536, + "minLength": 1, + "type": "string", "format": "uri" }, { @@ -3093,9 +3187,9 @@ "title": "Self", "anyOf": [ { - "type": "string", - "minLength": 1, "maxLength": 65536, + "minLength": 1, + "type": "string", "format": "uri" }, { @@ -3129,7 +3223,12 @@ "title": "Api Version", "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$", "type": "string", - "description": "Presently used full version of the OPTIMADE API.\nThe version number string MUST NOT be prefixed by, e.g., \"v\".\nExamples: `1.0.0`, `1.0.0-rc.2`." + "description": "Presently used full version of the OPTIMADE API.\nThe version number string MUST NOT be prefixed by, e.g., \"v\".\nExamples: `1.0.0`, `1.0.0-rc.2`.", + "example": [ + "0.10.1", + "1.0.0-rc.2", + "1.2.3-rc.5+develop" + ] }, "more_data_available": { "title": "More Data Available", @@ -3140,9 +3239,9 @@ "title": "Schema", "anyOf": [ { - "type": "string", - "minLength": 1, "maxLength": 65536, + "minLength": 1, + "type": "string", "format": "uri" }, { @@ -3235,7 +3334,9 @@ "name": { "title": "Name", "type": "string", - "description": "Gives the name of the species; the **name** value MUST be unique in the `species` list." + "description": "Gives the name of the species; the **name** value MUST be unique in the `species` list.", + "x-optimade-queryable": "optional", + "x-optimade-support": "must" }, "chemical_symbols": { "title": "Chemical Symbols", @@ -3243,7 +3344,9 @@ "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`." + "description": "MUST be a list of strings of all chemical elements composing this species. Each item of the list MUST be one of the following:\n\n- a valid chemical-element symbol, or\n- the special value `\"X\"` to represent a non-chemical element, or\n- the special value `\"vacancy\"` to represent that this site has a non-zero probability of having a vacancy (the respective probability is indicated in the `concentration` list, see below).\n\nIf any one entry in the `species` list has a `chemical_symbols` list that is longer than 1 element, the correct flag MUST be set in the list `structure_features`.", + "x-optimade-queryable": "optional", + "x-optimade-support": "must" }, "concentration": { "title": "Concentration", @@ -3251,7 +3354,9 @@ "items": { "type": "number" }, - "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)." + "description": "MUST be a list of floats, with same length as `chemical_symbols`. The numbers represent the relative concentration of the corresponding chemical symbol in this species. The numbers SHOULD sum to one. Cases in which the numbers do not sum to one typically fall only in the following two categories:\n\n- Numerical errors when representing float numbers in fixed precision, e.g. for two chemical symbols with concentrations `1/3` and `2/3`, the concentration might look something like `[0.33333333333, 0.66666666666]`. If the client is aware that the sum is not one because of numerical precision, it can renormalize the values so that the sum is exactly one.\n- Experimental errors in the data present in the database. In this case, it is the responsibility of the client to decide how to process the data.\n\nNote that concentrations are uncorrelated between different site (even of the same species).", + "x-optimade-queryable": "optional", + "x-optimade-support": "must" }, "mass": { "title": "Mass", @@ -3259,12 +3364,17 @@ "items": { "type": "number" }, - "description": "If present MUST be a list of floats expressed in a.m.u.\nElements denoting vacancies MUST have masses equal to 0." + "description": "If present MUST be a list of floats expressed in a.m.u.\nElements denoting vacancies MUST have masses equal to 0.", + "x-optimade-queryable": "optional", + "x-optimade-unit": "a.m.u.", + "x-optimade-support": "optional" }, "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." + "description": "Can be any valid Unicode string, and SHOULD contain (if specified) the name of the species that is used internally in the source database.\n\nNote: With regards to \"source database\", we refer to the immediate source being queried via the OPTIMADE API implementation.", + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "attached": { "title": "Attached", @@ -3272,7 +3382,9 @@ "items": { "type": "string" }, - "description": "If provided MUST be a list of length 1 or more of strings of chemical symbols for the elements attached to this site, or \"X\" for a non-chemical element." + "description": "If provided MUST be a list of length 1 or more of strings of chemical symbols for the elements attached to this site, or \"X\" for a non-chemical element.", + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "nattached": { "title": "Nattached", @@ -3280,7 +3392,9 @@ "items": { "type": "integer" }, - "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": "If provided MUST be a list of length 1 or more of integers indicating the number of attached atoms of the kind specified in the value of the :field:`attached` key.", + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" } }, "description": "A list describing the species of the sites of this structure.\n\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\": [0.0, 137.327, 40.078]} ]`: any site with this species is occupied by a Ba atom with 45 % probability, a Ca atom with 50 % probability, and by a vacancy with 5 % probability. The mass of this site is (on average) 88.5 a.m.u.\n - `[ {\"name\": \"C12\", \"chemical_symbols\": [\"C\"], \"concentration\": [1.0], \"mass\": [12.0]} ]`: any site with this species is occupied by a carbon isotope with mass 12.\n - `[ {\"name\": \"C13\", \"chemical_symbols\": [\"C\"], \"concentration\": [1.0], \"mass\": [13.0]} ]`: any site with this species is occupied by a carbon isotope with mass 13.\n - `[ {\"name\": \"CH3\", \"chemical_symbols\": [\"C\"], \"concentration\": [1.0], \"attached\": [\"H\"], \"nattached\": [3]} ]`: any site with this species is occupied by a methyl group, -CH3, which is represented without specifying precise positions of the hydrogen atoms." @@ -3334,7 +3448,7 @@ "description": "a meta object that contains non-standard meta-information about the relationship." } }, - "description": "Similar to normal JSON API relationship, but with addition of OPTIONAL meta field for a resource" + "description": "Similar to normal JSON API relationship, but with addition of OPTIONAL meta field for a resource." }, "StructureResource": { "title": "StructureResource", @@ -3348,13 +3462,18 @@ "id": { "title": "Id", "type": "string", - "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`" + "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "type": { "title": "Type", "pattern": "^structures$", "type": "string", - "description": "The name of the type of an entry.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - MUST be an existing entry type.\n - The entry of type `` and ID `` MUST be returned in response to a request for `//` under the versioned base URL.\n\n- **Examples**:\n - `\"structures\"`" + "description": "The name of the type of an entry.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - MUST be an existing entry type.\n - The entry of type `` and ID `` MUST be returned in response to a request for `//` under the versioned base URL.\n\n- **Examples**:\n - `\"structures\"`", + "default": "structures", + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "links": { "title": "Links", @@ -3413,14 +3532,18 @@ "immutable_id": { "title": "Immutable Id", "type": "string", - "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)" + "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", + "x-optimade-queryable": "must", + "x-optimade-support": "optional" }, "last_modified": { "title": "Last Modified", "type": "string", "description": "Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n - As part of JSON response format: `\"2007-04-05T14:30:20Z\"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)", "format": "date-time", - "nullable": true + "nullable": true, + "x-optimade-queryable": "must", + "x-optimade-support": "should" }, "elements": { "title": "Elements", @@ -3428,14 +3551,18 @@ "items": { "type": "string" }, - "description": "Symbols of the different elements present in the structure.\n\n- **Type**: list of strings.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - The strings are the chemical symbols, i.e., either a single uppercase letter or an uppercase letter followed by a number of lowercase letters.\n - The order MUST be alphabetical.\n - MUST refer to the same elements in the same order, and therefore be of the same length, as `elements_ratios`, if the latter is provided.\n - Note: This property SHOULD NOT contain the string \"X\" to indicate non-chemical elements or \"vacancy\" to indicate vacancies (in contrast to the field `chemical_symbols` for the `species` property).\n\n- **Examples**:\n - `[\"Si\"]`\n - `[\"Al\",\"O\",\"Si\"]`\n\n- **Query examples**:\n - A filter that matches all records of structures that contain Si, Al **and** O, and possibly other elements: `elements HAS ALL \"Si\", \"Al\", \"O\"`.\n - To match structures with exactly these three elements, use `elements HAS ALL \"Si\", \"Al\", \"O\" AND elements LENGTH 3`.\n - Note: length queries on this property can be equivalently formulated by filtering on the `nelements`_ property directly.", - "nullable": true + "description": "The chemical symbols of the different elements present in the structure.\n\n- **Type**: list of strings.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - The strings are the chemical symbols, i.e., either a single uppercase letter or an uppercase letter followed by a number of lowercase letters.\n - The order MUST be alphabetical.\n - MUST refer to the same elements in the same order, and therefore be of the same length, as `elements_ratios`, if the latter is provided.\n - Note: This property SHOULD NOT contain the string \"X\" to indicate non-chemical elements or \"vacancy\" to indicate vacancies (in contrast to the field `chemical_symbols` for the `species` property).\n\n- **Examples**:\n - `[\"Si\"]`\n - `[\"Al\",\"O\",\"Si\"]`\n\n- **Query examples**:\n - A filter that matches all records of structures that contain Si, Al **and** O, and possibly other elements: `elements HAS ALL \"Si\", \"Al\", \"O\"`.\n - To match structures with exactly these three elements, use `elements HAS ALL \"Si\", \"Al\", \"O\" AND elements LENGTH 3`.\n - Note: length queries on this property can be equivalently formulated by filtering on the `nelements`_ property directly.", + "nullable": true, + "x-optimade-queryable": "must", + "x-optimade-support": "should" }, "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 - MUST be equal to the lengths of the list properties `elements` and `elements_ratios`, if they are provided.\n\n- **Examples**:\n - `3`\n\n- **Querying**:\n - Note: queries on this property can equivalently be formulated using `elements LENGTH`.\n - A filter that matches structures that have exactly 4 elements: `nelements=4`.\n - A filter that matches structures that have between 2 and 7 elements: `nelements>=2 AND nelements<=7`.", - "nullable": true + "nullable": true, + "x-optimade-queryable": "must", + "x-optimade-support": "should" }, "elements_ratios": { "title": "Elements Ratios", @@ -3444,33 +3571,43 @@ "type": "number" }, "description": "Relative proportions of different elements in the structure.\n\n- **Type**: list of floats\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - Composed by the proportions of elements in the structure as a list of floating point numbers.\n - The sum of the numbers MUST be 1.0 (within floating point accuracy)\n - MUST refer to the same elements in the same order, and therefore be of the same length, as `elements`, if the latter is provided.\n\n- **Examples**:\n - `[1.0]`\n - `[0.3333333333333333, 0.2222222222222222, 0.4444444444444444]`\n\n- **Query examples**:\n - Note: Useful filters can be formulated using the set operator syntax for correlated values.\n However, since the values are floating point values, the use of equality comparisons is generally inadvisable.\n - OPTIONAL: a filter that matches structures where approximately 1/3 of the atoms in the structure are the element Al is: `elements:elements_ratios HAS ALL \"Al\":>0.3333, \"Al\":<0.3334`.", - "nullable": true + "nullable": true, + "x-optimade-queryable": "must", + "x-optimade-support": "should" }, "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\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - The chemical formula is given as a string consisting of properly capitalized element symbols followed by integers or decimal numbers, balanced parentheses, square, and curly brackets `(`,`)`, `[`,`]`, `{`, `}`, commas, the `+`, `-`, `:` and `=` symbols. The parentheses are allowed to be followed by a number. Spaces are allowed anywhere except within chemical symbols. The order of elements and any groupings indicated by parentheses or brackets are chosen freely by the API implementation.\n - The string SHOULD be arithmetically consistent with the element ratios in the `chemical_formula_reduced` property.\n - It is RECOMMENDED, but not mandatory, that symbols, parentheses and brackets, if used, are used with the meanings prescribed by [IUPAC's Nomenclature of Organic Chemistry](https://www.qmul.ac.uk/sbcs/iupac/bibliog/blue.html).\n\n- **Examples**:\n - `\"(H2O)2 Na\"`\n - `\"NaCl\"`\n - `\"CaCO3\"`\n - `\"CCaO3\"`\n - `\"(CH3)3N+ - [CH2]2-OH = Me3N+ - CH2 - CH2OH\"`\n\n- **Query examples**:\n - Note: the free-form nature of this property is likely to make queries on it across different databases inconsistent.\n - A filter that matches an exactly given formula: `chemical_formula_descriptive=\"(H2O)2 Na\"`.\n - A filter that does a partial match: `chemical_formula_descriptive CONTAINS \"H2O\"`.", - "nullable": true + "nullable": true, + "x-optimade-queryable": "must", + "x-optimade-support": "should" }, "chemical_formula_reduced": { "title": "Chemical Formula Reduced", - "pattern": "^([A-Z][a-z]?\\d*)*$", + "pattern": "^([A-Z][a-z]?([2-9]|[1-9]\\d+)?)+$", "type": "string", "description": "The reduced chemical formula for a structure as a string with element symbols and integer chemical proportion numbers.\nThe proportion number MUST be omitted if it is 1.\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property.\n However, support for filters using partial string matching with this property is OPTIONAL (i.e., BEGINS WITH, ENDS WITH, and CONTAINS).\n Intricate queries on formula components are instead suggested to be formulated using set-type filter operators on the multi valued `elements` and `elements_ratios` properties.\n - Element symbols MUST have proper capitalization (e.g., `\"Si\"`, not `\"SI\"` for \"silicon\").\n - Elements MUST be placed in alphabetical order, followed by their integer chemical proportion number.\n - For structures with no partial occupation, the chemical proportion numbers are the smallest integers for which the chemical proportion is exactly correct.\n - For structures with partial occupation, the chemical proportion numbers are integers that within reasonable approximation indicate the correct chemical proportions. The precise details of how to perform the rounding is chosen by the API implementation.\n - No spaces or separators are allowed.\n\n- **Examples**:\n - `\"H2NaO\"`\n - `\"ClNa\"`\n - `\"CCaO3\"`\n\n- **Query examples**:\n - A filter that matches an exactly given formula is `chemical_formula_reduced=\"H2NaO\"`.", - "nullable": true + "nullable": true, + "x-optimade-queryable": "must", + "x-optimade-support": "should" }, "chemical_formula_hill": { "title": "Chemical Formula Hill", - "pattern": "^([A-Z][a-z]?\\d*)*$", + "pattern": "^([A-Z][a-z]?([2-9]|[1-9]\\d+)?)+$", "type": "string", - "description": "The chemical formula for a structure in [Hill form](https://dx.doi.org/10.1021/ja02046a005) with element symbols followed by integer chemical proportion numbers. The proportion number MUST be omitted if it is 1.\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, only a subset of the filter features MAY be supported.\n - The overall scale factor of the chemical proportions is chosen such that the resulting values are integers that indicate the most chemically relevant unit of which the system is composed.\n For example, if the structure is a repeating unit cell with four hydrogens and four oxygens that represents two hydroperoxide molecules, `chemical_formula_hill` is `\"H2O2\"` (i.e., not `\"HO\"`, nor `\"H4O4\"`).\n - If the chemical insight needed to ascribe a Hill formula to the system is not present, the property MUST be handled as unset.\n - Element symbols MUST have proper capitalization (e.g., `\"Si\"`, not `\"SI\"` for \"silicon\").\n - Elements MUST be placed in [Hill order](https://dx.doi.org/10.1021/ja02046a005), followed by their integer chemical proportion number.\n Hill order means: if carbon is present, it is placed first, and if also present, hydrogen is placed second.\n After that, all other elements are ordered alphabetically.\n If carbon is not present, all elements are ordered alphabetically.\n - If the system has sites with partial occupation and the total occupations of each element do not all sum up to integers, then the Hill formula SHOULD be handled as unset.\n - No spaces or separators are allowed.\n\n- **Examples**:\n - `\"H2O2\"`\n\n- **Query examples**:\n - A filter that matches an exactly given formula is `chemical_formula_hill=\"H2O2\"`." + "description": "The chemical formula for a structure in [Hill form](https://dx.doi.org/10.1021/ja02046a005) with element symbols followed by integer chemical proportion numbers. The proportion number MUST be omitted if it is 1.\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, only a subset of the filter features MAY be supported.\n - The overall scale factor of the chemical proportions is chosen such that the resulting values are integers that indicate the most chemically relevant unit of which the system is composed.\n For example, if the structure is a repeating unit cell with four hydrogens and four oxygens that represents two hydroperoxide molecules, `chemical_formula_hill` is `\"H2O2\"` (i.e., not `\"HO\"`, nor `\"H4O4\"`).\n - If the chemical insight needed to ascribe a Hill formula to the system is not present, the property MUST be handled as unset.\n - Element symbols MUST have proper capitalization (e.g., `\"Si\"`, not `\"SI\"` for \"silicon\").\n - Elements MUST be placed in [Hill order](https://dx.doi.org/10.1021/ja02046a005), followed by their integer chemical proportion number.\n Hill order means: if carbon is present, it is placed first, and if also present, hydrogen is placed second.\n After that, all other elements are ordered alphabetically.\n If carbon is not present, all elements are ordered alphabetically.\n - If the system has sites with partial occupation and the total occupations of each element do not all sum up to integers, then the Hill formula SHOULD be handled as unset.\n - No spaces or separators are allowed.\n\n- **Examples**:\n - `\"H2O2\"`\n\n- **Query examples**:\n - A filter that matches an exactly given formula is `chemical_formula_hill=\"H2O2\"`.", + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "chemical_formula_anonymous": { "title": "Chemical Formula Anonymous", - "pattern": "^([A-Z][a-z]?\\d*)*$", + "pattern": "^([A-Z][a-z]?([2-9]|[1-9]\\d+)?)+$", "type": "string", "description": "The anonymous formula is the `chemical_formula_reduced`, but where the elements are instead first ordered by their chemical proportion number, and then, in order left to right, replaced by anonymous symbols A, B, C, ..., Z, Aa, Ba, ..., Za, Ab, Bb, ... and so on.\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property.\n However, support for filters using partial string matching with this property is OPTIONAL (i.e., BEGINS WITH, ENDS WITH, and CONTAINS).\n\n- **Examples**:\n - `\"A2B\"`\n - `\"A42B42C16D12E10F9G5\"`\n\n- **Querying**:\n - A filter that matches an exactly given formula is `chemical_formula_anonymous=\"A2B\"`.", - "nullable": true + "nullable": true, + "x-optimade-queryable": "must", + "x-optimade-support": "should" }, "dimension_types": { "title": "Dimension Types", @@ -3481,13 +3618,17 @@ "$ref": "#/components/schemas/Periodicity" }, "description": "List of three integers.\nFor each of the three directions indicated by the three lattice vectors (see property `lattice_vectors`), this list indicates if the direction is periodic (value `1`) or non-periodic (value `0`).\nNote: the elements in this list each refer to the direction of the corresponding entry in `lattice_vectors` and *not* the Cartesian x, y, z directions.\n\n- **Type**: list of integers.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - MUST be a list of length 3.\n - Each integer element MUST assume only the value 0 or 1.\n\n- **Examples**:\n - For a molecule: `[0, 0, 0]`\n - For a wire along the direction specified by the third lattice vector: `[0, 0, 1]`\n - For a 2D surface/slab, periodic on the plane defined by the first and third lattice vectors: `[1, 0, 1]`\n - For a bulk 3D system: `[1, 1, 1]`", - "nullable": true + "nullable": true, + "x-optimade-queryable": "optional", + "x-optimade-support": "should" }, "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 `dimension_types`.\n\n- **Type**: integer\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - The integer value MUST be between 0 and 3 inclusive and MUST be equal to the sum of the items in the `dimension_types` property.\n - This property only reflects the treatment of the lattice vectors provided for the structure, and not any physical interpretation of the dimensionality of its contents.\n\n- **Examples**:\n - `2` should be indicated in cases where `dimension_types` is any of `[1, 1, 0]`, `[1, 0, 1]`, `[0, 1, 1]`.\n\n- **Query examples**:\n - Match only structures with exactly 3 periodic dimensions: `nperiodic_dimensions=3`\n - Match all structures with 2 or fewer periodic dimensions: `nperiodic_dimensions<=2`", - "nullable": true + "nullable": true, + "x-optimade-queryable": "must", + "x-optimade-support": "should" }, "lattice_vectors": { "title": "Lattice Vectors", @@ -3495,35 +3636,43 @@ "minItems": 3, "type": "array", "items": { + "maxItems": 3, + "minItems": 3, "type": "array", "items": { "type": "number" - }, - "minItems": 3, - "maxItems": 3 + } }, "description": "The three lattice vectors in Cartesian coordinates, in \u00e5ngstr\u00f6m (\u00c5).\n\n- **Type**: list of list of floats or unknown values.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - MUST be a list of three vectors *a*, *b*, and *c*, where each of the vectors MUST BE a list of the vector's coordinates along the x, y, and z Cartesian coordinates.\n (Therefore, the first index runs over the three lattice vectors and the second index runs over the x, y, z Cartesian coordinates).\n - For databases that do not define an absolute Cartesian system (e.g., only defining the length and angles between vectors), the first lattice vector SHOULD be set along *x* and the second on the *xy*-plane.\n - MUST always contain three vectors of three coordinates each, independently of the elements of property `dimension_types`.\n The vectors SHOULD by convention be chosen so the determinant of the `lattice_vectors` matrix is different from zero.\n The vectors in the non-periodic directions have no significance beyond fulfilling these requirements.\n - The coordinates of the lattice vectors of non-periodic dimensions (i.e., those dimensions for which `dimension_types` is `0`) MAY be given as a list of all `null` values.\n If a lattice vector contains the value `null`, all coordinates of that lattice vector MUST be `null`.\n\n- **Examples**:\n - `[[4.0,0.0,0.0],[0.0,4.0,0.0],[0.0,1.0,4.0]]` represents a cell, where the first vector is `(4, 0, 0)`, i.e., a vector aligned along the `x` axis of length 4 \u00c5; the second vector is `(0, 4, 0)`; and the third vector is `(0, 1, 4)`.", - "nullable": true + "nullable": true, + "x-optimade-queryable": "optional", + "x-optimade-unit": "\u00c5", + "x-optimade-support": "should" }, "cartesian_site_positions": { "title": "Cartesian Site Positions", "type": "array", "items": { + "maxItems": 3, + "minItems": 3, "type": "array", "items": { "type": "number" - }, - "minItems": 3, - "maxItems": 3 + } }, "description": "Cartesian positions of each site in the structure.\nA site is usually used to describe positions of atoms; what atoms can be encountered at a given site is conveyed by the `species_at_sites` property, and the species themselves are described in the `species` property.\n\n- **Type**: list of list of floats\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - It MUST be a list of length equal to the number of sites in the structure, where every element is a list of the three Cartesian coordinates of a site expressed as float values in the unit angstrom (\u00c5).\n - An entry MAY have multiple sites at the same Cartesian position (for a relevant use of this, see e.g., the property `assemblies`).\n\n- **Examples**:\n - `[[0,0,0],[0,0,2]]` indicates a structure with two sites, one sitting at the origin and one along the (positive) *z*-axis, 2 \u00c5 away from the origin.", - "nullable": true + "nullable": true, + "x-optimade-queryable": "optional", + "x-optimade-unit": "\u00c5", + "x-optimade-support": "should" }, "nsites": { "title": "Nsites", "type": "integer", "description": "An integer specifying the length of the `cartesian_site_positions` property.\n\n- **Type**: integer\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `42`\n\n- **Query examples**:\n - Match only structures with exactly 4 sites: `nsites=4`\n - Match structures that have between 2 and 7 sites: `nsites>=2 AND nsites<=7`", - "nullable": true + "nullable": true, + "x-optimade-queryable": "must", + "x-optimade-support": "should" }, "species": { "title": "Species", @@ -3532,7 +3681,9 @@ "$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 - `attached`: list of strings (REQUIRED)\n - `nattached`: list of integers (OPTIONAL)\n - `mass`: list of floats (OPTIONAL)\n - `original_name`: string (OPTIONAL).\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - Each list member MUST be a dictionary with the following keys:\n - **name**: REQUIRED; gives the name of the species; the **name** value MUST be unique in the `species` list;\n - **chemical_symbols**: REQUIRED; MUST be a list of strings of all chemical elements composing this species.\n Each item of the list MUST be one of the following:\n - a valid chemical-element symbol, or\n - the special value `\"X\"` to represent a non-chemical element, or\n - the special value `\"vacancy\"` to represent that this site has a non-zero probability of having a vacancy (the respective probability is indicated in the `concentration` list, see below).\n\n If any one entry in the `species` list has a `chemical_symbols` list that is longer than 1 element, the correct flag MUST be set in the list `structure_features`.\n\n - **concentration**: REQUIRED; MUST be a list of floats, with same length as `chemical_symbols`.\n The numbers represent the relative concentration of the corresponding chemical symbol in this species.\n The numbers SHOULD sum to one. Cases in which the numbers do not sum to one typically fall only in the following two categories:\n\n - Numerical errors when representing float numbers in fixed precision, e.g. for two chemical symbols with concentrations `1/3` and `2/3`, the concentration might look something like `[0.33333333333, 0.66666666666]`. If the client is aware that the sum is not one because of numerical precision, it can renormalize the values so that the sum is exactly one.\n - Experimental errors in the data present in the database. In this case, it is the responsibility of the client to decide how to process the data.\n\n Note that concentrations are uncorrelated between different sites (even of the same species).\n\n - **attached**: OPTIONAL; if provided MUST be a list of length 1 or more of strings of chemical symbols for the elements attached to this site, or \"X\" for a non-chemical element.\n\n - **nattached**: OPTIONAL; if provided MUST be a list of length 1 or more of integers indicating the number of attached atoms of the kind specified in the value of the `attached` key.\n\n The implementation MUST include either both or none of the `attached` and `nattached` keys, and if they are provided, they MUST be of the same length.\n Furthermore, if they are provided, the `structure_features` property MUST include the string `site_attachments`.\n\n - **mass**: OPTIONAL. If present MUST be a list of floats, with the same length as `chemical_symbols`, providing element masses expressed in a.m.u.\n Elements denoting vacancies MUST have masses equal to 0.\n\n - **original_name**: OPTIONAL. Can be any valid Unicode string, and SHOULD contain (if specified) the name of the species that is used internally in the source database.\n\n Note: With regards to \"source database\", we refer to the immediate source being queried via the OPTIMADE API implementation.\n\n The main use of this field is for source databases that use species names, containing characters that are not allowed (see description of the list property `species_at_sites`).\n\n - For systems that have only species formed by a single chemical symbol, and that have at most one species per chemical symbol, SHOULD use the chemical symbol as species name (e.g., `\"Ti\"` for titanium, `\"O\"` for oxygen, etc.)\n However, note that this is OPTIONAL, and client implementations MUST NOT assume that the key corresponds to a chemical symbol, nor assume that if the species name is a valid chemical symbol, that it represents a species with that chemical symbol.\n This means that a species `{\"name\": \"C\", \"chemical_symbols\": [\"Ti\"], \"concentration\": [1.0]}` is valid and represents a titanium species (and *not* a carbon species).\n - It is NOT RECOMMENDED that a structure includes species that do not have at least one corresponding site.\n\n- **Examples**:\n - `[ {\"name\": \"Ti\", \"chemical_symbols\": [\"Ti\"], \"concentration\": [1.0]} ]`: any site with this species is occupied by a Ti atom.\n - `[ {\"name\": \"Ti\", \"chemical_symbols\": [\"Ti\", \"vacancy\"], \"concentration\": [0.9, 0.1]} ]`: any site with this species is occupied by a Ti atom with 90 % probability, and has a vacancy with 10 % probability.\n - `[ {\"name\": \"BaCa\", \"chemical_symbols\": [\"vacancy\", \"Ba\", \"Ca\"], \"concentration\": [0.05, 0.45, 0.5], \"mass\": [0.0, 137.327, 40.078]} ]`: any site with this species is occupied by a Ba atom with 45 % probability, a Ca atom with 50 % probability, and by a vacancy with 5 % probability. The mass of this site is (on average) 88.5 a.m.u.\n - `[ {\"name\": \"C12\", \"chemical_symbols\": [\"C\"], \"concentration\": [1.0], \"mass\": [12.0]} ]`: any site with this species is occupied by a carbon isotope with mass 12.\n - `[ {\"name\": \"C13\", \"chemical_symbols\": [\"C\"], \"concentration\": [1.0], \"mass\": [13.0]} ]`: any site with this species is occupied by a carbon isotope with mass 13.\n - `[ {\"name\": \"CH3\", \"chemical_symbols\": [\"C\"], \"concentration\": [1.0], \"attached\": [\"H\"], \"nattached\": [3]} ]`: any site with this species is occupied by a methyl group, -CH3, which is represented without specifying precise positions of the hydrogen atoms.", - "nullable": true + "nullable": true, + "x-optimade-queryable": "optional", + "x-optimade-support": "should" }, "species_at_sites": { "title": "Species At Sites", @@ -3541,7 +3692,9 @@ "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`).\nThe properties of the species are found in the property `species`.\n\n- **Type**: list of strings.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - MUST have length equal to the number of sites in the structure (first dimension of the list property `cartesian_site_positions`).\n - Each species name mentioned in the `species_at_sites` list MUST be described in the list property `species` (i.e. for each value in the `species_at_sites` list there MUST exist exactly one dictionary in the `species` list with the `name` attribute equal to the corresponding `species_at_sites` value).\n - Each site MUST be associated only to a single species.\n **Note**: However, species can represent mixtures of atoms, and multiple species MAY be defined for the same chemical element.\n This latter case is useful when different atoms of the same type need to be grouped or distinguished, for instance in simulation codes to assign different initial spin states.\n\n- **Examples**:\n - `[\"Ti\",\"O2\"]` indicates that the first site is hosting a species labeled `\"Ti\"` and the second a species labeled `\"O2\"`.\n - `[\"Ac\", \"Ac\", \"Ag\", \"Ir\"]` indicating the first two sites contains the `\"Ac\"` species, while the third and fourth sites contain the `\"Ag\"` and `\"Ir\"` species, respectively.", - "nullable": true + "nullable": true, + "x-optimade-queryable": "optional", + "x-optimade-support": "should" }, "assemblies": { "title": "Assemblies", @@ -3549,7 +3702,9 @@ "items": { "$ref": "#/components/schemas/Assembly" }, - "description": "A description of groups of sites that are statistically correlated.\n\n- **Type**: list of dictionary with keys:\n - `sites_in_groups`: list of list of integers (REQUIRED)\n - `group_probabilities`: list of floats (REQUIRED)\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - The property SHOULD be `null` for entries that have no partial occupancies.\n - If present, the correct flag MUST be set in the list `structure_features`.\n - Client implementations MUST check its presence (as its presence changes the interpretation of the structure).\n - If present, it MUST be a list of dictionaries, each of which represents an assembly and MUST have the following two keys:\n - **sites_in_groups**: Index of the sites (0-based) that belong to each group for each assembly.\n\n Example: `[[1], [2]]`: two groups, one with the second site, one with the third.\n Example: `[[1,2], [3]]`: one group with the second and third site, one with the fourth.\n\n - **group_probabilities**: Statistical probability of each group. It MUST have the same length as `sites_in_groups`.\n It SHOULD sum to one.\n See below for examples of how to specify the probability of the occurrence of a vacancy.\n The possible reasons for the values not to sum to one are the same as already specified above for the `concentration` of each `species`.\n\n - If a site is not present in any group, it means that it is present with 100 % probability (as if no assembly was specified).\n - A site MUST NOT appear in more than one group.\n\n- **Examples** (for each entry of the assemblies list):\n - `{\"sites_in_groups\": [[0], [1]], \"group_probabilities: [0.3, 0.7]}`: the first site and the second site never occur at the same time in the unit cell.\n Statistically, 30 % of the times the first site is present, while 70 % of the times the second site is present.\n - `{\"sites_in_groups\": [[1,2], [3]], \"group_probabilities: [0.3, 0.7]}`: the second and third site are either present together or not present; they form the first group of atoms for this assembly.\n The second group is formed by the fourth site.\n Sites of the first group (the second and the third) are never present at the same time as the fourth site.\n 30 % of times sites 1 and 2 are present (and site 3 is absent); 70 % of times site 3 is present (and sites 1 and 2 are absent).\n\n- **Notes**:\n - Assemblies are essential to represent, for instance, the situation where an atom can statistically occupy two different positions (sites).\n\n - By defining groups, it is possible to represent, e.g., the case where a functional molecule (and not just one atom) is either present or absent (or the case where it it is present in two conformations)\n\n - Considerations on virtual alloys and on vacancies: In the special case of a virtual alloy, these specifications allow two different, equivalent ways of specifying them.\n For instance, for a site at the origin with 30 % probability of being occupied by Si, 50 % probability of being occupied by Ge, and 20 % of being a vacancy, the following two representations are possible:\n\n - Using a single species:\n ```json\n {\n \"cartesian_site_positions\": [[0,0,0]],\n \"species_at_sites\": [\"SiGe-vac\"],\n \"species\": [\n {\n \"name\": \"SiGe-vac\",\n \"chemical_symbols\": [\"Si\", \"Ge\", \"vacancy\"],\n \"concentration\": [0.3, 0.5, 0.2]\n }\n ]\n // ...\n }\n ```\n\n - Using multiple species and the assemblies:\n ```json\n {\n \"cartesian_site_positions\": [ [0,0,0], [0,0,0], [0,0,0] ],\n \"species_at_sites\": [\"Si\", \"Ge\", \"vac\"],\n \"species\": [\n { \"name\": \"Si\", \"chemical_symbols\": [\"Si\"], \"concentration\": [1.0] },\n { \"name\": \"Ge\", \"chemical_symbols\": [\"Ge\"], \"concentration\": [1.0] },\n { \"name\": \"vac\", \"chemical_symbols\": [\"vacancy\"], \"concentration\": [1.0] }\n ],\n \"assemblies\": [\n {\n \"sites_in_groups\": [ [0], [1], [2] ],\n \"group_probabilities\": [0.3, 0.5, 0.2]\n }\n ]\n // ...\n }\n ```\n\n - It is up to the database provider to decide which representation to use, typically depending on the internal format in which the structure is stored.\n However, given a structure identified by a unique ID, the API implementation MUST always provide the same representation for it.\n\n - The probabilities of occurrence of different assemblies are uncorrelated.\n So, for instance in the following case with two assemblies:\n ```json\n {\n \"assemblies\": [\n {\n \"sites_in_groups\": [ [0], [1] ],\n \"group_probabilities\": [0.2, 0.8],\n },\n {\n \"sites_in_groups\": [ [2], [3] ],\n \"group_probabilities\": [0.3, 0.7]\n }\n ]\n }\n ```\n\n Site 0 is present with a probability of 20 % and site 1 with a probability of 80 %. These two sites are correlated (either site 0 or 1 is present). Similarly, site 2 is present with a probability of 30 % and site 3 with a probability of 70 %.\n These two sites are correlated (either site 2 or 3 is present).\n However, the presence or absence of sites 0 and 1 is not correlated with the presence or absence of sites 2 and 3 (in the specific example, the pair of sites (0, 2) can occur with 0.2*0.3 = 6 % probability; the pair (0, 3) with 0.2*0.7 = 14 % probability; the pair (1, 2) with 0.8*0.3 = 24 % probability; and the pair (1, 3) with 0.8*0.7 = 56 % probability)." + "description": "A description of groups of sites that are statistically correlated.\n\n- **Type**: list of dictionary with keys:\n - `sites_in_groups`: list of list of integers (REQUIRED)\n - `group_probabilities`: list of floats (REQUIRED)\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - The property SHOULD be `null` for entries that have no partial occupancies.\n - If present, the correct flag MUST be set in the list `structure_features`.\n - Client implementations MUST check its presence (as its presence changes the interpretation of the structure).\n - If present, it MUST be a list of dictionaries, each of which represents an assembly and MUST have the following two keys:\n - **sites_in_groups**: Index of the sites (0-based) that belong to each group for each assembly.\n\n Example: `[[1], [2]]`: two groups, one with the second site, one with the third.\n Example: `[[1,2], [3]]`: one group with the second and third site, one with the fourth.\n\n - **group_probabilities**: Statistical probability of each group. It MUST have the same length as `sites_in_groups`.\n It SHOULD sum to one.\n See below for examples of how to specify the probability of the occurrence of a vacancy.\n The possible reasons for the values not to sum to one are the same as already specified above for the `concentration` of each `species`.\n\n - If a site is not present in any group, it means that it is present with 100 % probability (as if no assembly was specified).\n - A site MUST NOT appear in more than one group.\n\n- **Examples** (for each entry of the assemblies list):\n - `{\"sites_in_groups\": [[0], [1]], \"group_probabilities: [0.3, 0.7]}`: the first site and the second site never occur at the same time in the unit cell.\n Statistically, 30 % of the times the first site is present, while 70 % of the times the second site is present.\n - `{\"sites_in_groups\": [[1,2], [3]], \"group_probabilities: [0.3, 0.7]}`: the second and third site are either present together or not present; they form the first group of atoms for this assembly.\n The second group is formed by the fourth site.\n Sites of the first group (the second and the third) are never present at the same time as the fourth site.\n 30 % of times sites 1 and 2 are present (and site 3 is absent); 70 % of times site 3 is present (and sites 1 and 2 are absent).\n\n- **Notes**:\n - Assemblies are essential to represent, for instance, the situation where an atom can statistically occupy two different positions (sites).\n\n - By defining groups, it is possible to represent, e.g., the case where a functional molecule (and not just one atom) is either present or absent (or the case where it it is present in two conformations)\n\n - Considerations on virtual alloys and on vacancies: In the special case of a virtual alloy, these specifications allow two different, equivalent ways of specifying them.\n For instance, for a site at the origin with 30 % probability of being occupied by Si, 50 % probability of being occupied by Ge, and 20 % of being a vacancy, the following two representations are possible:\n\n - Using a single species:\n ```json\n {\n \"cartesian_site_positions\": [[0,0,0]],\n \"species_at_sites\": [\"SiGe-vac\"],\n \"species\": [\n {\n \"name\": \"SiGe-vac\",\n \"chemical_symbols\": [\"Si\", \"Ge\", \"vacancy\"],\n \"concentration\": [0.3, 0.5, 0.2]\n }\n ]\n // ...\n }\n ```\n\n - Using multiple species and the assemblies:\n ```json\n {\n \"cartesian_site_positions\": [ [0,0,0], [0,0,0], [0,0,0] ],\n \"species_at_sites\": [\"Si\", \"Ge\", \"vac\"],\n \"species\": [\n { \"name\": \"Si\", \"chemical_symbols\": [\"Si\"], \"concentration\": [1.0] },\n { \"name\": \"Ge\", \"chemical_symbols\": [\"Ge\"], \"concentration\": [1.0] },\n { \"name\": \"vac\", \"chemical_symbols\": [\"vacancy\"], \"concentration\": [1.0] }\n ],\n \"assemblies\": [\n {\n \"sites_in_groups\": [ [0], [1], [2] ],\n \"group_probabilities\": [0.3, 0.5, 0.2]\n }\n ]\n // ...\n }\n ```\n\n - It is up to the database provider to decide which representation to use, typically depending on the internal format in which the structure is stored.\n However, given a structure identified by a unique ID, the API implementation MUST always provide the same representation for it.\n\n - The probabilities of occurrence of different assemblies are uncorrelated.\n So, for instance in the following case with two assemblies:\n ```json\n {\n \"assemblies\": [\n {\n \"sites_in_groups\": [ [0], [1] ],\n \"group_probabilities\": [0.2, 0.8],\n },\n {\n \"sites_in_groups\": [ [2], [3] ],\n \"group_probabilities\": [0.3, 0.7]\n }\n ]\n }\n ```\n\n Site 0 is present with a probability of 20 % and site 1 with a probability of 80 %. These two sites are correlated (either site 0 or 1 is present). Similarly, site 2 is present with a probability of 30 % and site 3 with a probability of 70 %.\n These two sites are correlated (either site 2 or 3 is present).\n However, the presence or absence of sites 0 and 1 is not correlated with the presence or absence of sites 2 and 3 (in the specific example, the pair of sites (0, 2) can occur with 0.2*0.3 = 6 % probability; the pair (0, 3) with 0.2*0.7 = 14 % probability; the pair (1, 2) with 0.8*0.3 = 24 % probability; and the pair (1, 3) with 0.8*0.7 = 56 % probability).", + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "structure_features": { "title": "Structure Features", @@ -3557,7 +3712,9 @@ "items": { "$ref": "#/components/schemas/StructureFeatures" }, - "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": "A list of strings that flag which special features are used by the structure.\n\n- **Type**: list of strings\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property.\n Filters on the list MUST support all mandatory HAS-type queries.\n Filter operators for comparisons on the string components MUST support equality, support for other comparison operators are OPTIONAL.\n - MUST be an empty list if no special features are used.\n - MUST be sorted alphabetically.\n - If a special feature listed below is used, the list MUST contain the corresponding string.\n - If a special feature listed below is not used, the list MUST NOT contain the corresponding string.\n - **List of strings used to indicate special structure features**:\n - `disorder`: this flag MUST be present if any one entry in the `species` list has a `chemical_symbols` list that is longer than 1 element.\n - `implicit_atoms`: this flag MUST be present if the structure contains atoms that are not assigned to sites via the property `species_at_sites` (e.g., because their positions are unknown).\n When this flag is present, the properties related to the chemical formula will likely not match the type and count of atoms represented by the `species_at_sites`, `species` and `assemblies` properties.\n - `site_attachments`: this flag MUST be present if any one entry in the `species` list includes `attached` and `nattached`.\n - `assemblies`: this flag MUST be present if the property `assemblies` is present.\n\n- **Examples**: A structure having implicit atoms and using assemblies: `[\"assemblies\", \"implicit_atoms\"]`", + "x-optimade-queryable": "must", + "x-optimade-support": "must" } }, "description": "This class contains the Field for the attributes used to represent a structure, e.g. unit cell, atoms, positions." @@ -3587,7 +3744,7 @@ } } ], - "description": "List of unique OPTIMADE structures entry resource objects" + "description": "List of unique OPTIMADE structures entry resource objects." }, "meta": { "title": "Meta", @@ -3664,7 +3821,7 @@ "type": "object" } ], - "description": "A single structures entry resource" + "description": "A single structures entry resource." }, "meta": { "title": "Meta", @@ -3731,9 +3888,9 @@ "title": "Self", "anyOf": [ { - "type": "string", - "minLength": 1, "maxLength": 65536, + "minLength": 1, + "type": "string", "format": "uri" }, { @@ -3746,9 +3903,9 @@ "title": "Related", "anyOf": [ { - "type": "string", - "minLength": 1, "maxLength": 65536, + "minLength": 1, + "type": "string", "format": "uri" }, { @@ -3761,9 +3918,9 @@ "title": "First", "anyOf": [ { - "type": "string", - "minLength": 1, "maxLength": 65536, + "minLength": 1, + "type": "string", "format": "uri" }, { @@ -3776,9 +3933,9 @@ "title": "Last", "anyOf": [ { - "type": "string", - "minLength": 1, "maxLength": 65536, + "minLength": 1, + "type": "string", "format": "uri" }, { @@ -3791,9 +3948,9 @@ "title": "Prev", "anyOf": [ { - "type": "string", - "minLength": 1, "maxLength": 65536, + "minLength": 1, + "type": "string", "format": "uri" }, { @@ -3806,9 +3963,9 @@ "title": "Next", "anyOf": [ { - "type": "string", - "minLength": 1, "maxLength": 65536, + "minLength": 1, + "type": "string", "format": "uri" }, { @@ -3879,7 +4036,8 @@ "title": "Type", "pattern": "^warning$", "type": "string", - "description": "Warnings must be of type \"warning\"" + "description": "Warnings must be of type \"warning\"", + "default": "warning" } }, "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/v1.1.0/optimade_index.json b/openapi/v1.1.0/optimade_index.json index 9fc7609..2ab4693 100644 --- a/openapi/v1.1.0/optimade_index.json +++ b/openapi/v1.1.0/optimade_index.json @@ -2,7 +2,7 @@ "openapi": "3.0.2", "info": { "title": "OPTIMADE API - Index meta-database", - "description": "The [Open Databases Integration for Materials Design (OPTIMADE) consortium](https://www.optimade.org/) aims to make materials databases interoperational by developing a common REST API.\nThis is the \"special\" index meta-database.\n\nThis specification is generated using [`optimade-python-tools`](https://github.com/Materials-Consortia/optimade-python-tools/tree/v0.16.0) v0.16.0.", + "description": "The [Open Databases Integration for Materials Design (OPTIMADE) consortium](https://www.optimade.org/) aims to make materials databases interoperational by developing a common REST API.\nThis is the \"special\" index meta-database.\n\nThis specification is generated using [`optimade-python-tools`](https://github.com/Materials-Consortia/optimade-python-tools/tree/v0.19.1) v0.19.1.", "version": "1.1.0" }, "paths": { @@ -17,7 +17,7 @@ "200": { "description": "Successful Response", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/IndexInfoResponse" } @@ -27,7 +27,7 @@ "400": { "description": "Bad Request", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -37,7 +37,7 @@ "403": { "description": "Forbidden", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -47,7 +47,7 @@ "404": { "description": "Not Found", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -57,7 +57,7 @@ "422": { "description": "Unprocessable Entity", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -67,7 +67,7 @@ "500": { "description": "Internal Server Error", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -77,7 +77,7 @@ "501": { "description": "Not Implemented", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -87,7 +87,7 @@ "553": { "description": "Version Not Supported", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -199,7 +199,7 @@ "required": false, "schema": { "title": "Page Number", - "minimum": 0.0, + "minimum": 1.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`.", "default": 0 @@ -276,7 +276,7 @@ "200": { "description": "Successful Response", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/LinksResponse" } @@ -286,7 +286,7 @@ "400": { "description": "Bad Request", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -296,7 +296,7 @@ "403": { "description": "Forbidden", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -306,7 +306,7 @@ "404": { "description": "Not Found", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -316,7 +316,7 @@ "422": { "description": "Unprocessable Entity", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -326,7 +326,7 @@ "500": { "description": "Internal Server Error", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -336,7 +336,7 @@ "501": { "description": "Not Implemented", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -346,7 +346,7 @@ "553": { "description": "Version Not Supported", "content": { - "application/json": { + "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } @@ -418,7 +418,12 @@ "title": "Version", "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$", "type": "string", - "description": "A string containing the full version number of the API served at that versioned base URL.\nThe version number string MUST NOT be prefixed by, e.g., 'v'.\nExamples: `1.0.0`, `1.0.0-rc.2`." + "description": "A string containing the full version number of the API served at that versioned base URL.\nThe version number string MUST NOT be prefixed by, e.g., 'v'.\nExamples: `1.0.0`, `1.0.0-rc.2`.", + "example": [ + "0.10.1", + "1.0.0-rc.2", + "1.2.3-rc.5+develop" + ] } }, "description": "A JSON object containing information about an available API version" @@ -433,7 +438,7 @@ "description": { "title": "Description", "type": "string", - "description": "OPTIONAL human-readable description of the relationship" + "description": "OPTIONAL human-readable description of the relationship." } }, "description": "Specific meta field for base relationship resource" @@ -505,12 +510,16 @@ "id": { "title": "Id", "type": "string", - "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`" + "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "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- **Example**: `\"structures\"`", + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "links": { "title": "Links", @@ -561,13 +570,17 @@ "immutable_id": { "title": "Immutable Id", "type": "string", - "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)" + "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", + "x-optimade-queryable": "must", + "x-optimade-support": "optional" }, "last_modified": { "title": "Last Modified", "type": "string", "description": "Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n - As part of JSON response format: `\"2007-04-05T14:30:20Z\"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)", - "format": "date-time" + "format": "date-time", + "x-optimade-queryable": "must", + "x-optimade-support": "should" } }, "description": "Contains key-value pairs representing the entry's properties." @@ -639,9 +652,9 @@ "title": "About", "anyOf": [ { - "type": "string", - "minLength": 1, "maxLength": 65536, + "minLength": 1, + "type": "string", "format": "uri" }, { @@ -684,7 +697,7 @@ "$ref": "#/components/schemas/ResponseMeta" } ], - "description": "A meta object containing non-standard information" + "description": "A meta object containing non-standard information." }, "errors": { "title": "Errors", @@ -760,9 +773,9 @@ "title": "Homepage", "anyOf": [ { - "type": "string", - "minLength": 1, "maxLength": 65536, + "minLength": 1, + "type": "string", "format": "uri" }, { @@ -775,9 +788,9 @@ "title": "Source Url", "anyOf": [ { - "type": "string", - "minLength": 1, "maxLength": 65536, + "minLength": 1, + "type": "string", "format": "uri" }, { @@ -799,9 +812,9 @@ "title": "Issue Tracker", "anyOf": [ { - "type": "string", - "minLength": 1, "maxLength": 65536, + "minLength": 1, + "type": "string", "format": "uri" }, { @@ -843,7 +856,12 @@ "title": "Api Version", "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$", "type": "string", - "description": "Presently used full version of the OPTIMADE API.\nThe version number string MUST NOT be prefixed by, e.g., \"v\".\nExamples: `1.0.0`, `1.0.0-rc.2`." + "description": "Presently used full version of the OPTIMADE API.\nThe version number string MUST NOT be prefixed by, e.g., \"v\".\nExamples: `1.0.0`, `1.0.0-rc.2`.", + "example": [ + "0.10.1", + "1.0.0-rc.2", + "1.2.3-rc.5+develop" + ] }, "available_api_versions": { "title": "Available Api Versions", @@ -886,7 +904,8 @@ "is_index": { "title": "Is Index", "type": "boolean", - "description": "This must be `true` since this is an index meta-database (see section Index Meta-Database)." + "description": "This must be `true` since this is an index meta-database (see section Index Meta-Database).", + "default": true } }, "description": "Attributes for Base URL Info endpoint for an Index Meta-Database" @@ -904,12 +923,14 @@ "id": { "title": "Id", "pattern": "^/$", - "type": "string" + "type": "string", + "default": "/" }, "type": { "title": "Type", "pattern": "^info$", - "type": "string" + "type": "string", + "default": "info" }, "links": { "title": "Links", @@ -958,7 +979,7 @@ "$ref": "#/components/schemas/IndexInfoResource" } ], - "description": "Index meta-database /info data" + "description": "Index meta-database /info data." }, "meta": { "title": "Meta", @@ -1098,13 +1119,16 @@ "id": { "title": "Id", "type": "string", - "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`" + "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "type": { "title": "Type", "pattern": "^links$", "type": "string", - "description": "These objects are described in detail in the section Links Endpoint" + "description": "These objects are described in detail in the section Links Endpoint", + "default": "links" }, "links": { "title": "Links", @@ -1170,9 +1194,9 @@ "title": "Base Url", "anyOf": [ { - "type": "string", - "minLength": 1, "maxLength": 65536, + "minLength": 1, + "type": "string", "format": "uri" }, { @@ -1185,9 +1209,9 @@ "title": "Homepage", "anyOf": [ { - "type": "string", - "minLength": 1, "maxLength": 65536, + "minLength": 1, + "type": "string", "format": "uri" }, { @@ -1248,7 +1272,7 @@ } } ], - "description": "List of unique OPTIMADE links resource objects" + "description": "List of unique OPTIMADE links resource objects." }, "meta": { "title": "Meta", @@ -1404,9 +1428,9 @@ "title": "Homepage", "anyOf": [ { - "type": "string", - "minLength": 1, "maxLength": 65536, + "minLength": 1, + "type": "string", "format": "uri" }, { @@ -1457,7 +1481,7 @@ "description": "a meta object that contains non-standard meta-information about the relationship." } }, - "description": "Similar to normal JSON API relationship, but with addition of OPTIONAL meta field for a resource" + "description": "Similar to normal JSON API relationship, but with addition of OPTIONAL meta field for a resource." }, "RelatedLinksResource": { "title": "RelatedLinksResource", @@ -1475,7 +1499,8 @@ "type": { "title": "Type", "pattern": "^links$", - "type": "string" + "type": "string", + "default": "links" } }, "description": "A related Links resource object" @@ -1488,9 +1513,9 @@ "title": "Self", "anyOf": [ { - "type": "string", - "minLength": 1, "maxLength": 65536, + "minLength": 1, + "type": "string", "format": "uri" }, { @@ -1503,9 +1528,9 @@ "title": "Related", "anyOf": [ { - "type": "string", - "minLength": 1, "maxLength": 65536, + "minLength": 1, + "type": "string", "format": "uri" }, { @@ -1588,9 +1613,9 @@ "title": "Self", "anyOf": [ { - "type": "string", - "minLength": 1, "maxLength": 65536, + "minLength": 1, + "type": "string", "format": "uri" }, { @@ -1624,7 +1649,12 @@ "title": "Api Version", "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$", "type": "string", - "description": "Presently used full version of the OPTIMADE API.\nThe version number string MUST NOT be prefixed by, e.g., \"v\".\nExamples: `1.0.0`, `1.0.0-rc.2`." + "description": "Presently used full version of the OPTIMADE API.\nThe version number string MUST NOT be prefixed by, e.g., \"v\".\nExamples: `1.0.0`, `1.0.0-rc.2`.", + "example": [ + "0.10.1", + "1.0.0-rc.2", + "1.2.3-rc.5+develop" + ] }, "more_data_available": { "title": "More Data Available", @@ -1635,9 +1665,9 @@ "title": "Schema", "anyOf": [ { - "type": "string", - "minLength": 1, "maxLength": 65536, + "minLength": 1, + "type": "string", "format": "uri" }, { @@ -1757,7 +1787,7 @@ "description": "a meta object that contains non-standard meta-information about the relationship." } }, - "description": "Similar to normal JSON API relationship, but with addition of OPTIONAL meta field for a resource" + "description": "Similar to normal JSON API relationship, but with addition of OPTIONAL meta field for a resource." }, "ToplevelLinks": { "title": "ToplevelLinks", @@ -1767,9 +1797,9 @@ "title": "Self", "anyOf": [ { - "type": "string", - "minLength": 1, "maxLength": 65536, + "minLength": 1, + "type": "string", "format": "uri" }, { @@ -1782,9 +1812,9 @@ "title": "Related", "anyOf": [ { - "type": "string", - "minLength": 1, "maxLength": 65536, + "minLength": 1, + "type": "string", "format": "uri" }, { @@ -1797,9 +1827,9 @@ "title": "First", "anyOf": [ { - "type": "string", - "minLength": 1, "maxLength": 65536, + "minLength": 1, + "type": "string", "format": "uri" }, { @@ -1812,9 +1842,9 @@ "title": "Last", "anyOf": [ { - "type": "string", - "minLength": 1, "maxLength": 65536, + "minLength": 1, + "type": "string", "format": "uri" }, { @@ -1827,9 +1857,9 @@ "title": "Prev", "anyOf": [ { - "type": "string", - "minLength": 1, "maxLength": 65536, + "minLength": 1, + "type": "string", "format": "uri" }, { @@ -1842,9 +1872,9 @@ "title": "Next", "anyOf": [ { - "type": "string", - "minLength": 1, "maxLength": 65536, + "minLength": 1, + "type": "string", "format": "uri" }, { @@ -1915,7 +1945,8 @@ "title": "Type", "pattern": "^warning$", "type": "string", - "description": "Warnings must be of type \"warning\"" + "description": "Warnings must be of type \"warning\"", + "default": "warning" } }, "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." From 3cf0e777ff931c1a50e3ab5b855b80d6acb67763 Mon Sep 17 00:00:00 2001 From: Matthew Evans Date: Wed, 26 Oct 2022 10:37:41 +0100 Subject: [PATCH 2/4] Bump schema to 0.19.5 with `page_number` fix --- openapi/v1.1.0/optimade.json | 284 ++++++++++++++--------------- openapi/v1.1.0/optimade_index.json | 26 ++- 2 files changed, 151 insertions(+), 159 deletions(-) diff --git a/openapi/v1.1.0/optimade.json b/openapi/v1.1.0/optimade.json index 4801a86..35ad35a 100644 --- a/openapi/v1.1.0/optimade.json +++ b/openapi/v1.1.0/optimade.json @@ -2,7 +2,7 @@ "openapi": "3.0.2", "info": { "title": "OPTIMADE API", - "description": "The [Open Databases Integration for Materials Design (OPTIMADE) consortium](https://www.optimade.org/) aims to make materials databases interoperational by developing a common REST API.\n\nThis specification is generated using [`optimade-python-tools`](https://github.com/Materials-Consortia/optimade-python-tools/tree/v0.19.1) v0.19.1.", + "description": "The [Open Databases Integration for Materials Design (OPTIMADE) consortium](https://www.optimade.org/) aims to make materials databases interoperational by developing a common REST API.\n\nThis specification is generated using [`optimade-python-tools`](https://github.com/Materials-Consortia/optimade-python-tools/tree/v0.19.5) v0.19.5.", "version": "1.1.0" }, "paths": { @@ -301,10 +301,8 @@ "required": false, "schema": { "title": "Page Number", - "minimum": 1.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`.", - "default": 0 + "description": "RECOMMENDED for use with _page-based_ pagination: using `page_number` and `page_limit` is RECOMMENDED.\nIt is RECOMMENDED that the first page has number 1, i.e., that `page_number` is 1-based.\nExample: Fetch page 2 of up to 50 structures per page: `/structures?page_number=2&page_limit=50`." }, "name": "page_number", "in": "query" @@ -560,10 +558,8 @@ "required": false, "schema": { "title": "Page Number", - "minimum": 1.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`.", - "default": 0 + "description": "RECOMMENDED for use with _page-based_ pagination: using `page_number` and `page_limit` is RECOMMENDED.\nIt is RECOMMENDED that the first page has number 1, i.e., that `page_number` is 1-based.\nExample: Fetch page 2 of up to 50 structures per page: `/structures?page_number=2&page_limit=50`." }, "name": "page_number", "in": "query" @@ -984,10 +980,8 @@ "required": false, "schema": { "title": "Page Number", - "minimum": 1.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`.", - "default": 0 + "description": "RECOMMENDED for use with _page-based_ pagination: using `page_number` and `page_limit` is RECOMMENDED.\nIt is RECOMMENDED that the first page has number 1, i.e., that `page_number` is 1-based.\nExample: Fetch page 2 of up to 50 structures per page: `/structures?page_number=2&page_limit=50`." }, "name": "page_number", "in": "query" @@ -1359,8 +1353,8 @@ } }, "description": "Index of the sites (0-based) that belong to each group for each assembly.\n\n- **Examples**:\n - `[[1], [2]]`: two groups, one with the second site, one with the third.\n - `[[1,2], [3]]`: one group with the second and third site, one with the fourth.", - "x-optimade-queryable": "optional", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "optional" }, "group_probabilities": { "title": "Group Probabilities", @@ -1369,8 +1363,8 @@ "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`.", - "x-optimade-queryable": "optional", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "optional" } }, "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)." @@ -1591,7 +1585,7 @@ "dictionary", "unknown" ], - "description": "Optimade Data Types\n\nSee the section \"Data types\" in the OPTIMADE API specification for more information." + "description": "Optimade Data Types\n\n See the section \"Data types\" in the OPTIMADE API specification for more information.\n " }, "EntryInfoProperty": { "title": "EntryInfoProperty", @@ -1773,15 +1767,15 @@ "title": "Id", "type": "string", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "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\"`", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "links": { "title": "Links", @@ -1833,16 +1827,16 @@ "title": "Immutable Id", "type": "string", "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", - "x-optimade-queryable": "must", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "must" }, "last_modified": { "title": "Last Modified", "type": "string", "description": "Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n - As part of JSON response format: `\"2007-04-05T14:30:20Z\"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)", "format": "date-time", - "x-optimade-queryable": "must", - "x-optimade-support": "should" + "x-optimade-support": "should", + "x-optimade-queryable": "must" } }, "description": "Contains key-value pairs representing the entry's properties." @@ -2241,8 +2235,8 @@ "title": "Id", "type": "string", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "type": { "title": "Type", @@ -2540,22 +2534,22 @@ "title": "Name", "type": "string", "description": "Full name of the person, REQUIRED.", - "x-optimade-queryable": "optional", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "optional" }, "firstname": { "title": "Firstname", "type": "string", "description": "First name of the person.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "lastname": { "title": "Lastname", "type": "string", "description": "Last name of the person.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" } }, "description": "A person, i.e., an author, editor or other." @@ -2657,8 +2651,8 @@ "title": "Id", "type": "string", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "type": { "title": "Type", @@ -2666,8 +2660,8 @@ "type": "string", "description": "The name of the type of an entry.\n- **Type**: string.\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - MUST be an existing entry type.\n - The entry of type and ID MUST be returned in response to a request for `//` under the versioned base URL.\n- **Example**: `\"structures\"`", "default": "references", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "links": { "title": "Links", @@ -2713,16 +2707,16 @@ "title": "Immutable Id", "type": "string", "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", - "x-optimade-queryable": "must", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "must" }, "last_modified": { "title": "Last Modified", "type": "string", "description": "Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n - As part of JSON response format: `\"2007-04-05T14:30:20Z\"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)", "format": "date-time", - "x-optimade-queryable": "must", - "x-optimade-support": "should" + "x-optimade-support": "should", + "x-optimade-queryable": "must" }, "authors": { "title": "Authors", @@ -2731,8 +2725,8 @@ "$ref": "#/components/schemas/Person" }, "description": "List of person objects containing the authors of the reference.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "editors": { "title": "Editors", @@ -2741,15 +2735,15 @@ "$ref": "#/components/schemas/Person" }, "description": "List of person objects containing the editors of the reference.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "doi": { "title": "Doi", "type": "string", "description": "The digital object identifier of the reference.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "url": { "title": "Url", @@ -2758,162 +2752,162 @@ "type": "string", "description": "The URL of the reference.", "format": "uri", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "address": { "title": "Address", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "annote": { "title": "Annote", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "booktitle": { "title": "Booktitle", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "chapter": { "title": "Chapter", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "crossref": { "title": "Crossref", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "edition": { "title": "Edition", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "howpublished": { "title": "Howpublished", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "institution": { "title": "Institution", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "journal": { "title": "Journal", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "key": { "title": "Key", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "month": { "title": "Month", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "note": { "title": "Note", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "number": { "title": "Number", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "organization": { "title": "Organization", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "pages": { "title": "Pages", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "publisher": { "title": "Publisher", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "school": { "title": "School", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "series": { "title": "Series", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "title": { "title": "Title", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "bib_type": { "title": "Bib Type", "type": "string", "description": "Type of the reference, corresponding to the **type** property in the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "volume": { "title": "Volume", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "year": { "title": "Year", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" } }, "description": "Model that stores the attributes of a reference.\n\nMany properties match the meaning described in the\n[BibTeX specification](http://bibtexml.sourceforge.net/btxdoc.pdf)." @@ -3335,8 +3329,8 @@ "title": "Name", "type": "string", "description": "Gives the name of the species; the **name** value MUST be unique in the `species` list.", - "x-optimade-queryable": "optional", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "optional" }, "chemical_symbols": { "title": "Chemical Symbols", @@ -3345,8 +3339,8 @@ "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 symbol, or\n- the special value `\"X\"` to represent a non-chemical element, or\n- the special value `\"vacancy\"` to represent that this site has a non-zero probability of having a vacancy (the respective probability is indicated in the `concentration` list, see below).\n\nIf any one entry in the `species` list has a `chemical_symbols` list that is longer than 1 element, the correct flag MUST be set in the list `structure_features`.", - "x-optimade-queryable": "optional", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "optional" }, "concentration": { "title": "Concentration", @@ -3355,8 +3349,8 @@ "type": "number" }, "description": "MUST be a list of floats, with same length as `chemical_symbols`. The numbers represent the relative concentration of the corresponding chemical symbol in this species. The numbers SHOULD sum to one. Cases in which the numbers do not sum to one typically fall only in the following two categories:\n\n- Numerical errors when representing float numbers in fixed precision, e.g. for two chemical symbols with concentrations `1/3` and `2/3`, the concentration might look something like `[0.33333333333, 0.66666666666]`. If the client is aware that the sum is not one because of numerical precision, it can renormalize the values so that the sum is exactly one.\n- Experimental errors in the data present in the database. In this case, it is the responsibility of the client to decide how to process the data.\n\nNote that concentrations are uncorrelated between different site (even of the same species).", - "x-optimade-queryable": "optional", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "optional" }, "mass": { "title": "Mass", @@ -3365,16 +3359,16 @@ "type": "number" }, "description": "If present MUST be a list of floats expressed in a.m.u.\nElements denoting vacancies MUST have masses equal to 0.", - "x-optimade-queryable": "optional", "x-optimade-unit": "a.m.u.", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "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.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "attached": { "title": "Attached", @@ -3383,8 +3377,8 @@ "type": "string" }, "description": "If provided MUST be a list of length 1 or more of strings of chemical symbols for the elements attached to this site, or \"X\" for a non-chemical element.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "nattached": { "title": "Nattached", @@ -3393,8 +3387,8 @@ "type": "integer" }, "description": "If provided MUST be a list of length 1 or more of integers indicating the number of attached atoms of the kind specified in the value of the :field:`attached` key.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" } }, "description": "A list describing the species of the sites of this structure.\n\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\": [0.0, 137.327, 40.078]} ]`: any site with this species is occupied by a Ba atom with 45 % probability, a Ca atom with 50 % probability, and by a vacancy with 5 % probability. The mass of this site is (on average) 88.5 a.m.u.\n - `[ {\"name\": \"C12\", \"chemical_symbols\": [\"C\"], \"concentration\": [1.0], \"mass\": [12.0]} ]`: any site with this species is occupied by a carbon isotope with mass 12.\n - `[ {\"name\": \"C13\", \"chemical_symbols\": [\"C\"], \"concentration\": [1.0], \"mass\": [13.0]} ]`: any site with this species is occupied by a carbon isotope with mass 13.\n - `[ {\"name\": \"CH3\", \"chemical_symbols\": [\"C\"], \"concentration\": [1.0], \"attached\": [\"H\"], \"nattached\": [3]} ]`: any site with this species is occupied by a methyl group, -CH3, which is represented without specifying precise positions of the hydrogen atoms." @@ -3463,8 +3457,8 @@ "title": "Id", "type": "string", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "type": { "title": "Type", @@ -3472,8 +3466,8 @@ "type": "string", "description": "The name of the type of an entry.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - MUST be an existing entry type.\n - The entry of type `` and ID `` MUST be returned in response to a request for `//` under the versioned base URL.\n\n- **Examples**:\n - `\"structures\"`", "default": "structures", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "links": { "title": "Links", @@ -3533,8 +3527,8 @@ "title": "Immutable Id", "type": "string", "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", - "x-optimade-queryable": "must", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "must" }, "last_modified": { "title": "Last Modified", @@ -3542,8 +3536,8 @@ "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", "nullable": true, - "x-optimade-queryable": "must", - "x-optimade-support": "should" + "x-optimade-support": "should", + "x-optimade-queryable": "must" }, "elements": { "title": "Elements", @@ -3553,16 +3547,16 @@ }, "description": "The chemical symbols of the different elements present in the structure.\n\n- **Type**: list of strings.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - The strings are the chemical symbols, i.e., either a single uppercase letter or an uppercase letter followed by a number of lowercase letters.\n - The order MUST be alphabetical.\n - MUST refer to the same elements in the same order, and therefore be of the same length, as `elements_ratios`, if the latter is provided.\n - Note: This property SHOULD NOT contain the string \"X\" to indicate non-chemical elements or \"vacancy\" to indicate vacancies (in contrast to the field `chemical_symbols` for the `species` property).\n\n- **Examples**:\n - `[\"Si\"]`\n - `[\"Al\",\"O\",\"Si\"]`\n\n- **Query examples**:\n - A filter that matches all records of structures that contain Si, Al **and** O, and possibly other elements: `elements HAS ALL \"Si\", \"Al\", \"O\"`.\n - To match structures with exactly these three elements, use `elements HAS ALL \"Si\", \"Al\", \"O\" AND elements LENGTH 3`.\n - Note: length queries on this property can be equivalently formulated by filtering on the `nelements`_ property directly.", "nullable": true, - "x-optimade-queryable": "must", - "x-optimade-support": "should" + "x-optimade-support": "should", + "x-optimade-queryable": "must" }, "nelements": { "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 - MUST be equal to the lengths of the list properties `elements` and `elements_ratios`, if they are provided.\n\n- **Examples**:\n - `3`\n\n- **Querying**:\n - Note: queries on this property can equivalently be formulated using `elements LENGTH`.\n - A filter that matches structures that have exactly 4 elements: `nelements=4`.\n - A filter that matches structures that have between 2 and 7 elements: `nelements>=2 AND nelements<=7`.", "nullable": true, - "x-optimade-queryable": "must", - "x-optimade-support": "should" + "x-optimade-support": "should", + "x-optimade-queryable": "must" }, "elements_ratios": { "title": "Elements Ratios", @@ -3572,16 +3566,16 @@ }, "description": "Relative proportions of different elements in the structure.\n\n- **Type**: list of floats\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - Composed by the proportions of elements in the structure as a list of floating point numbers.\n - The sum of the numbers MUST be 1.0 (within floating point accuracy)\n - MUST refer to the same elements in the same order, and therefore be of the same length, as `elements`, if the latter is provided.\n\n- **Examples**:\n - `[1.0]`\n - `[0.3333333333333333, 0.2222222222222222, 0.4444444444444444]`\n\n- **Query examples**:\n - Note: Useful filters can be formulated using the set operator syntax for correlated values.\n However, since the values are floating point values, the use of equality comparisons is generally inadvisable.\n - OPTIONAL: a filter that matches structures where approximately 1/3 of the atoms in the structure are the element Al is: `elements:elements_ratios HAS ALL \"Al\":>0.3333, \"Al\":<0.3334`.", "nullable": true, - "x-optimade-queryable": "must", - "x-optimade-support": "should" + "x-optimade-support": "should", + "x-optimade-queryable": "must" }, "chemical_formula_descriptive": { "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\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - The chemical formula is given as a string consisting of properly capitalized element symbols followed by integers or decimal numbers, balanced parentheses, square, and curly brackets `(`,`)`, `[`,`]`, `{`, `}`, commas, the `+`, `-`, `:` and `=` symbols. The parentheses are allowed to be followed by a number. Spaces are allowed anywhere except within chemical symbols. The order of elements and any groupings indicated by parentheses or brackets are chosen freely by the API implementation.\n - The string SHOULD be arithmetically consistent with the element ratios in the `chemical_formula_reduced` property.\n - It is RECOMMENDED, but not mandatory, that symbols, parentheses and brackets, if used, are used with the meanings prescribed by [IUPAC's Nomenclature of Organic Chemistry](https://www.qmul.ac.uk/sbcs/iupac/bibliog/blue.html).\n\n- **Examples**:\n - `\"(H2O)2 Na\"`\n - `\"NaCl\"`\n - `\"CaCO3\"`\n - `\"CCaO3\"`\n - `\"(CH3)3N+ - [CH2]2-OH = Me3N+ - CH2 - CH2OH\"`\n\n- **Query examples**:\n - Note: the free-form nature of this property is likely to make queries on it across different databases inconsistent.\n - A filter that matches an exactly given formula: `chemical_formula_descriptive=\"(H2O)2 Na\"`.\n - A filter that does a partial match: `chemical_formula_descriptive CONTAINS \"H2O\"`.", "nullable": true, - "x-optimade-queryable": "must", - "x-optimade-support": "should" + "x-optimade-support": "should", + "x-optimade-queryable": "must" }, "chemical_formula_reduced": { "title": "Chemical Formula Reduced", @@ -3589,16 +3583,16 @@ "type": "string", "description": "The reduced chemical formula for a structure as a string with element symbols and integer chemical proportion numbers.\nThe proportion number MUST be omitted if it is 1.\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property.\n However, support for filters using partial string matching with this property is OPTIONAL (i.e., BEGINS WITH, ENDS WITH, and CONTAINS).\n Intricate queries on formula components are instead suggested to be formulated using set-type filter operators on the multi valued `elements` and `elements_ratios` properties.\n - Element symbols MUST have proper capitalization (e.g., `\"Si\"`, not `\"SI\"` for \"silicon\").\n - Elements MUST be placed in alphabetical order, followed by their integer chemical proportion number.\n - For structures with no partial occupation, the chemical proportion numbers are the smallest integers for which the chemical proportion is exactly correct.\n - For structures with partial occupation, the chemical proportion numbers are integers that within reasonable approximation indicate the correct chemical proportions. The precise details of how to perform the rounding is chosen by the API implementation.\n - No spaces or separators are allowed.\n\n- **Examples**:\n - `\"H2NaO\"`\n - `\"ClNa\"`\n - `\"CCaO3\"`\n\n- **Query examples**:\n - A filter that matches an exactly given formula is `chemical_formula_reduced=\"H2NaO\"`.", "nullable": true, - "x-optimade-queryable": "must", - "x-optimade-support": "should" + "x-optimade-support": "should", + "x-optimade-queryable": "must" }, "chemical_formula_hill": { "title": "Chemical Formula Hill", "pattern": "^([A-Z][a-z]?([2-9]|[1-9]\\d+)?)+$", "type": "string", "description": "The chemical formula for a structure in [Hill form](https://dx.doi.org/10.1021/ja02046a005) with element symbols followed by integer chemical proportion numbers. The proportion number MUST be omitted if it is 1.\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, only a subset of the filter features MAY be supported.\n - The overall scale factor of the chemical proportions is chosen such that the resulting values are integers that indicate the most chemically relevant unit of which the system is composed.\n For example, if the structure is a repeating unit cell with four hydrogens and four oxygens that represents two hydroperoxide molecules, `chemical_formula_hill` is `\"H2O2\"` (i.e., not `\"HO\"`, nor `\"H4O4\"`).\n - If the chemical insight needed to ascribe a Hill formula to the system is not present, the property MUST be handled as unset.\n - Element symbols MUST have proper capitalization (e.g., `\"Si\"`, not `\"SI\"` for \"silicon\").\n - Elements MUST be placed in [Hill order](https://dx.doi.org/10.1021/ja02046a005), followed by their integer chemical proportion number.\n Hill order means: if carbon is present, it is placed first, and if also present, hydrogen is placed second.\n After that, all other elements are ordered alphabetically.\n If carbon is not present, all elements are ordered alphabetically.\n - If the system has sites with partial occupation and the total occupations of each element do not all sum up to integers, then the Hill formula SHOULD be handled as unset.\n - No spaces or separators are allowed.\n\n- **Examples**:\n - `\"H2O2\"`\n\n- **Query examples**:\n - A filter that matches an exactly given formula is `chemical_formula_hill=\"H2O2\"`.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "chemical_formula_anonymous": { "title": "Chemical Formula Anonymous", @@ -3606,8 +3600,8 @@ "type": "string", "description": "The anonymous formula is the `chemical_formula_reduced`, but where the elements are instead first ordered by their chemical proportion number, and then, in order left to right, replaced by anonymous symbols A, B, C, ..., Z, Aa, Ba, ..., Za, Ab, Bb, ... and so on.\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property.\n However, support for filters using partial string matching with this property is OPTIONAL (i.e., BEGINS WITH, ENDS WITH, and CONTAINS).\n\n- **Examples**:\n - `\"A2B\"`\n - `\"A42B42C16D12E10F9G5\"`\n\n- **Querying**:\n - A filter that matches an exactly given formula is `chemical_formula_anonymous=\"A2B\"`.", "nullable": true, - "x-optimade-queryable": "must", - "x-optimade-support": "should" + "x-optimade-support": "should", + "x-optimade-queryable": "must" }, "dimension_types": { "title": "Dimension Types", @@ -3619,16 +3613,16 @@ }, "description": "List of three integers.\nFor each of the three directions indicated by the three lattice vectors (see property `lattice_vectors`), this list indicates if the direction is periodic (value `1`) or non-periodic (value `0`).\nNote: the elements in this list each refer to the direction of the corresponding entry in `lattice_vectors` and *not* the Cartesian x, y, z directions.\n\n- **Type**: list of integers.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - MUST be a list of length 3.\n - Each integer element MUST assume only the value 0 or 1.\n\n- **Examples**:\n - For a molecule: `[0, 0, 0]`\n - For a wire along the direction specified by the third lattice vector: `[0, 0, 1]`\n - For a 2D surface/slab, periodic on the plane defined by the first and third lattice vectors: `[1, 0, 1]`\n - For a bulk 3D system: `[1, 1, 1]`", "nullable": true, - "x-optimade-queryable": "optional", - "x-optimade-support": "should" + "x-optimade-support": "should", + "x-optimade-queryable": "optional" }, "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 `dimension_types`.\n\n- **Type**: integer\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - The integer value MUST be between 0 and 3 inclusive and MUST be equal to the sum of the items in the `dimension_types` property.\n - This property only reflects the treatment of the lattice vectors provided for the structure, and not any physical interpretation of the dimensionality of its contents.\n\n- **Examples**:\n - `2` should be indicated in cases where `dimension_types` is any of `[1, 1, 0]`, `[1, 0, 1]`, `[0, 1, 1]`.\n\n- **Query examples**:\n - Match only structures with exactly 3 periodic dimensions: `nperiodic_dimensions=3`\n - Match all structures with 2 or fewer periodic dimensions: `nperiodic_dimensions<=2`", "nullable": true, - "x-optimade-queryable": "must", - "x-optimade-support": "should" + "x-optimade-support": "should", + "x-optimade-queryable": "must" }, "lattice_vectors": { "title": "Lattice Vectors", @@ -3645,9 +3639,9 @@ }, "description": "The three lattice vectors in Cartesian coordinates, in \u00e5ngstr\u00f6m (\u00c5).\n\n- **Type**: list of list of floats or unknown values.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - MUST be a list of three vectors *a*, *b*, and *c*, where each of the vectors MUST BE a list of the vector's coordinates along the x, y, and z Cartesian coordinates.\n (Therefore, the first index runs over the three lattice vectors and the second index runs over the x, y, z Cartesian coordinates).\n - For databases that do not define an absolute Cartesian system (e.g., only defining the length and angles between vectors), the first lattice vector SHOULD be set along *x* and the second on the *xy*-plane.\n - MUST always contain three vectors of three coordinates each, independently of the elements of property `dimension_types`.\n The vectors SHOULD by convention be chosen so the determinant of the `lattice_vectors` matrix is different from zero.\n The vectors in the non-periodic directions have no significance beyond fulfilling these requirements.\n - The coordinates of the lattice vectors of non-periodic dimensions (i.e., those dimensions for which `dimension_types` is `0`) MAY be given as a list of all `null` values.\n If a lattice vector contains the value `null`, all coordinates of that lattice vector MUST be `null`.\n\n- **Examples**:\n - `[[4.0,0.0,0.0],[0.0,4.0,0.0],[0.0,1.0,4.0]]` represents a cell, where the first vector is `(4, 0, 0)`, i.e., a vector aligned along the `x` axis of length 4 \u00c5; the second vector is `(0, 4, 0)`; and the third vector is `(0, 1, 4)`.", "nullable": true, - "x-optimade-queryable": "optional", "x-optimade-unit": "\u00c5", - "x-optimade-support": "should" + "x-optimade-support": "should", + "x-optimade-queryable": "optional" }, "cartesian_site_positions": { "title": "Cartesian Site Positions", @@ -3662,17 +3656,17 @@ }, "description": "Cartesian positions of each site in the structure.\nA site is usually used to describe positions of atoms; what atoms can be encountered at a given site is conveyed by the `species_at_sites` property, and the species themselves are described in the `species` property.\n\n- **Type**: list of list of floats\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - It MUST be a list of length equal to the number of sites in the structure, where every element is a list of the three Cartesian coordinates of a site expressed as float values in the unit angstrom (\u00c5).\n - An entry MAY have multiple sites at the same Cartesian position (for a relevant use of this, see e.g., the property `assemblies`).\n\n- **Examples**:\n - `[[0,0,0],[0,0,2]]` indicates a structure with two sites, one sitting at the origin and one along the (positive) *z*-axis, 2 \u00c5 away from the origin.", "nullable": true, - "x-optimade-queryable": "optional", "x-optimade-unit": "\u00c5", - "x-optimade-support": "should" + "x-optimade-support": "should", + "x-optimade-queryable": "optional" }, "nsites": { "title": "Nsites", "type": "integer", "description": "An integer specifying the length of the `cartesian_site_positions` property.\n\n- **Type**: integer\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `42`\n\n- **Query examples**:\n - Match only structures with exactly 4 sites: `nsites=4`\n - Match structures that have between 2 and 7 sites: `nsites>=2 AND nsites<=7`", "nullable": true, - "x-optimade-queryable": "must", - "x-optimade-support": "should" + "x-optimade-support": "should", + "x-optimade-queryable": "must" }, "species": { "title": "Species", @@ -3682,8 +3676,8 @@ }, "description": "A list describing the species of the sites of this structure.\nSpecies can represent pure chemical elements, virtual-crystal atoms representing a statistical occupation of a given site by multiple chemical elements, and/or a location to which there are attached atoms, i.e., atoms whose precise location are unknown beyond that they are attached to that position (frequently used to indicate hydrogen atoms attached to another element, e.g., a carbon with three attached hydrogens might represent a methyl group, -CH3).\n\n- **Type**: list of dictionary with keys:\n - `name`: string (REQUIRED)\n - `chemical_symbols`: list of strings (REQUIRED)\n - `concentration`: list of float (REQUIRED)\n - `attached`: list of strings (REQUIRED)\n - `nattached`: list of integers (OPTIONAL)\n - `mass`: list of floats (OPTIONAL)\n - `original_name`: string (OPTIONAL).\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - Each list member MUST be a dictionary with the following keys:\n - **name**: REQUIRED; gives the name of the species; the **name** value MUST be unique in the `species` list;\n - **chemical_symbols**: REQUIRED; MUST be a list of strings of all chemical elements composing this species.\n Each item of the list MUST be one of the following:\n - a valid chemical-element symbol, or\n - the special value `\"X\"` to represent a non-chemical element, or\n - the special value `\"vacancy\"` to represent that this site has a non-zero probability of having a vacancy (the respective probability is indicated in the `concentration` list, see below).\n\n If any one entry in the `species` list has a `chemical_symbols` list that is longer than 1 element, the correct flag MUST be set in the list `structure_features`.\n\n - **concentration**: REQUIRED; MUST be a list of floats, with same length as `chemical_symbols`.\n The numbers represent the relative concentration of the corresponding chemical symbol in this species.\n The numbers SHOULD sum to one. Cases in which the numbers do not sum to one typically fall only in the following two categories:\n\n - Numerical errors when representing float numbers in fixed precision, e.g. for two chemical symbols with concentrations `1/3` and `2/3`, the concentration might look something like `[0.33333333333, 0.66666666666]`. If the client is aware that the sum is not one because of numerical precision, it can renormalize the values so that the sum is exactly one.\n - Experimental errors in the data present in the database. In this case, it is the responsibility of the client to decide how to process the data.\n\n Note that concentrations are uncorrelated between different sites (even of the same species).\n\n - **attached**: OPTIONAL; if provided MUST be a list of length 1 or more of strings of chemical symbols for the elements attached to this site, or \"X\" for a non-chemical element.\n\n - **nattached**: OPTIONAL; if provided MUST be a list of length 1 or more of integers indicating the number of attached atoms of the kind specified in the value of the `attached` key.\n\n The implementation MUST include either both or none of the `attached` and `nattached` keys, and if they are provided, they MUST be of the same length.\n Furthermore, if they are provided, the `structure_features` property MUST include the string `site_attachments`.\n\n - **mass**: OPTIONAL. If present MUST be a list of floats, with the same length as `chemical_symbols`, providing element masses expressed in a.m.u.\n Elements denoting vacancies MUST have masses equal to 0.\n\n - **original_name**: OPTIONAL. Can be any valid Unicode string, and SHOULD contain (if specified) the name of the species that is used internally in the source database.\n\n Note: With regards to \"source database\", we refer to the immediate source being queried via the OPTIMADE API implementation.\n\n The main use of this field is for source databases that use species names, containing characters that are not allowed (see description of the list property `species_at_sites`).\n\n - For systems that have only species formed by a single chemical symbol, and that have at most one species per chemical symbol, SHOULD use the chemical symbol as species name (e.g., `\"Ti\"` for titanium, `\"O\"` for oxygen, etc.)\n However, note that this is OPTIONAL, and client implementations MUST NOT assume that the key corresponds to a chemical symbol, nor assume that if the species name is a valid chemical symbol, that it represents a species with that chemical symbol.\n This means that a species `{\"name\": \"C\", \"chemical_symbols\": [\"Ti\"], \"concentration\": [1.0]}` is valid and represents a titanium species (and *not* a carbon species).\n - It is NOT RECOMMENDED that a structure includes species that do not have at least one corresponding site.\n\n- **Examples**:\n - `[ {\"name\": \"Ti\", \"chemical_symbols\": [\"Ti\"], \"concentration\": [1.0]} ]`: any site with this species is occupied by a Ti atom.\n - `[ {\"name\": \"Ti\", \"chemical_symbols\": [\"Ti\", \"vacancy\"], \"concentration\": [0.9, 0.1]} ]`: any site with this species is occupied by a Ti atom with 90 % probability, and has a vacancy with 10 % probability.\n - `[ {\"name\": \"BaCa\", \"chemical_symbols\": [\"vacancy\", \"Ba\", \"Ca\"], \"concentration\": [0.05, 0.45, 0.5], \"mass\": [0.0, 137.327, 40.078]} ]`: any site with this species is occupied by a Ba atom with 45 % probability, a Ca atom with 50 % probability, and by a vacancy with 5 % probability. The mass of this site is (on average) 88.5 a.m.u.\n - `[ {\"name\": \"C12\", \"chemical_symbols\": [\"C\"], \"concentration\": [1.0], \"mass\": [12.0]} ]`: any site with this species is occupied by a carbon isotope with mass 12.\n - `[ {\"name\": \"C13\", \"chemical_symbols\": [\"C\"], \"concentration\": [1.0], \"mass\": [13.0]} ]`: any site with this species is occupied by a carbon isotope with mass 13.\n - `[ {\"name\": \"CH3\", \"chemical_symbols\": [\"C\"], \"concentration\": [1.0], \"attached\": [\"H\"], \"nattached\": [3]} ]`: any site with this species is occupied by a methyl group, -CH3, which is represented without specifying precise positions of the hydrogen atoms.", "nullable": true, - "x-optimade-queryable": "optional", - "x-optimade-support": "should" + "x-optimade-support": "should", + "x-optimade-queryable": "optional" }, "species_at_sites": { "title": "Species At Sites", @@ -3693,8 +3687,8 @@ }, "description": "Name of the species at each site (where values for sites are specified with the same order of the property `cartesian_site_positions`).\nThe properties of the species are found in the property `species`.\n\n- **Type**: list of strings.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - MUST have length equal to the number of sites in the structure (first dimension of the list property `cartesian_site_positions`).\n - Each species name mentioned in the `species_at_sites` list MUST be described in the list property `species` (i.e. for each value in the `species_at_sites` list there MUST exist exactly one dictionary in the `species` list with the `name` attribute equal to the corresponding `species_at_sites` value).\n - Each site MUST be associated only to a single species.\n **Note**: However, species can represent mixtures of atoms, and multiple species MAY be defined for the same chemical element.\n This latter case is useful when different atoms of the same type need to be grouped or distinguished, for instance in simulation codes to assign different initial spin states.\n\n- **Examples**:\n - `[\"Ti\",\"O2\"]` indicates that the first site is hosting a species labeled `\"Ti\"` and the second a species labeled `\"O2\"`.\n - `[\"Ac\", \"Ac\", \"Ag\", \"Ir\"]` indicating the first two sites contains the `\"Ac\"` species, while the third and fourth sites contain the `\"Ag\"` and `\"Ir\"` species, respectively.", "nullable": true, - "x-optimade-queryable": "optional", - "x-optimade-support": "should" + "x-optimade-support": "should", + "x-optimade-queryable": "optional" }, "assemblies": { "title": "Assemblies", @@ -3703,8 +3697,8 @@ "$ref": "#/components/schemas/Assembly" }, "description": "A description of groups of sites that are statistically correlated.\n\n- **Type**: list of dictionary with keys:\n - `sites_in_groups`: list of list of integers (REQUIRED)\n - `group_probabilities`: list of floats (REQUIRED)\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - The property SHOULD be `null` for entries that have no partial occupancies.\n - If present, the correct flag MUST be set in the list `structure_features`.\n - Client implementations MUST check its presence (as its presence changes the interpretation of the structure).\n - If present, it MUST be a list of dictionaries, each of which represents an assembly and MUST have the following two keys:\n - **sites_in_groups**: Index of the sites (0-based) that belong to each group for each assembly.\n\n Example: `[[1], [2]]`: two groups, one with the second site, one with the third.\n Example: `[[1,2], [3]]`: one group with the second and third site, one with the fourth.\n\n - **group_probabilities**: Statistical probability of each group. It MUST have the same length as `sites_in_groups`.\n It SHOULD sum to one.\n See below for examples of how to specify the probability of the occurrence of a vacancy.\n The possible reasons for the values not to sum to one are the same as already specified above for the `concentration` of each `species`.\n\n - If a site is not present in any group, it means that it is present with 100 % probability (as if no assembly was specified).\n - A site MUST NOT appear in more than one group.\n\n- **Examples** (for each entry of the assemblies list):\n - `{\"sites_in_groups\": [[0], [1]], \"group_probabilities: [0.3, 0.7]}`: the first site and the second site never occur at the same time in the unit cell.\n Statistically, 30 % of the times the first site is present, while 70 % of the times the second site is present.\n - `{\"sites_in_groups\": [[1,2], [3]], \"group_probabilities: [0.3, 0.7]}`: the second and third site are either present together or not present; they form the first group of atoms for this assembly.\n The second group is formed by the fourth site.\n Sites of the first group (the second and the third) are never present at the same time as the fourth site.\n 30 % of times sites 1 and 2 are present (and site 3 is absent); 70 % of times site 3 is present (and sites 1 and 2 are absent).\n\n- **Notes**:\n - Assemblies are essential to represent, for instance, the situation where an atom can statistically occupy two different positions (sites).\n\n - By defining groups, it is possible to represent, e.g., the case where a functional molecule (and not just one atom) is either present or absent (or the case where it it is present in two conformations)\n\n - Considerations on virtual alloys and on vacancies: In the special case of a virtual alloy, these specifications allow two different, equivalent ways of specifying them.\n For instance, for a site at the origin with 30 % probability of being occupied by Si, 50 % probability of being occupied by Ge, and 20 % of being a vacancy, the following two representations are possible:\n\n - Using a single species:\n ```json\n {\n \"cartesian_site_positions\": [[0,0,0]],\n \"species_at_sites\": [\"SiGe-vac\"],\n \"species\": [\n {\n \"name\": \"SiGe-vac\",\n \"chemical_symbols\": [\"Si\", \"Ge\", \"vacancy\"],\n \"concentration\": [0.3, 0.5, 0.2]\n }\n ]\n // ...\n }\n ```\n\n - Using multiple species and the assemblies:\n ```json\n {\n \"cartesian_site_positions\": [ [0,0,0], [0,0,0], [0,0,0] ],\n \"species_at_sites\": [\"Si\", \"Ge\", \"vac\"],\n \"species\": [\n { \"name\": \"Si\", \"chemical_symbols\": [\"Si\"], \"concentration\": [1.0] },\n { \"name\": \"Ge\", \"chemical_symbols\": [\"Ge\"], \"concentration\": [1.0] },\n { \"name\": \"vac\", \"chemical_symbols\": [\"vacancy\"], \"concentration\": [1.0] }\n ],\n \"assemblies\": [\n {\n \"sites_in_groups\": [ [0], [1], [2] ],\n \"group_probabilities\": [0.3, 0.5, 0.2]\n }\n ]\n // ...\n }\n ```\n\n - It is up to the database provider to decide which representation to use, typically depending on the internal format in which the structure is stored.\n However, given a structure identified by a unique ID, the API implementation MUST always provide the same representation for it.\n\n - The probabilities of occurrence of different assemblies are uncorrelated.\n So, for instance in the following case with two assemblies:\n ```json\n {\n \"assemblies\": [\n {\n \"sites_in_groups\": [ [0], [1] ],\n \"group_probabilities\": [0.2, 0.8],\n },\n {\n \"sites_in_groups\": [ [2], [3] ],\n \"group_probabilities\": [0.3, 0.7]\n }\n ]\n }\n ```\n\n Site 0 is present with a probability of 20 % and site 1 with a probability of 80 %. These two sites are correlated (either site 0 or 1 is present). Similarly, site 2 is present with a probability of 30 % and site 3 with a probability of 70 %.\n These two sites are correlated (either site 2 or 3 is present).\n However, the presence or absence of sites 0 and 1 is not correlated with the presence or absence of sites 2 and 3 (in the specific example, the pair of sites (0, 2) can occur with 0.2*0.3 = 6 % probability; the pair (0, 3) with 0.2*0.7 = 14 % probability; the pair (1, 2) with 0.8*0.3 = 24 % probability; and the pair (1, 3) with 0.8*0.7 = 56 % probability).", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "structure_features": { "title": "Structure Features", @@ -3713,8 +3707,8 @@ "$ref": "#/components/schemas/StructureFeatures" }, "description": "A list of strings that flag which special features are used by the structure.\n\n- **Type**: list of strings\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property.\n Filters on the list MUST support all mandatory HAS-type queries.\n Filter operators for comparisons on the string components MUST support equality, support for other comparison operators are OPTIONAL.\n - MUST be an empty list if no special features are used.\n - MUST be sorted alphabetically.\n - If a special feature listed below is used, the list MUST contain the corresponding string.\n - If a special feature listed below is not used, the list MUST NOT contain the corresponding string.\n - **List of strings used to indicate special structure features**:\n - `disorder`: this flag MUST be present if any one entry in the `species` list has a `chemical_symbols` list that is longer than 1 element.\n - `implicit_atoms`: this flag MUST be present if the structure contains atoms that are not assigned to sites via the property `species_at_sites` (e.g., because their positions are unknown).\n When this flag is present, the properties related to the chemical formula will likely not match the type and count of atoms represented by the `species_at_sites`, `species` and `assemblies` properties.\n - `site_attachments`: this flag MUST be present if any one entry in the `species` list includes `attached` and `nattached`.\n - `assemblies`: this flag MUST be present if the property `assemblies` is present.\n\n- **Examples**: A structure having implicit atoms and using assemblies: `[\"assemblies\", \"implicit_atoms\"]`", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" } }, "description": "This class contains the Field for the attributes used to represent a structure, e.g. unit cell, atoms, positions." diff --git a/openapi/v1.1.0/optimade_index.json b/openapi/v1.1.0/optimade_index.json index 2ab4693..85a1e2b 100644 --- a/openapi/v1.1.0/optimade_index.json +++ b/openapi/v1.1.0/optimade_index.json @@ -2,7 +2,7 @@ "openapi": "3.0.2", "info": { "title": "OPTIMADE API - Index meta-database", - "description": "The [Open Databases Integration for Materials Design (OPTIMADE) consortium](https://www.optimade.org/) aims to make materials databases interoperational by developing a common REST API.\nThis is the \"special\" index meta-database.\n\nThis specification is generated using [`optimade-python-tools`](https://github.com/Materials-Consortia/optimade-python-tools/tree/v0.19.1) v0.19.1.", + "description": "The [Open Databases Integration for Materials Design (OPTIMADE) consortium](https://www.optimade.org/) aims to make materials databases interoperational by developing a common REST API.\nThis is the \"special\" index meta-database.\n\nThis specification is generated using [`optimade-python-tools`](https://github.com/Materials-Consortia/optimade-python-tools/tree/v0.19.5) v0.19.5.", "version": "1.1.0" }, "paths": { @@ -199,10 +199,8 @@ "required": false, "schema": { "title": "Page Number", - "minimum": 1.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`.", - "default": 0 + "description": "RECOMMENDED for use with _page-based_ pagination: using `page_number` and `page_limit` is RECOMMENDED.\nIt is RECOMMENDED that the first page has number 1, i.e., that `page_number` is 1-based.\nExample: Fetch page 2 of up to 50 structures per page: `/structures?page_number=2&page_limit=50`." }, "name": "page_number", "in": "query" @@ -511,15 +509,15 @@ "title": "Id", "type": "string", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "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\"`", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "links": { "title": "Links", @@ -571,16 +569,16 @@ "title": "Immutable Id", "type": "string", "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", - "x-optimade-queryable": "must", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "must" }, "last_modified": { "title": "Last Modified", "type": "string", "description": "Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n - As part of JSON response format: `\"2007-04-05T14:30:20Z\"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)", "format": "date-time", - "x-optimade-queryable": "must", - "x-optimade-support": "should" + "x-optimade-support": "should", + "x-optimade-queryable": "must" } }, "description": "Contains key-value pairs representing the entry's properties." @@ -1120,8 +1118,8 @@ "title": "Id", "type": "string", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "type": { "title": "Type", From aedbbaade2ec8afa2994f6a02d697f2b32675ca1 Mon Sep 17 00:00:00 2001 From: Matthew Evans Date: Thu, 8 Dec 2022 23:44:31 +0000 Subject: [PATCH 3/4] Allow empty chemical formulae through regexp --- openapi/v1.1.0/optimade.json | 276 ++++++++++++++--------------- openapi/v1.1.0/optimade_index.json | 22 +-- 2 files changed, 149 insertions(+), 149 deletions(-) diff --git a/openapi/v1.1.0/optimade.json b/openapi/v1.1.0/optimade.json index 35ad35a..180dce2 100644 --- a/openapi/v1.1.0/optimade.json +++ b/openapi/v1.1.0/optimade.json @@ -2,7 +2,7 @@ "openapi": "3.0.2", "info": { "title": "OPTIMADE API", - "description": "The [Open Databases Integration for Materials Design (OPTIMADE) consortium](https://www.optimade.org/) aims to make materials databases interoperational by developing a common REST API.\n\nThis specification is generated using [`optimade-python-tools`](https://github.com/Materials-Consortia/optimade-python-tools/tree/v0.19.5) v0.19.5.", + "description": "The [Open Databases Integration for Materials Design (OPTIMADE) consortium](https://www.optimade.org/) aims to make materials databases interoperational by developing a common REST API.\n\nThis specification is generated using [`optimade-python-tools`](https://github.com/Materials-Consortia/optimade-python-tools/tree/v0.20.1) v0.20.1.", "version": "1.1.0" }, "paths": { @@ -1353,8 +1353,8 @@ } }, "description": "Index of the sites (0-based) that belong to each group for each assembly.\n\n- **Examples**:\n - `[[1], [2]]`: two groups, one with the second site, one with the third.\n - `[[1,2], [3]]`: one group with the second and third site, one with the fourth.", - "x-optimade-support": "must", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "must" }, "group_probabilities": { "title": "Group Probabilities", @@ -1363,8 +1363,8 @@ "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`.", - "x-optimade-support": "must", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "must" } }, "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)." @@ -1767,15 +1767,15 @@ "title": "Id", "type": "string", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "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\"`", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "links": { "title": "Links", @@ -1827,16 +1827,16 @@ "title": "Immutable Id", "type": "string", "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", - "x-optimade-support": "optional", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "optional" }, "last_modified": { "title": "Last Modified", "type": "string", "description": "Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n - As part of JSON response format: `\"2007-04-05T14:30:20Z\"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)", "format": "date-time", - "x-optimade-support": "should", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "should" } }, "description": "Contains key-value pairs representing the entry's properties." @@ -2235,8 +2235,8 @@ "title": "Id", "type": "string", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "type": { "title": "Type", @@ -2534,22 +2534,22 @@ "title": "Name", "type": "string", "description": "Full name of the person, REQUIRED.", - "x-optimade-support": "must", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "must" }, "firstname": { "title": "Firstname", "type": "string", "description": "First name of the person.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "lastname": { "title": "Lastname", "type": "string", "description": "Last name of the person.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" } }, "description": "A person, i.e., an author, editor or other." @@ -2651,8 +2651,8 @@ "title": "Id", "type": "string", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "type": { "title": "Type", @@ -2660,8 +2660,8 @@ "type": "string", "description": "The name of the type of an entry.\n- **Type**: string.\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - MUST be an existing entry type.\n - The entry of type and ID MUST be returned in response to a request for `//` under the versioned base URL.\n- **Example**: `\"structures\"`", "default": "references", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "links": { "title": "Links", @@ -2707,16 +2707,16 @@ "title": "Immutable Id", "type": "string", "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", - "x-optimade-support": "optional", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "optional" }, "last_modified": { "title": "Last Modified", "type": "string", "description": "Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n - As part of JSON response format: `\"2007-04-05T14:30:20Z\"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)", "format": "date-time", - "x-optimade-support": "should", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "should" }, "authors": { "title": "Authors", @@ -2725,8 +2725,8 @@ "$ref": "#/components/schemas/Person" }, "description": "List of person objects containing the authors of the reference.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "editors": { "title": "Editors", @@ -2735,15 +2735,15 @@ "$ref": "#/components/schemas/Person" }, "description": "List of person objects containing the editors of the reference.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "doi": { "title": "Doi", "type": "string", "description": "The digital object identifier of the reference.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "url": { "title": "Url", @@ -2752,162 +2752,162 @@ "type": "string", "description": "The URL of the reference.", "format": "uri", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "address": { "title": "Address", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "annote": { "title": "Annote", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "booktitle": { "title": "Booktitle", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "chapter": { "title": "Chapter", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "crossref": { "title": "Crossref", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "edition": { "title": "Edition", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "howpublished": { "title": "Howpublished", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "institution": { "title": "Institution", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "journal": { "title": "Journal", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "key": { "title": "Key", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "month": { "title": "Month", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "note": { "title": "Note", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "number": { "title": "Number", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "organization": { "title": "Organization", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "pages": { "title": "Pages", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "publisher": { "title": "Publisher", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "school": { "title": "School", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "series": { "title": "Series", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "title": { "title": "Title", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "bib_type": { "title": "Bib Type", "type": "string", "description": "Type of the reference, corresponding to the **type** property in the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "volume": { "title": "Volume", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "year": { "title": "Year", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" } }, "description": "Model that stores the attributes of a reference.\n\nMany properties match the meaning described in the\n[BibTeX specification](http://bibtexml.sourceforge.net/btxdoc.pdf)." @@ -3329,8 +3329,8 @@ "title": "Name", "type": "string", "description": "Gives the name of the species; the **name** value MUST be unique in the `species` list.", - "x-optimade-support": "must", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "must" }, "chemical_symbols": { "title": "Chemical Symbols", @@ -3339,8 +3339,8 @@ "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 symbol, or\n- the special value `\"X\"` to represent a non-chemical element, or\n- the special value `\"vacancy\"` to represent that this site has a non-zero probability of having a vacancy (the respective probability is indicated in the `concentration` list, see below).\n\nIf any one entry in the `species` list has a `chemical_symbols` list that is longer than 1 element, the correct flag MUST be set in the list `structure_features`.", - "x-optimade-support": "must", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "must" }, "concentration": { "title": "Concentration", @@ -3349,8 +3349,8 @@ "type": "number" }, "description": "MUST be a list of floats, with same length as `chemical_symbols`. The numbers represent the relative concentration of the corresponding chemical symbol in this species. The numbers SHOULD sum to one. Cases in which the numbers do not sum to one typically fall only in the following two categories:\n\n- Numerical errors when representing float numbers in fixed precision, e.g. for two chemical symbols with concentrations `1/3` and `2/3`, the concentration might look something like `[0.33333333333, 0.66666666666]`. If the client is aware that the sum is not one because of numerical precision, it can renormalize the values so that the sum is exactly one.\n- Experimental errors in the data present in the database. In this case, it is the responsibility of the client to decide how to process the data.\n\nNote that concentrations are uncorrelated between different site (even of the same species).", - "x-optimade-support": "must", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "must" }, "mass": { "title": "Mass", @@ -3359,16 +3359,16 @@ "type": "number" }, "description": "If present MUST be a list of floats expressed in a.m.u.\nElements denoting vacancies MUST have masses equal to 0.", + "x-optimade-queryable": "optional", "x-optimade-unit": "a.m.u.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-support": "optional" }, "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.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "attached": { "title": "Attached", @@ -3377,8 +3377,8 @@ "type": "string" }, "description": "If provided MUST be a list of length 1 or more of strings of chemical symbols for the elements attached to this site, or \"X\" for a non-chemical element.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "nattached": { "title": "Nattached", @@ -3387,8 +3387,8 @@ "type": "integer" }, "description": "If provided MUST be a list of length 1 or more of integers indicating the number of attached atoms of the kind specified in the value of the :field:`attached` key.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" } }, "description": "A list describing the species of the sites of this structure.\n\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\": [0.0, 137.327, 40.078]} ]`: any site with this species is occupied by a Ba atom with 45 % probability, a Ca atom with 50 % probability, and by a vacancy with 5 % probability. The mass of this site is (on average) 88.5 a.m.u.\n - `[ {\"name\": \"C12\", \"chemical_symbols\": [\"C\"], \"concentration\": [1.0], \"mass\": [12.0]} ]`: any site with this species is occupied by a carbon isotope with mass 12.\n - `[ {\"name\": \"C13\", \"chemical_symbols\": [\"C\"], \"concentration\": [1.0], \"mass\": [13.0]} ]`: any site with this species is occupied by a carbon isotope with mass 13.\n - `[ {\"name\": \"CH3\", \"chemical_symbols\": [\"C\"], \"concentration\": [1.0], \"attached\": [\"H\"], \"nattached\": [3]} ]`: any site with this species is occupied by a methyl group, -CH3, which is represented without specifying precise positions of the hydrogen atoms." @@ -3457,8 +3457,8 @@ "title": "Id", "type": "string", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "type": { "title": "Type", @@ -3466,8 +3466,8 @@ "type": "string", "description": "The name of the type of an entry.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - MUST be an existing entry type.\n - The entry of type `` and ID `` MUST be returned in response to a request for `//` under the versioned base URL.\n\n- **Examples**:\n - `\"structures\"`", "default": "structures", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "links": { "title": "Links", @@ -3527,8 +3527,8 @@ "title": "Immutable Id", "type": "string", "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", - "x-optimade-support": "optional", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "optional" }, "last_modified": { "title": "Last Modified", @@ -3536,8 +3536,8 @@ "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", "nullable": true, - "x-optimade-support": "should", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "should" }, "elements": { "title": "Elements", @@ -3547,16 +3547,16 @@ }, "description": "The chemical symbols of the different elements present in the structure.\n\n- **Type**: list of strings.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - The strings are the chemical symbols, i.e., either a single uppercase letter or an uppercase letter followed by a number of lowercase letters.\n - The order MUST be alphabetical.\n - MUST refer to the same elements in the same order, and therefore be of the same length, as `elements_ratios`, if the latter is provided.\n - Note: This property SHOULD NOT contain the string \"X\" to indicate non-chemical elements or \"vacancy\" to indicate vacancies (in contrast to the field `chemical_symbols` for the `species` property).\n\n- **Examples**:\n - `[\"Si\"]`\n - `[\"Al\",\"O\",\"Si\"]`\n\n- **Query examples**:\n - A filter that matches all records of structures that contain Si, Al **and** O, and possibly other elements: `elements HAS ALL \"Si\", \"Al\", \"O\"`.\n - To match structures with exactly these three elements, use `elements HAS ALL \"Si\", \"Al\", \"O\" AND elements LENGTH 3`.\n - Note: length queries on this property can be equivalently formulated by filtering on the `nelements`_ property directly.", "nullable": true, - "x-optimade-support": "should", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "should" }, "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 - MUST be equal to the lengths of the list properties `elements` and `elements_ratios`, if they are provided.\n\n- **Examples**:\n - `3`\n\n- **Querying**:\n - Note: queries on this property can equivalently be formulated using `elements LENGTH`.\n - A filter that matches structures that have exactly 4 elements: `nelements=4`.\n - A filter that matches structures that have between 2 and 7 elements: `nelements>=2 AND nelements<=7`.", "nullable": true, - "x-optimade-support": "should", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "should" }, "elements_ratios": { "title": "Elements Ratios", @@ -3566,42 +3566,42 @@ }, "description": "Relative proportions of different elements in the structure.\n\n- **Type**: list of floats\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - Composed by the proportions of elements in the structure as a list of floating point numbers.\n - The sum of the numbers MUST be 1.0 (within floating point accuracy)\n - MUST refer to the same elements in the same order, and therefore be of the same length, as `elements`, if the latter is provided.\n\n- **Examples**:\n - `[1.0]`\n - `[0.3333333333333333, 0.2222222222222222, 0.4444444444444444]`\n\n- **Query examples**:\n - Note: Useful filters can be formulated using the set operator syntax for correlated values.\n However, since the values are floating point values, the use of equality comparisons is generally inadvisable.\n - OPTIONAL: a filter that matches structures where approximately 1/3 of the atoms in the structure are the element Al is: `elements:elements_ratios HAS ALL \"Al\":>0.3333, \"Al\":<0.3334`.", "nullable": true, - "x-optimade-support": "should", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "should" }, "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\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - The chemical formula is given as a string consisting of properly capitalized element symbols followed by integers or decimal numbers, balanced parentheses, square, and curly brackets `(`,`)`, `[`,`]`, `{`, `}`, commas, the `+`, `-`, `:` and `=` symbols. The parentheses are allowed to be followed by a number. Spaces are allowed anywhere except within chemical symbols. The order of elements and any groupings indicated by parentheses or brackets are chosen freely by the API implementation.\n - The string SHOULD be arithmetically consistent with the element ratios in the `chemical_formula_reduced` property.\n - It is RECOMMENDED, but not mandatory, that symbols, parentheses and brackets, if used, are used with the meanings prescribed by [IUPAC's Nomenclature of Organic Chemistry](https://www.qmul.ac.uk/sbcs/iupac/bibliog/blue.html).\n\n- **Examples**:\n - `\"(H2O)2 Na\"`\n - `\"NaCl\"`\n - `\"CaCO3\"`\n - `\"CCaO3\"`\n - `\"(CH3)3N+ - [CH2]2-OH = Me3N+ - CH2 - CH2OH\"`\n\n- **Query examples**:\n - Note: the free-form nature of this property is likely to make queries on it across different databases inconsistent.\n - A filter that matches an exactly given formula: `chemical_formula_descriptive=\"(H2O)2 Na\"`.\n - A filter that does a partial match: `chemical_formula_descriptive CONTAINS \"H2O\"`.", "nullable": true, - "x-optimade-support": "should", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "should" }, "chemical_formula_reduced": { "title": "Chemical Formula Reduced", - "pattern": "^([A-Z][a-z]?([2-9]|[1-9]\\d+)?)+$", + "pattern": "(^$)|^([A-Z][a-z]?([2-9]|[1-9]\\d+)?)+$", "type": "string", "description": "The reduced chemical formula for a structure as a string with element symbols and integer chemical proportion numbers.\nThe proportion number MUST be omitted if it is 1.\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property.\n However, support for filters using partial string matching with this property is OPTIONAL (i.e., BEGINS WITH, ENDS WITH, and CONTAINS).\n Intricate queries on formula components are instead suggested to be formulated using set-type filter operators on the multi valued `elements` and `elements_ratios` properties.\n - Element symbols MUST have proper capitalization (e.g., `\"Si\"`, not `\"SI\"` for \"silicon\").\n - Elements MUST be placed in alphabetical order, followed by their integer chemical proportion number.\n - For structures with no partial occupation, the chemical proportion numbers are the smallest integers for which the chemical proportion is exactly correct.\n - For structures with partial occupation, the chemical proportion numbers are integers that within reasonable approximation indicate the correct chemical proportions. The precise details of how to perform the rounding is chosen by the API implementation.\n - No spaces or separators are allowed.\n\n- **Examples**:\n - `\"H2NaO\"`\n - `\"ClNa\"`\n - `\"CCaO3\"`\n\n- **Query examples**:\n - A filter that matches an exactly given formula is `chemical_formula_reduced=\"H2NaO\"`.", "nullable": true, - "x-optimade-support": "should", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "should" }, "chemical_formula_hill": { "title": "Chemical Formula Hill", - "pattern": "^([A-Z][a-z]?([2-9]|[1-9]\\d+)?)+$", + "pattern": "(^$)|^([A-Z][a-z]?([2-9]|[1-9]\\d+)?)+$", "type": "string", "description": "The chemical formula for a structure in [Hill form](https://dx.doi.org/10.1021/ja02046a005) with element symbols followed by integer chemical proportion numbers. The proportion number MUST be omitted if it is 1.\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, only a subset of the filter features MAY be supported.\n - The overall scale factor of the chemical proportions is chosen such that the resulting values are integers that indicate the most chemically relevant unit of which the system is composed.\n For example, if the structure is a repeating unit cell with four hydrogens and four oxygens that represents two hydroperoxide molecules, `chemical_formula_hill` is `\"H2O2\"` (i.e., not `\"HO\"`, nor `\"H4O4\"`).\n - If the chemical insight needed to ascribe a Hill formula to the system is not present, the property MUST be handled as unset.\n - Element symbols MUST have proper capitalization (e.g., `\"Si\"`, not `\"SI\"` for \"silicon\").\n - Elements MUST be placed in [Hill order](https://dx.doi.org/10.1021/ja02046a005), followed by their integer chemical proportion number.\n Hill order means: if carbon is present, it is placed first, and if also present, hydrogen is placed second.\n After that, all other elements are ordered alphabetically.\n If carbon is not present, all elements are ordered alphabetically.\n - If the system has sites with partial occupation and the total occupations of each element do not all sum up to integers, then the Hill formula SHOULD be handled as unset.\n - No spaces or separators are allowed.\n\n- **Examples**:\n - `\"H2O2\"`\n\n- **Query examples**:\n - A filter that matches an exactly given formula is `chemical_formula_hill=\"H2O2\"`.", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "chemical_formula_anonymous": { "title": "Chemical Formula Anonymous", - "pattern": "^([A-Z][a-z]?([2-9]|[1-9]\\d+)?)+$", + "pattern": "(^$)|^([A-Z][a-z]?([2-9]|[1-9]\\d+)?)+$", "type": "string", "description": "The anonymous formula is the `chemical_formula_reduced`, but where the elements are instead first ordered by their chemical proportion number, and then, in order left to right, replaced by anonymous symbols A, B, C, ..., Z, Aa, Ba, ..., Za, Ab, Bb, ... and so on.\n\n- **Type**: string\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property.\n However, support for filters using partial string matching with this property is OPTIONAL (i.e., BEGINS WITH, ENDS WITH, and CONTAINS).\n\n- **Examples**:\n - `\"A2B\"`\n - `\"A42B42C16D12E10F9G5\"`\n\n- **Querying**:\n - A filter that matches an exactly given formula is `chemical_formula_anonymous=\"A2B\"`.", "nullable": true, - "x-optimade-support": "should", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "should" }, "dimension_types": { "title": "Dimension Types", @@ -3613,16 +3613,16 @@ }, "description": "List of three integers.\nFor each of the three directions indicated by the three lattice vectors (see property `lattice_vectors`), this list indicates if the direction is periodic (value `1`) or non-periodic (value `0`).\nNote: the elements in this list each refer to the direction of the corresponding entry in `lattice_vectors` and *not* the Cartesian x, y, z directions.\n\n- **Type**: list of integers.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - MUST be a list of length 3.\n - Each integer element MUST assume only the value 0 or 1.\n\n- **Examples**:\n - For a molecule: `[0, 0, 0]`\n - For a wire along the direction specified by the third lattice vector: `[0, 0, 1]`\n - For a 2D surface/slab, periodic on the plane defined by the first and third lattice vectors: `[1, 0, 1]`\n - For a bulk 3D system: `[1, 1, 1]`", "nullable": true, - "x-optimade-support": "should", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "should" }, "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 `dimension_types`.\n\n- **Type**: integer\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - The integer value MUST be between 0 and 3 inclusive and MUST be equal to the sum of the items in the `dimension_types` property.\n - This property only reflects the treatment of the lattice vectors provided for the structure, and not any physical interpretation of the dimensionality of its contents.\n\n- **Examples**:\n - `2` should be indicated in cases where `dimension_types` is any of `[1, 1, 0]`, `[1, 0, 1]`, `[0, 1, 1]`.\n\n- **Query examples**:\n - Match only structures with exactly 3 periodic dimensions: `nperiodic_dimensions=3`\n - Match all structures with 2 or fewer periodic dimensions: `nperiodic_dimensions<=2`", "nullable": true, - "x-optimade-support": "should", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "should" }, "lattice_vectors": { "title": "Lattice Vectors", @@ -3639,9 +3639,9 @@ }, "description": "The three lattice vectors in Cartesian coordinates, in \u00e5ngstr\u00f6m (\u00c5).\n\n- **Type**: list of list of floats or unknown values.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - MUST be a list of three vectors *a*, *b*, and *c*, where each of the vectors MUST BE a list of the vector's coordinates along the x, y, and z Cartesian coordinates.\n (Therefore, the first index runs over the three lattice vectors and the second index runs over the x, y, z Cartesian coordinates).\n - For databases that do not define an absolute Cartesian system (e.g., only defining the length and angles between vectors), the first lattice vector SHOULD be set along *x* and the second on the *xy*-plane.\n - MUST always contain three vectors of three coordinates each, independently of the elements of property `dimension_types`.\n The vectors SHOULD by convention be chosen so the determinant of the `lattice_vectors` matrix is different from zero.\n The vectors in the non-periodic directions have no significance beyond fulfilling these requirements.\n - The coordinates of the lattice vectors of non-periodic dimensions (i.e., those dimensions for which `dimension_types` is `0`) MAY be given as a list of all `null` values.\n If a lattice vector contains the value `null`, all coordinates of that lattice vector MUST be `null`.\n\n- **Examples**:\n - `[[4.0,0.0,0.0],[0.0,4.0,0.0],[0.0,1.0,4.0]]` represents a cell, where the first vector is `(4, 0, 0)`, i.e., a vector aligned along the `x` axis of length 4 \u00c5; the second vector is `(0, 4, 0)`; and the third vector is `(0, 1, 4)`.", "nullable": true, + "x-optimade-queryable": "optional", "x-optimade-unit": "\u00c5", - "x-optimade-support": "should", - "x-optimade-queryable": "optional" + "x-optimade-support": "should" }, "cartesian_site_positions": { "title": "Cartesian Site Positions", @@ -3656,17 +3656,17 @@ }, "description": "Cartesian positions of each site in the structure.\nA site is usually used to describe positions of atoms; what atoms can be encountered at a given site is conveyed by the `species_at_sites` property, and the species themselves are described in the `species` property.\n\n- **Type**: list of list of floats\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - It MUST be a list of length equal to the number of sites in the structure, where every element is a list of the three Cartesian coordinates of a site expressed as float values in the unit angstrom (\u00c5).\n - An entry MAY have multiple sites at the same Cartesian position (for a relevant use of this, see e.g., the property `assemblies`).\n\n- **Examples**:\n - `[[0,0,0],[0,0,2]]` indicates a structure with two sites, one sitting at the origin and one along the (positive) *z*-axis, 2 \u00c5 away from the origin.", "nullable": true, + "x-optimade-queryable": "optional", "x-optimade-unit": "\u00c5", - "x-optimade-support": "should", - "x-optimade-queryable": "optional" + "x-optimade-support": "should" }, "nsites": { "title": "Nsites", "type": "integer", "description": "An integer specifying the length of the `cartesian_site_positions` property.\n\n- **Type**: integer\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `42`\n\n- **Query examples**:\n - Match only structures with exactly 4 sites: `nsites=4`\n - Match structures that have between 2 and 7 sites: `nsites>=2 AND nsites<=7`", "nullable": true, - "x-optimade-support": "should", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "should" }, "species": { "title": "Species", @@ -3676,8 +3676,8 @@ }, "description": "A list describing the species of the sites of this structure.\nSpecies can represent pure chemical elements, virtual-crystal atoms representing a statistical occupation of a given site by multiple chemical elements, and/or a location to which there are attached atoms, i.e., atoms whose precise location are unknown beyond that they are attached to that position (frequently used to indicate hydrogen atoms attached to another element, e.g., a carbon with three attached hydrogens might represent a methyl group, -CH3).\n\n- **Type**: list of dictionary with keys:\n - `name`: string (REQUIRED)\n - `chemical_symbols`: list of strings (REQUIRED)\n - `concentration`: list of float (REQUIRED)\n - `attached`: list of strings (REQUIRED)\n - `nattached`: list of integers (OPTIONAL)\n - `mass`: list of floats (OPTIONAL)\n - `original_name`: string (OPTIONAL).\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - Each list member MUST be a dictionary with the following keys:\n - **name**: REQUIRED; gives the name of the species; the **name** value MUST be unique in the `species` list;\n - **chemical_symbols**: REQUIRED; MUST be a list of strings of all chemical elements composing this species.\n Each item of the list MUST be one of the following:\n - a valid chemical-element symbol, or\n - the special value `\"X\"` to represent a non-chemical element, or\n - the special value `\"vacancy\"` to represent that this site has a non-zero probability of having a vacancy (the respective probability is indicated in the `concentration` list, see below).\n\n If any one entry in the `species` list has a `chemical_symbols` list that is longer than 1 element, the correct flag MUST be set in the list `structure_features`.\n\n - **concentration**: REQUIRED; MUST be a list of floats, with same length as `chemical_symbols`.\n The numbers represent the relative concentration of the corresponding chemical symbol in this species.\n The numbers SHOULD sum to one. Cases in which the numbers do not sum to one typically fall only in the following two categories:\n\n - Numerical errors when representing float numbers in fixed precision, e.g. for two chemical symbols with concentrations `1/3` and `2/3`, the concentration might look something like `[0.33333333333, 0.66666666666]`. If the client is aware that the sum is not one because of numerical precision, it can renormalize the values so that the sum is exactly one.\n - Experimental errors in the data present in the database. In this case, it is the responsibility of the client to decide how to process the data.\n\n Note that concentrations are uncorrelated between different sites (even of the same species).\n\n - **attached**: OPTIONAL; if provided MUST be a list of length 1 or more of strings of chemical symbols for the elements attached to this site, or \"X\" for a non-chemical element.\n\n - **nattached**: OPTIONAL; if provided MUST be a list of length 1 or more of integers indicating the number of attached atoms of the kind specified in the value of the `attached` key.\n\n The implementation MUST include either both or none of the `attached` and `nattached` keys, and if they are provided, they MUST be of the same length.\n Furthermore, if they are provided, the `structure_features` property MUST include the string `site_attachments`.\n\n - **mass**: OPTIONAL. If present MUST be a list of floats, with the same length as `chemical_symbols`, providing element masses expressed in a.m.u.\n Elements denoting vacancies MUST have masses equal to 0.\n\n - **original_name**: OPTIONAL. Can be any valid Unicode string, and SHOULD contain (if specified) the name of the species that is used internally in the source database.\n\n Note: With regards to \"source database\", we refer to the immediate source being queried via the OPTIMADE API implementation.\n\n The main use of this field is for source databases that use species names, containing characters that are not allowed (see description of the list property `species_at_sites`).\n\n - For systems that have only species formed by a single chemical symbol, and that have at most one species per chemical symbol, SHOULD use the chemical symbol as species name (e.g., `\"Ti\"` for titanium, `\"O\"` for oxygen, etc.)\n However, note that this is OPTIONAL, and client implementations MUST NOT assume that the key corresponds to a chemical symbol, nor assume that if the species name is a valid chemical symbol, that it represents a species with that chemical symbol.\n This means that a species `{\"name\": \"C\", \"chemical_symbols\": [\"Ti\"], \"concentration\": [1.0]}` is valid and represents a titanium species (and *not* a carbon species).\n - It is NOT RECOMMENDED that a structure includes species that do not have at least one corresponding site.\n\n- **Examples**:\n - `[ {\"name\": \"Ti\", \"chemical_symbols\": [\"Ti\"], \"concentration\": [1.0]} ]`: any site with this species is occupied by a Ti atom.\n - `[ {\"name\": \"Ti\", \"chemical_symbols\": [\"Ti\", \"vacancy\"], \"concentration\": [0.9, 0.1]} ]`: any site with this species is occupied by a Ti atom with 90 % probability, and has a vacancy with 10 % probability.\n - `[ {\"name\": \"BaCa\", \"chemical_symbols\": [\"vacancy\", \"Ba\", \"Ca\"], \"concentration\": [0.05, 0.45, 0.5], \"mass\": [0.0, 137.327, 40.078]} ]`: any site with this species is occupied by a Ba atom with 45 % probability, a Ca atom with 50 % probability, and by a vacancy with 5 % probability. The mass of this site is (on average) 88.5 a.m.u.\n - `[ {\"name\": \"C12\", \"chemical_symbols\": [\"C\"], \"concentration\": [1.0], \"mass\": [12.0]} ]`: any site with this species is occupied by a carbon isotope with mass 12.\n - `[ {\"name\": \"C13\", \"chemical_symbols\": [\"C\"], \"concentration\": [1.0], \"mass\": [13.0]} ]`: any site with this species is occupied by a carbon isotope with mass 13.\n - `[ {\"name\": \"CH3\", \"chemical_symbols\": [\"C\"], \"concentration\": [1.0], \"attached\": [\"H\"], \"nattached\": [3]} ]`: any site with this species is occupied by a methyl group, -CH3, which is represented without specifying precise positions of the hydrogen atoms.", "nullable": true, - "x-optimade-support": "should", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "should" }, "species_at_sites": { "title": "Species At Sites", @@ -3687,8 +3687,8 @@ }, "description": "Name of the species at each site (where values for sites are specified with the same order of the property `cartesian_site_positions`).\nThe properties of the species are found in the property `species`.\n\n- **Type**: list of strings.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - MUST have length equal to the number of sites in the structure (first dimension of the list property `cartesian_site_positions`).\n - Each species name mentioned in the `species_at_sites` list MUST be described in the list property `species` (i.e. for each value in the `species_at_sites` list there MUST exist exactly one dictionary in the `species` list with the `name` attribute equal to the corresponding `species_at_sites` value).\n - Each site MUST be associated only to a single species.\n **Note**: However, species can represent mixtures of atoms, and multiple species MAY be defined for the same chemical element.\n This latter case is useful when different atoms of the same type need to be grouped or distinguished, for instance in simulation codes to assign different initial spin states.\n\n- **Examples**:\n - `[\"Ti\",\"O2\"]` indicates that the first site is hosting a species labeled `\"Ti\"` and the second a species labeled `\"O2\"`.\n - `[\"Ac\", \"Ac\", \"Ag\", \"Ir\"]` indicating the first two sites contains the `\"Ac\"` species, while the third and fourth sites contain the `\"Ag\"` and `\"Ir\"` species, respectively.", "nullable": true, - "x-optimade-support": "should", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "should" }, "assemblies": { "title": "Assemblies", @@ -3697,8 +3697,8 @@ "$ref": "#/components/schemas/Assembly" }, "description": "A description of groups of sites that are statistically correlated.\n\n- **Type**: list of dictionary with keys:\n - `sites_in_groups`: list of list of integers (REQUIRED)\n - `group_probabilities`: list of floats (REQUIRED)\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - The property SHOULD be `null` for entries that have no partial occupancies.\n - If present, the correct flag MUST be set in the list `structure_features`.\n - Client implementations MUST check its presence (as its presence changes the interpretation of the structure).\n - If present, it MUST be a list of dictionaries, each of which represents an assembly and MUST have the following two keys:\n - **sites_in_groups**: Index of the sites (0-based) that belong to each group for each assembly.\n\n Example: `[[1], [2]]`: two groups, one with the second site, one with the third.\n Example: `[[1,2], [3]]`: one group with the second and third site, one with the fourth.\n\n - **group_probabilities**: Statistical probability of each group. It MUST have the same length as `sites_in_groups`.\n It SHOULD sum to one.\n See below for examples of how to specify the probability of the occurrence of a vacancy.\n The possible reasons for the values not to sum to one are the same as already specified above for the `concentration` of each `species`.\n\n - If a site is not present in any group, it means that it is present with 100 % probability (as if no assembly was specified).\n - A site MUST NOT appear in more than one group.\n\n- **Examples** (for each entry of the assemblies list):\n - `{\"sites_in_groups\": [[0], [1]], \"group_probabilities: [0.3, 0.7]}`: the first site and the second site never occur at the same time in the unit cell.\n Statistically, 30 % of the times the first site is present, while 70 % of the times the second site is present.\n - `{\"sites_in_groups\": [[1,2], [3]], \"group_probabilities: [0.3, 0.7]}`: the second and third site are either present together or not present; they form the first group of atoms for this assembly.\n The second group is formed by the fourth site.\n Sites of the first group (the second and the third) are never present at the same time as the fourth site.\n 30 % of times sites 1 and 2 are present (and site 3 is absent); 70 % of times site 3 is present (and sites 1 and 2 are absent).\n\n- **Notes**:\n - Assemblies are essential to represent, for instance, the situation where an atom can statistically occupy two different positions (sites).\n\n - By defining groups, it is possible to represent, e.g., the case where a functional molecule (and not just one atom) is either present or absent (or the case where it it is present in two conformations)\n\n - Considerations on virtual alloys and on vacancies: In the special case of a virtual alloy, these specifications allow two different, equivalent ways of specifying them.\n For instance, for a site at the origin with 30 % probability of being occupied by Si, 50 % probability of being occupied by Ge, and 20 % of being a vacancy, the following two representations are possible:\n\n - Using a single species:\n ```json\n {\n \"cartesian_site_positions\": [[0,0,0]],\n \"species_at_sites\": [\"SiGe-vac\"],\n \"species\": [\n {\n \"name\": \"SiGe-vac\",\n \"chemical_symbols\": [\"Si\", \"Ge\", \"vacancy\"],\n \"concentration\": [0.3, 0.5, 0.2]\n }\n ]\n // ...\n }\n ```\n\n - Using multiple species and the assemblies:\n ```json\n {\n \"cartesian_site_positions\": [ [0,0,0], [0,0,0], [0,0,0] ],\n \"species_at_sites\": [\"Si\", \"Ge\", \"vac\"],\n \"species\": [\n { \"name\": \"Si\", \"chemical_symbols\": [\"Si\"], \"concentration\": [1.0] },\n { \"name\": \"Ge\", \"chemical_symbols\": [\"Ge\"], \"concentration\": [1.0] },\n { \"name\": \"vac\", \"chemical_symbols\": [\"vacancy\"], \"concentration\": [1.0] }\n ],\n \"assemblies\": [\n {\n \"sites_in_groups\": [ [0], [1], [2] ],\n \"group_probabilities\": [0.3, 0.5, 0.2]\n }\n ]\n // ...\n }\n ```\n\n - It is up to the database provider to decide which representation to use, typically depending on the internal format in which the structure is stored.\n However, given a structure identified by a unique ID, the API implementation MUST always provide the same representation for it.\n\n - The probabilities of occurrence of different assemblies are uncorrelated.\n So, for instance in the following case with two assemblies:\n ```json\n {\n \"assemblies\": [\n {\n \"sites_in_groups\": [ [0], [1] ],\n \"group_probabilities\": [0.2, 0.8],\n },\n {\n \"sites_in_groups\": [ [2], [3] ],\n \"group_probabilities\": [0.3, 0.7]\n }\n ]\n }\n ```\n\n Site 0 is present with a probability of 20 % and site 1 with a probability of 80 %. These two sites are correlated (either site 0 or 1 is present). Similarly, site 2 is present with a probability of 30 % and site 3 with a probability of 70 %.\n These two sites are correlated (either site 2 or 3 is present).\n However, the presence or absence of sites 0 and 1 is not correlated with the presence or absence of sites 2 and 3 (in the specific example, the pair of sites (0, 2) can occur with 0.2*0.3 = 6 % probability; the pair (0, 3) with 0.2*0.7 = 14 % probability; the pair (1, 2) with 0.8*0.3 = 24 % probability; and the pair (1, 3) with 0.8*0.7 = 56 % probability).", - "x-optimade-support": "optional", - "x-optimade-queryable": "optional" + "x-optimade-queryable": "optional", + "x-optimade-support": "optional" }, "structure_features": { "title": "Structure Features", @@ -3707,8 +3707,8 @@ "$ref": "#/components/schemas/StructureFeatures" }, "description": "A list of strings that flag which special features are used by the structure.\n\n- **Type**: list of strings\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property.\n Filters on the list MUST support all mandatory HAS-type queries.\n Filter operators for comparisons on the string components MUST support equality, support for other comparison operators are OPTIONAL.\n - MUST be an empty list if no special features are used.\n - MUST be sorted alphabetically.\n - If a special feature listed below is used, the list MUST contain the corresponding string.\n - If a special feature listed below is not used, the list MUST NOT contain the corresponding string.\n - **List of strings used to indicate special structure features**:\n - `disorder`: this flag MUST be present if any one entry in the `species` list has a `chemical_symbols` list that is longer than 1 element.\n - `implicit_atoms`: this flag MUST be present if the structure contains atoms that are not assigned to sites via the property `species_at_sites` (e.g., because their positions are unknown).\n When this flag is present, the properties related to the chemical formula will likely not match the type and count of atoms represented by the `species_at_sites`, `species` and `assemblies` properties.\n - `site_attachments`: this flag MUST be present if any one entry in the `species` list includes `attached` and `nattached`.\n - `assemblies`: this flag MUST be present if the property `assemblies` is present.\n\n- **Examples**: A structure having implicit atoms and using assemblies: `[\"assemblies\", \"implicit_atoms\"]`", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" } }, "description": "This class contains the Field for the attributes used to represent a structure, e.g. unit cell, atoms, positions." diff --git a/openapi/v1.1.0/optimade_index.json b/openapi/v1.1.0/optimade_index.json index 85a1e2b..38b8830 100644 --- a/openapi/v1.1.0/optimade_index.json +++ b/openapi/v1.1.0/optimade_index.json @@ -2,7 +2,7 @@ "openapi": "3.0.2", "info": { "title": "OPTIMADE API - Index meta-database", - "description": "The [Open Databases Integration for Materials Design (OPTIMADE) consortium](https://www.optimade.org/) aims to make materials databases interoperational by developing a common REST API.\nThis is the \"special\" index meta-database.\n\nThis specification is generated using [`optimade-python-tools`](https://github.com/Materials-Consortia/optimade-python-tools/tree/v0.19.5) v0.19.5.", + "description": "The [Open Databases Integration for Materials Design (OPTIMADE) consortium](https://www.optimade.org/) aims to make materials databases interoperational by developing a common REST API.\nThis is the \"special\" index meta-database.\n\nThis specification is generated using [`optimade-python-tools`](https://github.com/Materials-Consortia/optimade-python-tools/tree/v0.20.1) v0.20.1.", "version": "1.1.0" }, "paths": { @@ -509,15 +509,15 @@ "title": "Id", "type": "string", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "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\"`", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "links": { "title": "Links", @@ -569,16 +569,16 @@ "title": "Immutable Id", "type": "string", "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", - "x-optimade-support": "optional", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "optional" }, "last_modified": { "title": "Last Modified", "type": "string", "description": "Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n - As part of JSON response format: `\"2007-04-05T14:30:20Z\"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)", "format": "date-time", - "x-optimade-support": "should", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "should" } }, "description": "Contains key-value pairs representing the entry's properties." @@ -1118,8 +1118,8 @@ "title": "Id", "type": "string", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-support": "must", - "x-optimade-queryable": "must" + "x-optimade-queryable": "must", + "x-optimade-support": "must" }, "type": { "title": "Type", From ff30d577b1199796ecf0e12da0dc6bf0f1d6f5b3 Mon Sep 17 00:00:00 2001 From: Matthew Evans Date: Fri, 3 Mar 2023 18:20:06 +0100 Subject: [PATCH 4/4] Add `page_above`/`page_below` fixes from optimade-python-tools v0.22 --- openapi/v1.1.0/optimade.json | 196 ++++++++++++++--------------- openapi/v1.1.0/optimade_index.json | 30 ++--- 2 files changed, 105 insertions(+), 121 deletions(-) diff --git a/openapi/v1.1.0/optimade.json b/openapi/v1.1.0/optimade.json index 180dce2..0911bfb 100644 --- a/openapi/v1.1.0/optimade.json +++ b/openapi/v1.1.0/optimade.json @@ -2,7 +2,7 @@ "openapi": "3.0.2", "info": { "title": "OPTIMADE API", - "description": "The [Open Databases Integration for Materials Design (OPTIMADE) consortium](https://www.optimade.org/) aims to make materials databases interoperational by developing a common REST API.\n\nThis specification is generated using [`optimade-python-tools`](https://github.com/Materials-Consortia/optimade-python-tools/tree/v0.20.1) v0.20.1.", + "description": "The [Open Databases Integration for Materials Design (OPTIMADE) consortium](https://www.optimade.org/) aims to make materials databases interoperational by developing a common REST API.\n\nThis specification is generated using [`optimade-python-tools`](https://github.com/Materials-Consortia/optimade-python-tools/tree/v0.22.1) v0.22.1.", "version": "1.1.0" }, "paths": { @@ -325,10 +325,8 @@ "required": false, "schema": { "title": "Page Above", - "minimum": 0.0, - "type": "integer", - "description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.\nExample: Fetch up to 100 structures above sort-field value 4000 (in this example, server chooses to fetch results sorted by increasing `id`, so `page_above` value refers to an `id` value): `/structures?page_above=4000&page_limit=100`.", - "default": 0 + "type": "string", + "description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.\nExample: Fetch up to 100 structures above sort-field value 4000 (in this example, server chooses to fetch results sorted by increasing `id`, so `page_above` value refers to an `id` value): `/structures?page_above=4000&page_limit=100`." }, "name": "page_above", "in": "query" @@ -338,10 +336,8 @@ "required": false, "schema": { "title": "Page Below", - "minimum": 0.0, - "type": "integer", - "description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.", - "default": 0 + "type": "string", + "description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED." }, "name": "page_below", "in": "query" @@ -582,10 +578,8 @@ "required": false, "schema": { "title": "Page Above", - "minimum": 0.0, - "type": "integer", - "description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.\nExample: Fetch up to 100 structures above sort-field value 4000 (in this example, server chooses to fetch results sorted by increasing `id`, so `page_above` value refers to an `id` value): `/structures?page_above=4000&page_limit=100`.", - "default": 0 + "type": "string", + "description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.\nExample: Fetch up to 100 structures above sort-field value 4000 (in this example, server chooses to fetch results sorted by increasing `id`, so `page_above` value refers to an `id` value): `/structures?page_above=4000&page_limit=100`." }, "name": "page_above", "in": "query" @@ -595,10 +589,8 @@ "required": false, "schema": { "title": "Page Below", - "minimum": 0.0, - "type": "integer", - "description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.", - "default": 0 + "type": "string", + "description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED." }, "name": "page_below", "in": "query" @@ -1004,10 +996,8 @@ "required": false, "schema": { "title": "Page Above", - "minimum": 0.0, - "type": "integer", - "description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.\nExample: Fetch up to 100 structures above sort-field value 4000 (in this example, server chooses to fetch results sorted by increasing `id`, so `page_above` value refers to an `id` value): `/structures?page_above=4000&page_limit=100`.", - "default": 0 + "type": "string", + "description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.\nExample: Fetch up to 100 structures above sort-field value 4000 (in this example, server chooses to fetch results sorted by increasing `id`, so `page_above` value refers to an `id` value): `/structures?page_above=4000&page_limit=100`." }, "name": "page_above", "in": "query" @@ -1017,10 +1007,8 @@ "required": false, "schema": { "title": "Page Below", - "minimum": 0.0, - "type": "integer", - "description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.", - "default": 0 + "type": "string", + "description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED." }, "name": "page_below", "in": "query" @@ -1585,7 +1573,7 @@ "dictionary", "unknown" ], - "description": "Optimade Data Types\n\n See the section \"Data types\" in the OPTIMADE API specification for more information.\n " + "description": "Optimade Data Types\n\nSee the section \"Data types\" in the OPTIMADE API specification for more information." }, "EntryInfoProperty": { "title": "EntryInfoProperty", @@ -1767,15 +1755,15 @@ "title": "Id", "type": "string", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "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\"`", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "links": { "title": "Links", @@ -1827,8 +1815,8 @@ "title": "Immutable Id", "type": "string", "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", - "x-optimade-queryable": "must", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "must" }, "last_modified": { "title": "Last Modified", @@ -2235,8 +2223,8 @@ "title": "Id", "type": "string", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "type": { "title": "Type", @@ -2534,22 +2522,22 @@ "title": "Name", "type": "string", "description": "Full name of the person, REQUIRED.", - "x-optimade-queryable": "optional", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "optional" }, "firstname": { "title": "Firstname", "type": "string", "description": "First name of the person.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "lastname": { "title": "Lastname", "type": "string", "description": "Last name of the person.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" } }, "description": "A person, i.e., an author, editor or other." @@ -2651,8 +2639,8 @@ "title": "Id", "type": "string", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "type": { "title": "Type", @@ -2707,8 +2695,8 @@ "title": "Immutable Id", "type": "string", "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", - "x-optimade-queryable": "must", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "must" }, "last_modified": { "title": "Last Modified", @@ -2742,8 +2730,8 @@ "title": "Doi", "type": "string", "description": "The digital object identifier of the reference.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "url": { "title": "Url", @@ -2759,155 +2747,155 @@ "title": "Address", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "annote": { "title": "Annote", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "booktitle": { "title": "Booktitle", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "chapter": { "title": "Chapter", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "crossref": { "title": "Crossref", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "edition": { "title": "Edition", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "howpublished": { "title": "Howpublished", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "institution": { "title": "Institution", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "journal": { "title": "Journal", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "key": { "title": "Key", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "month": { "title": "Month", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "note": { "title": "Note", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "number": { "title": "Number", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "organization": { "title": "Organization", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "pages": { "title": "Pages", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "publisher": { "title": "Publisher", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "school": { "title": "School", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "series": { "title": "Series", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "title": { "title": "Title", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "bib_type": { "title": "Bib Type", "type": "string", "description": "Type of the reference, corresponding to the **type** property in the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "volume": { "title": "Volume", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "year": { "title": "Year", "type": "string", "description": "Meaning of property matches the BiBTeX specification.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" } }, "description": "Model that stores the attributes of a reference.\n\nMany properties match the meaning described in the\n[BibTeX specification](http://bibtexml.sourceforge.net/btxdoc.pdf)." @@ -3329,8 +3317,8 @@ "title": "Name", "type": "string", "description": "Gives the name of the species; the **name** value MUST be unique in the `species` list.", - "x-optimade-queryable": "optional", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "optional" }, "chemical_symbols": { "title": "Chemical Symbols", @@ -3360,15 +3348,15 @@ }, "description": "If present MUST be a list of floats expressed in a.m.u.\nElements denoting vacancies MUST have masses equal to 0.", "x-optimade-queryable": "optional", - "x-optimade-unit": "a.m.u.", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-unit": "a.m.u." }, "original_name": { "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.", - "x-optimade-queryable": "optional", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "optional" }, "attached": { "title": "Attached", @@ -3457,8 +3445,8 @@ "title": "Id", "type": "string", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "type": { "title": "Type", @@ -3527,8 +3515,8 @@ "title": "Immutable Id", "type": "string", "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", - "x-optimade-queryable": "must", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "must" }, "last_modified": { "title": "Last Modified", @@ -3640,8 +3628,8 @@ "description": "The three lattice vectors in Cartesian coordinates, in \u00e5ngstr\u00f6m (\u00c5).\n\n- **Type**: list of list of floats or unknown values.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - MUST be a list of three vectors *a*, *b*, and *c*, where each of the vectors MUST BE a list of the vector's coordinates along the x, y, and z Cartesian coordinates.\n (Therefore, the first index runs over the three lattice vectors and the second index runs over the x, y, z Cartesian coordinates).\n - For databases that do not define an absolute Cartesian system (e.g., only defining the length and angles between vectors), the first lattice vector SHOULD be set along *x* and the second on the *xy*-plane.\n - MUST always contain three vectors of three coordinates each, independently of the elements of property `dimension_types`.\n The vectors SHOULD by convention be chosen so the determinant of the `lattice_vectors` matrix is different from zero.\n The vectors in the non-periodic directions have no significance beyond fulfilling these requirements.\n - The coordinates of the lattice vectors of non-periodic dimensions (i.e., those dimensions for which `dimension_types` is `0`) MAY be given as a list of all `null` values.\n If a lattice vector contains the value `null`, all coordinates of that lattice vector MUST be `null`.\n\n- **Examples**:\n - `[[4.0,0.0,0.0],[0.0,4.0,0.0],[0.0,1.0,4.0]]` represents a cell, where the first vector is `(4, 0, 0)`, i.e., a vector aligned along the `x` axis of length 4 \u00c5; the second vector is `(0, 4, 0)`; and the third vector is `(0, 1, 4)`.", "nullable": true, "x-optimade-queryable": "optional", - "x-optimade-unit": "\u00c5", - "x-optimade-support": "should" + "x-optimade-support": "should", + "x-optimade-unit": "\u00c5" }, "cartesian_site_positions": { "title": "Cartesian Site Positions", @@ -3657,8 +3645,8 @@ "description": "Cartesian positions of each site in the structure.\nA site is usually used to describe positions of atoms; what atoms can be encountered at a given site is conveyed by the `species_at_sites` property, and the species themselves are described in the `species` property.\n\n- **Type**: list of list of floats\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n If supported, filters MAY support only a subset of comparison operators.\n - It MUST be a list of length equal to the number of sites in the structure, where every element is a list of the three Cartesian coordinates of a site expressed as float values in the unit angstrom (\u00c5).\n - An entry MAY have multiple sites at the same Cartesian position (for a relevant use of this, see e.g., the property `assemblies`).\n\n- **Examples**:\n - `[[0,0,0],[0,0,2]]` indicates a structure with two sites, one sitting at the origin and one along the (positive) *z*-axis, 2 \u00c5 away from the origin.", "nullable": true, "x-optimade-queryable": "optional", - "x-optimade-unit": "\u00c5", - "x-optimade-support": "should" + "x-optimade-support": "should", + "x-optimade-unit": "\u00c5" }, "nsites": { "title": "Nsites", diff --git a/openapi/v1.1.0/optimade_index.json b/openapi/v1.1.0/optimade_index.json index 38b8830..265b139 100644 --- a/openapi/v1.1.0/optimade_index.json +++ b/openapi/v1.1.0/optimade_index.json @@ -2,7 +2,7 @@ "openapi": "3.0.2", "info": { "title": "OPTIMADE API - Index meta-database", - "description": "The [Open Databases Integration for Materials Design (OPTIMADE) consortium](https://www.optimade.org/) aims to make materials databases interoperational by developing a common REST API.\nThis is the \"special\" index meta-database.\n\nThis specification is generated using [`optimade-python-tools`](https://github.com/Materials-Consortia/optimade-python-tools/tree/v0.20.1) v0.20.1.", + "description": "The [Open Databases Integration for Materials Design (OPTIMADE) consortium](https://www.optimade.org/) aims to make materials databases interoperational by developing a common REST API.\nThis is the \"special\" index meta-database.\n\nThis specification is generated using [`optimade-python-tools`](https://github.com/Materials-Consortia/optimade-python-tools/tree/v0.22.1) v0.22.1.", "version": "1.1.0" }, "paths": { @@ -223,10 +223,8 @@ "required": false, "schema": { "title": "Page Above", - "minimum": 0.0, - "type": "integer", - "description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.\nExample: Fetch up to 100 structures above sort-field value 4000 (in this example, server chooses to fetch results sorted by increasing `id`, so `page_above` value refers to an `id` value): `/structures?page_above=4000&page_limit=100`.", - "default": 0 + "type": "string", + "description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.\nExample: Fetch up to 100 structures above sort-field value 4000 (in this example, server chooses to fetch results sorted by increasing `id`, so `page_above` value refers to an `id` value): `/structures?page_above=4000&page_limit=100`." }, "name": "page_above", "in": "query" @@ -236,10 +234,8 @@ "required": false, "schema": { "title": "Page Below", - "minimum": 0.0, - "type": "integer", - "description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.", - "default": 0 + "type": "string", + "description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED." }, "name": "page_below", "in": "query" @@ -509,15 +505,15 @@ "title": "Id", "type": "string", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "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\"`", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "links": { "title": "Links", @@ -569,8 +565,8 @@ "title": "Immutable Id", "type": "string", "description": "The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to \"the latest version\" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `\"8bd3e750-b477-41a0-9b11-3a799f21b44f\"`\n - `\"fjeiwoj,54;@=%<>#32\"` (Strings that are not URL-safe are allowed.)", - "x-optimade-queryable": "must", - "x-optimade-support": "optional" + "x-optimade-support": "optional", + "x-optimade-queryable": "must" }, "last_modified": { "title": "Last Modified", @@ -1118,8 +1114,8 @@ "title": "Id", "type": "string", "description": "An entry's ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `\"db/1234567\"`\n - `\"cod/2000000\"`\n - `\"cod/2000000@1234567\"`\n - `\"nomad/L1234567890\"`\n - `\"42\"`", - "x-optimade-queryable": "must", - "x-optimade-support": "must" + "x-optimade-support": "must", + "x-optimade-queryable": "must" }, "type": { "title": "Type",