Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adjust handling of unknown properties #456

Open
wants to merge 12 commits into
base: develop
Choose a base branch
from
17 changes: 8 additions & 9 deletions optimade.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.
rartino marked this conversation as resolved.
Show resolved Hide resolved

For example, the following query can be sent to API implementations `exmpl1` and `exmpl2` without generating any errors:

Expand Down