From 9303373337bed01996035300c4b9883b9fafe7db Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Mon, 20 Feb 2023 12:59:38 +0100 Subject: [PATCH 01/11] Adjust handling of unknown properties for better future-proof behavior. --- optimade.rst | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/optimade.rst b/optimade.rst index 8c9d5562c..b37e72a09 100644 --- a/optimade.rst +++ b/optimade.rst @@ -426,17 +426,16 @@ In particular, filters with :filter-fragment:`IS UNKNOWN` and :filter-fragment:` Handling unknown property names ------------------------------- -When an implementation receives a request with a query filter that refers to an unknown property name it is handled differently depending on the database-specific prefix: - -* If the property name has no database-specific prefix, or if it has the database-specific prefix that belongs to the implementation itself, the error :http-error:`400 Bad Request` MUST be returned with a message indicating the offending property name. - -* If the property name has a database-specific prefix that does *not* belong to the implementation itself, it MUST NOT treat this as an error, but rather MUST evaluate the query with the property treated as unknown, i.e., comparisons are evaluated as if the property has the value :val:`null`. - - * Furthermore, if the implementation does not recognize the prefix at all, it SHOULD return a warning that indicates that the property has been handled as unknown. +When an implementation receives a request with a query filter that refers to an unknown property name, it MUST NOT treat this as an error. +Instead, it should evaluate the query with the property treated as unknown, meaning comparisons are evaluated as if the property has the value :val:`null`. +Furthermore: - * On the other hand, if the prefix is recognized, i.e., as belonging to a known database provider, the implementation SHOULD NOT issue a warning but MAY issue diagnostic output with a note explaining how the request was handled. +* If the property does not have a database-specific prefix, the implementation MUST issue a warning about the unrecognized property name. +* If the property has a database-specific prefix that the implementation does not recognize, it SHOULD return a warning indicating that the property has been handled as unknown. +* If the property has a recognized prefix, i.e., it belongs to a known database provider, the implementation SHOULD NOT issue a warning but may issue diagnostic output with a note explaining how the request was handled. -The rationale for treating properties from other databases as unknown rather than triggering an error is for OPTIMADE to support queries using database-specific properties that can be sent to multiple databases. +The rationale for not triggering errors in the above situations is to enable clients to perform queries that reference properties defined in future versions of the OPTIMADE standard or database-specific properties, and have them handled only by the databases that recognize them. +Database-specific properties (as well as properties defined in future versions of this standard) SHOULD be defined in such a way that treating them as :val:`null` in comparisons is a reasonable behavior for a provider that do not support the property. For example, the following query can be sent to API implementations `exmpl1` and `exmpl2` without generating any errors: From 8ed4ab95b2a0b0e68d760806016092a17f1fe7a5 Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Mon, 20 Feb 2023 13:57:00 +0100 Subject: [PATCH 02/11] Adjust grammar Co-authored-by: Antanas Vaitkus --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index b37e72a09..8750b2bf4 100644 --- a/optimade.rst +++ b/optimade.rst @@ -435,7 +435,7 @@ Furthermore: * If the property has a recognized prefix, i.e., it belongs to a known database provider, the implementation SHOULD NOT issue a warning but may issue diagnostic output with a note explaining how the request was handled. The rationale for not triggering errors in the above situations is to enable clients to perform queries that reference properties defined in future versions of the OPTIMADE standard or database-specific properties, and have them handled only by the databases that recognize them. -Database-specific properties (as well as properties defined in future versions of this standard) SHOULD be defined in such a way that treating them as :val:`null` in comparisons is a reasonable behavior for a provider that do not support the property. +Database-specific properties (as well as properties defined in future versions of this standard) SHOULD be defined in such a way that treating them as :val:`null` in comparisons is a reasonable behavior for providers that do not support the property. For example, the following query can be sent to API implementations `exmpl1` and `exmpl2` without generating any errors: From 1657e4cb47c50ad987e6a1aa43239d92c83b65d9 Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Mon, 27 Feb 2023 17:50:04 +0100 Subject: [PATCH 03/11] Handle forwards-compatibility also for response_field query parameter. --- optimade.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/optimade.rst b/optimade.rst index 8750b2bf4..9bf059916 100644 --- a/optimade.rst +++ b/optimade.rst @@ -426,8 +426,9 @@ In particular, filters with :filter-fragment:`IS UNKNOWN` and :filter-fragment:` Handling unknown property names ------------------------------- -When an implementation receives a request with a query filter that refers to an unknown property name, it MUST NOT treat this as an error. -Instead, it should evaluate the query with the property treated as unknown, meaning comparisons are evaluated as if the property has the value :val:`null`. +When an implementation receives a request with a query filter or other mechanism (e.g., :query-param:`response_fields`) that refers to an unknown property name, it MUST NOT treat this as an error. +Instead, it should evaluate queries with the property treated as unknown, meaning comparisons are evaluated as if the property has the value :val:`null`. +If the unknown property is requested to be included in the response, it MUST be included with `null` value. Furthermore: * If the property does not have a database-specific prefix, the implementation MUST issue a warning about the unrecognized property name. From 1fc0df234c3a3119e53dea3230f1bdc8c95ce840 Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Tue, 28 Feb 2023 14:53:32 +0100 Subject: [PATCH 04/11] Further improve forwards-compatibility with future additions --- optimade.rst | 28 +++++++++++++++++----------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/optimade.rst b/optimade.rst index 64d810183..0db35f794 100644 --- a/optimade.rst +++ b/optimade.rst @@ -423,20 +423,17 @@ OPTIONAL properties with an unknown value, if requested explicitly via the :quer The interaction of properties with an unknown value with query filters is described in the section `Filtering on Properties with an unknown value`_. In particular, filters with :filter-fragment:`IS UNKNOWN` and :filter-fragment:`IS KNOWN` can be used to match entries with values that are, or are not, unknown for some property, respectively. -Handling unknown property names -------------------------------- +Handling unrecognized property names +------------------------------------ -When an implementation receives a request with a query filter or other mechanism (e.g., :query-param:`response_fields`) that refers to an unknown property name, it MUST NOT treat this as an error. -Instead, it should evaluate queries with the property treated as unknown, meaning comparisons are evaluated as if the property has the value :val:`null`. +When an implementation receives a request with a query filter or other mechanism (e.g., :query-param:`response_fields`) that refers to a property name that is not recognized, it MUST NOT treat this as an error but rather MUST issue a warning with `code` set to `unrecognized_property`. +Queries MUST be evaluated with the property treated as unknown, meaning comparisons are evaluated as if the property has the value :val:`null`. If the unknown property is requested to be included in the response, it MUST be included with `null` value. -Furthermore: - -* If the property does not have a database-specific prefix, the implementation MUST issue a warning about the unrecognized property name. -* If the property has a database-specific prefix that the implementation does not recognize, it SHOULD return a warning indicating that the property has been handled as unknown. -* If the property has a recognized prefix, i.e., it belongs to a known database provider, the implementation SHOULD NOT issue a warning but may issue diagnostic output with a note explaining how the request was handled. -The rationale for not triggering errors in the above situations is to enable clients to perform queries that reference properties defined in future versions of the OPTIMADE standard or database-specific properties, and have them handled only by the databases that recognize them. +The rationale for not triggering errors for unrecognized properties is to enable clients to perform queries that reference properties defined in future versions of the OPTIMADE standard or database-specific properties, and have them handled only by the databases that recognize them. Database-specific properties (as well as properties defined in future versions of this standard) SHOULD be defined in such a way that treating them as :val:`null` in comparisons is a reasonable behavior for providers that do not support the property. +If this is not possible, and if the endpoint defines a :property:`_features` property (e.g., :property:`structure_features` for the `structures` endpoint), the implementation MUST define a database-specific identifier and place it in this list for those entries where the distinction between implementations that do and do not support the property is important. +Filters can then be formulated as, e.g., :filter-fragment:`_exmpl_strange_property IS UNKNOWN and structure_features HAS "strangeness"` to suppress results from implementations that do not support :property:`_exmpl_strange_property`. For example, the following query can be sent to API implementations `exmpl1` and `exmpl2` without generating any errors: @@ -719,7 +716,14 @@ Warnings Non-critical exceptional situations occurring in the implementation SHOULD be reported to the referrer as warnings. Warnings MUST be expressed as a human-readable message, OPTIONALLY coupled with a warning code. -Warning codes starting with an alphanumeric character are reserved for general OPTIMADE error codes (currently, none are specified). +Warning codes starting with an alphanumeric character are reserved for general OPTIMADE error codes. +The following are defined: + +- `unrecognized_property`: the request refers to an unrecognized property in the query parameters `filter`, `response_fields`, or in some other way. + Implementations SHOULD indicate in the warning field `details` which properties are unrecognized. + For future compatability, unrecognized properties are handled as having value :val:`null`. + For more information, see `Handling unrecognized property names`_. + For implementation-specific warnings, they MUST start with ``_`` and the database-provider-specific prefix of the implementation (see section `Database-Provider-Specific Namespace Prefixes`_). API Endpoints @@ -2848,6 +2852,8 @@ structure\_features - MUST be sorted alphabetically. - If a special feature listed below is used, the list MUST contain the corresponding string. - If a special feature listed below is not used, the list MUST NOT contain the corresponding string. + - Clients SHOULD NOT assume they can represent the structure correctly if the :field:`structure_features` field indicates a feature not supported by the client or contains any unrecognized items. + - Implementations that use database-specific properties that must be supported by the client to correctly interpret the structural information MUST define a string with a database-provider-specific prefix and place it in this list for those entries that would be incorrectly interpreted by ignoring the property. - **List of strings used to indicate special structure features**: - :val:`disorder`: this flag MUST be present if any one entry in the `species`_ list has a :field:`chemical_symbols` list that is longer than 1 element. From b91e617e4c3e9753716cb2fc04756cdb229aa5db Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Tue, 28 Feb 2023 15:08:13 +0100 Subject: [PATCH 05/11] Fix unknown property -> unrecognized property --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index 0db35f794..249a414c1 100644 --- a/optimade.rst +++ b/optimade.rst @@ -428,7 +428,7 @@ Handling unrecognized property names When an implementation receives a request with a query filter or other mechanism (e.g., :query-param:`response_fields`) that refers to a property name that is not recognized, it MUST NOT treat this as an error but rather MUST issue a warning with `code` set to `unrecognized_property`. Queries MUST be evaluated with the property treated as unknown, meaning comparisons are evaluated as if the property has the value :val:`null`. -If the unknown property is requested to be included in the response, it MUST be included with `null` value. +If the unrecognized property is requested to be included in the response, it MUST be included with `null` value. The rationale for not triggering errors for unrecognized properties is to enable clients to perform queries that reference properties defined in future versions of the OPTIMADE standard or database-specific properties, and have them handled only by the databases that recognize them. Database-specific properties (as well as properties defined in future versions of this standard) SHOULD be defined in such a way that treating them as :val:`null` in comparisons is a reasonable behavior for providers that do not support the property. From 0deec6047a70bcb3449dbb3e8ad5c720a755f9fb Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Tue, 28 Feb 2023 15:17:54 +0100 Subject: [PATCH 06/11] Apply suggestions from review --- optimade.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/optimade.rst b/optimade.rst index 249a414c1..0cb382025 100644 --- a/optimade.rst +++ b/optimade.rst @@ -428,7 +428,7 @@ Handling unrecognized property names When an implementation receives a request with a query filter or other mechanism (e.g., :query-param:`response_fields`) that refers to a property name that is not recognized, it MUST NOT treat this as an error but rather MUST issue a warning with `code` set to `unrecognized_property`. Queries MUST be evaluated with the property treated as unknown, meaning comparisons are evaluated as if the property has the value :val:`null`. -If the unrecognized property is requested to be included in the response, it MUST be included with `null` value. +If the unrecognized property is requested to be included in the response, it MUST be included with :val:`null` value. The rationale for not triggering errors for unrecognized properties is to enable clients to perform queries that reference properties defined in future versions of the OPTIMADE standard or database-specific properties, and have them handled only by the databases that recognize them. Database-specific properties (as well as properties defined in future versions of this standard) SHOULD be defined in such a way that treating them as :val:`null` in comparisons is a reasonable behavior for providers that do not support the property. @@ -721,7 +721,7 @@ The following are defined: - `unrecognized_property`: the request refers to an unrecognized property in the query parameters `filter`, `response_fields`, or in some other way. Implementations SHOULD indicate in the warning field `details` which properties are unrecognized. - For future compatability, unrecognized properties are handled as having value :val:`null`. + For future compatibility, unrecognized properties are handled as having value :val:`null`. For more information, see `Handling unrecognized property names`_. For implementation-specific warnings, they MUST start with ``_`` and the database-provider-specific prefix of the implementation (see section `Database-Provider-Specific Namespace Prefixes`_). From 3ebf0540a7677d501c1d1b0e6dd67f334aeda33a Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Mon, 20 Mar 2023 14:02:52 +0100 Subject: [PATCH 07/11] Fix incorrect example on futureproof unknown field --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index 0cb382025..f02440783 100644 --- a/optimade.rst +++ b/optimade.rst @@ -433,7 +433,7 @@ If the unrecognized property is requested to be included in the response, it MUS The rationale for not triggering errors for unrecognized properties is to enable clients to perform queries that reference properties defined in future versions of the OPTIMADE standard or database-specific properties, and have them handled only by the databases that recognize them. Database-specific properties (as well as properties defined in future versions of this standard) SHOULD be defined in such a way that treating them as :val:`null` in comparisons is a reasonable behavior for providers that do not support the property. If this is not possible, and if the endpoint defines a :property:`_features` property (e.g., :property:`structure_features` for the `structures` endpoint), the implementation MUST define a database-specific identifier and place it in this list for those entries where the distinction between implementations that do and do not support the property is important. -Filters can then be formulated as, e.g., :filter-fragment:`_exmpl_strange_property IS UNKNOWN and structure_features HAS "strangeness"` to suppress results from implementations that do not support :property:`_exmpl_strange_property`. +Filters can then be formulated as, e.g., :filter-fragment:`_exmpl_strange_property IS UNKNOWN and structure_features HAS "_exmpl_strangeness"` to suppress results from implementations that do not support :property:`_exmpl_strange_property`. For example, the following query can be sent to API implementations `exmpl1` and `exmpl2` without generating any errors: From 301d71d06d3b5a7bc3ef5f065978abdf520508da Mon Sep 17 00:00:00 2001 From: Matthew Evans <7916000+ml-evs@users.noreply.github.com> Date: Thu, 11 May 2023 16:23:18 +0100 Subject: [PATCH 08/11] Fix warning field name Co-authored-by: Antanas Vaitkus --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index f02440783..7461dc75d 100644 --- a/optimade.rst +++ b/optimade.rst @@ -720,7 +720,7 @@ Warning codes starting with an alphanumeric character are reserved for general O The following are defined: - `unrecognized_property`: the request refers to an unrecognized property in the query parameters `filter`, `response_fields`, or in some other way. - Implementations SHOULD indicate in the warning field `details` which properties are unrecognized. + Implementations SHOULD indicate in the warning field `detail` which properties are unrecognized. For future compatibility, unrecognized properties are handled as having value :val:`null`. For more information, see `Handling unrecognized property names`_. From 5d0d021325086676e86387ce0d61fcb80f3bf5f3 Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Tue, 16 May 2023 13:48:31 +0200 Subject: [PATCH 09/11] Fix rst formatting from review Co-authored-by: Matthew Evans <7916000+ml-evs@users.noreply.github.com> --- optimade.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/optimade.rst b/optimade.rst index 7461dc75d..c49ed89d7 100644 --- a/optimade.rst +++ b/optimade.rst @@ -426,13 +426,13 @@ In particular, filters with :filter-fragment:`IS UNKNOWN` and :filter-fragment:` Handling unrecognized property names ------------------------------------ -When an implementation receives a request with a query filter or other mechanism (e.g., :query-param:`response_fields`) that refers to a property name that is not recognized, it MUST NOT treat this as an error but rather MUST issue a warning with `code` set to `unrecognized_property`. +When an implementation receives a request with a query filter or other mechanism (e.g., :query-param:`response_fields`) that refers to a property name that is not recognized, it MUST NOT treat this as an error but rather MUST issue a warning with :field:`code` set to :field-val:`unrecognized_property`. Queries MUST be evaluated with the property treated as unknown, meaning comparisons are evaluated as if the property has the value :val:`null`. If the unrecognized property is requested to be included in the response, it MUST be included with :val:`null` value. The rationale for not triggering errors for unrecognized properties is to enable clients to perform queries that reference properties defined in future versions of the OPTIMADE standard or database-specific properties, and have them handled only by the databases that recognize them. Database-specific properties (as well as properties defined in future versions of this standard) SHOULD be defined in such a way that treating them as :val:`null` in comparisons is a reasonable behavior for providers that do not support the property. -If this is not possible, and if the endpoint defines a :property:`_features` property (e.g., :property:`structure_features` for the `structures` endpoint), the implementation MUST define a database-specific identifier and place it in this list for those entries where the distinction between implementations that do and do not support the property is important. +If this is not possible, and if the endpoint defines a :property:`_features` property (e.g., :property:`structure_features` for the :endpoint:`structures` endpoint), the implementation MUST define a database-specific identifier and place it in this list for those entries where the distinction between implementations that do and do not support the property is important. Filters can then be formulated as, e.g., :filter-fragment:`_exmpl_strange_property IS UNKNOWN and structure_features HAS "_exmpl_strangeness"` to suppress results from implementations that do not support :property:`_exmpl_strange_property`. For example, the following query can be sent to API implementations `exmpl1` and `exmpl2` without generating any errors: @@ -719,8 +719,8 @@ Warnings MUST be expressed as a human-readable message, OPTIONALLY coupled with Warning codes starting with an alphanumeric character are reserved for general OPTIMADE error codes. The following are defined: -- `unrecognized_property`: the request refers to an unrecognized property in the query parameters `filter`, `response_fields`, or in some other way. - Implementations SHOULD indicate in the warning field `detail` which properties are unrecognized. +- :field-val:`unrecognized_property`: the request refers to an unrecognized property in the query parameters :query-parameter:`filter`, :query_parameter:`response_fields`, or in some other way. + Implementations SHOULD indicate in the warning field :field:`detail` which properties are unrecognized. For future compatibility, unrecognized properties are handled as having value :val:`null`. For more information, see `Handling unrecognized property names`_. From e6695e85651486d19fc914d3e39f2c8c4368c3d3 Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Wed, 17 May 2023 09:14:25 +0200 Subject: [PATCH 10/11] Clarify statement about new fields and null based on review --- optimade.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index c49ed89d7..4a6e89f5e 100644 --- a/optimade.rst +++ b/optimade.rst @@ -431,7 +431,7 @@ Queries MUST be evaluated with the property treated as unknown, meaning comparis If the unrecognized property is requested to be included in the response, it MUST be included with :val:`null` value. The rationale for not triggering errors for unrecognized properties is to enable clients to perform queries that reference properties defined in future versions of the OPTIMADE standard or database-specific properties, and have them handled only by the databases that recognize them. -Database-specific properties (as well as properties defined in future versions of this standard) SHOULD be defined in such a way that treating them as :val:`null` in comparisons is a reasonable behavior for providers that do not support the property. +Database-specific properties (as well as properties defined in future versions of this standard) SHOULD be defined in such a way that returning them with the value :val:`null` and treating them as :val:`null` in comparisons is a reasonable behavior for providers that do not support the property. If this is not possible, and if the endpoint defines a :property:`_features` property (e.g., :property:`structure_features` for the :endpoint:`structures` endpoint), the implementation MUST define a database-specific identifier and place it in this list for those entries where the distinction between implementations that do and do not support the property is important. Filters can then be formulated as, e.g., :filter-fragment:`_exmpl_strange_property IS UNKNOWN and structure_features HAS "_exmpl_strangeness"` to suppress results from implementations that do not support :property:`_exmpl_strange_property`. @@ -2300,6 +2300,9 @@ database-provider-specific properties Similarly, an implementation MAY add keys with a database-provider-specific prefix to dictionary properties and their sub-dictionaries. For example, the database-provider-specific property :property:`_exmpl_oxidation_state`, can be placed within the OPTIMADE property :property:`species`. + Database-specific properties SHOULD be defined in such a way that returning them with the value :val:`null` and treating them as :val:`null` in comparisons is a reasonable behavior for providers that do not support the property. + See `Handling unrecognized property names`_ for more information. + - **Type**: Decided by the API implementation. MUST be one of the OPTIMADE `Data types`_. - **Requirements/Conventions**: From 793ad00fec0f968feac29d3b6bb79e3558876687 Mon Sep 17 00:00:00 2001 From: Rickard Armiento Date: Thu, 8 Jun 2023 23:59:22 +0200 Subject: [PATCH 11/11] Apply suggestions from review --- optimade.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/optimade.rst b/optimade.rst index 4a6e89f5e..e6060ed61 100644 --- a/optimade.rst +++ b/optimade.rst @@ -432,8 +432,6 @@ If the unrecognized property is requested to be included in the response, it MUS The rationale for not triggering errors for unrecognized properties is to enable clients to perform queries that reference properties defined in future versions of the OPTIMADE standard or database-specific properties, and have them handled only by the databases that recognize them. Database-specific properties (as well as properties defined in future versions of this standard) SHOULD be defined in such a way that returning them with the value :val:`null` and treating them as :val:`null` in comparisons is a reasonable behavior for providers that do not support the property. -If this is not possible, and if the endpoint defines a :property:`_features` property (e.g., :property:`structure_features` for the :endpoint:`structures` endpoint), the implementation MUST define a database-specific identifier and place it in this list for those entries where the distinction between implementations that do and do not support the property is important. -Filters can then be formulated as, e.g., :filter-fragment:`_exmpl_strange_property IS UNKNOWN and structure_features HAS "_exmpl_strangeness"` to suppress results from implementations that do not support :property:`_exmpl_strange_property`. For example, the following query can be sent to API implementations `exmpl1` and `exmpl2` without generating any errors: