From 05010ff025a98a196f26f84a3f90448ba3ea88b1 Mon Sep 17 00:00:00 2001 From: Andrius Merkys Date: Fri, 14 Jun 2024 15:46:51 +0200 Subject: [PATCH 1/6] Describe custom data types in "Type handling and conversions in comparisons". --- optimade.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/optimade.rst b/optimade.rst index c852b384..461aa408 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2070,6 +2070,10 @@ As the filter language syntax does not define a lexical token for timestamps, va In a comparison with a timestamp property, a string token represents a timestamp value that would result from parsing the string according to RFC 3339 Internet Date/Time Format. Interpretation failures MUST be reported with error :http-error:`400 Bad Request`. +Namespace providers MAY introduce custom types, representing them with string lexical tokens both in filters and responses. +It is up to the namespace providers to decide which comparison operators to support and how the comparisons should be performed. +For example, if a provider intoduces a set-valued property :property:`_exmpl_set`, it may decide to define operator :val:`CONTAINS` so that :filter:`identifier CONTAINS set` is true if :val:`set` is a subset of a property. + Optional filter features ~~~~~~~~~~~~~~~~~~~~~~~~ From 20cbe9fa62430e106570f2a35779e9ec237a7a68 Mon Sep 17 00:00:00 2001 From: Andrius Merkys Date: Fri, 14 Jun 2024 15:54:17 +0200 Subject: [PATCH 2/6] Introducing provider-specific data types in other parts of the specification. --- optimade.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/optimade.rst b/optimade.rst index 461aa408..47a23c8d 100644 --- a/optimade.rst +++ b/optimade.rst @@ -215,7 +215,7 @@ Hence, entry properties are described in this proposal using context-independent types that are assumed to have some form of representation in all contexts. They are as follows: -- Basic types: **string**, **integer**, **float**, **boolean**, **timestamp**. +- Basic types: **string**, **integer**, **float**, **boolean**, **timestamp**, database-provider-specific or definition-provider-specific data type. - **list**: an ordered collection of items, where all items are of the same type, unless they are unknown. A list can be empty, i.e., contain no items. - **dictionary**: an associative array of **keys** and **values**, where **keys** are pre-determined strings, i.e., for the same entry property, the **keys** remain the same among different entries whereas the **values** change. @@ -627,6 +627,7 @@ In the JSON response format, property types translate as follows: - **timestamp** uses a string representation of date and time as defined in `RFC 3339 Internet Date/Time Format `__. - **dictionary** is represented by the JSON object type. - **unknown** properties are represented by either omitting the property or by a JSON :field-val:`null` value. +- database-provider-specific or definition-provider-specific data types use string representations. Every response SHOULD contain the following fields, and MUST contain at least :field:`meta`: @@ -1816,6 +1817,7 @@ The following tokens are used in the filter query component: (Note that at the end of the string value above the four final backslashes represent the two terminal backslashes in the value, and the final double quote is a terminator, it is not escaped.) String value tokens are also used to represent **timestamps** in form of the `RFC 3339 Internet Date/Time Format `__. + String value tokens as well are used to represent database-provider-specific or definition-provider-specific data types. - **Numeric values** are represented as decimal integers or in scientific notation, using the usual programming language conventions. A regular expression giving the number syntax is given below as a `POSIX Extended Regular Expression (ERE) `__ or as a `Perl-Compatible Regular Expression (PCRE) `__: @@ -2070,8 +2072,8 @@ As the filter language syntax does not define a lexical token for timestamps, va In a comparison with a timestamp property, a string token represents a timestamp value that would result from parsing the string according to RFC 3339 Internet Date/Time Format. Interpretation failures MUST be reported with error :http-error:`400 Bad Request`. -Namespace providers MAY introduce custom types, representing them with string lexical tokens both in filters and responses. -It is up to the namespace providers to decide which comparison operators to support and how the comparisons should be performed. +Database and definition providers MAY introduce custom types, representing them with string lexical tokens both in filters and responses. +It is up to the providers to decide which comparison operators to support and how the comparisons should be performed. For example, if a provider intoduces a set-valued property :property:`_exmpl_set`, it may decide to define operator :val:`CONTAINS` so that :filter:`identifier CONTAINS set` is true if :val:`set` is a subset of a property. Optional filter features From 466a193be7d58e5af797e0f90ea7a6aca5f91478 Mon Sep 17 00:00:00 2001 From: Andrius Merkys Date: Fri, 14 Jun 2024 15:59:27 +0200 Subject: [PATCH 3/6] Require provider-specific data types to bear provider-specific prefixes. --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index 47a23c8d..5888efcb 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2164,7 +2164,7 @@ A Property Definition MUST be composed according to the combination of the requi - :field:`x-optimade-type`: String. Specifies the OPTIMADE data type for this level of the defined property. - MUST be one of :val:`"string"`, :val:`"integer"`, :val:`"float"`, :val:`"boolean"`, :val:`"timestamp"`, :val:`"list"`, or :val:`"dictionary"`. + MUST be one of :val:`"string"`, :val:`"integer"`, :val:`"float"`, :val:`"boolean"`, :val:`"timestamp"`, :val:`"list"`, :val:`"dictionary"` or a string naming database-provider-specific or definition-provider-specific data type starting with provider-specific prefix. - :field:`x-optimade-unit`: String. A (compound) symbol for the physical unit in which the value of the defined property is given or one of the strings :val:`dimensionless` or :val:`inapplicable`. From 8bd0811db3825ed6b2cb644c29d1095b0ecee8d6 Mon Sep 17 00:00:00 2001 From: Andrius Merkys Date: Wed, 19 Jun 2024 15:45:41 +0300 Subject: [PATCH 4/6] Update optimade.rst Co-authored-by: Antanas Vaitkus --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index 5888efcb..7aca4377 100644 --- a/optimade.rst +++ b/optimade.rst @@ -2074,7 +2074,7 @@ Interpretation failures MUST be reported with error :http-error:`400 Bad Request Database and definition providers MAY introduce custom types, representing them with string lexical tokens both in filters and responses. It is up to the providers to decide which comparison operators to support and how the comparisons should be performed. -For example, if a provider intoduces a set-valued property :property:`_exmpl_set`, it may decide to define operator :val:`CONTAINS` so that :filter:`identifier CONTAINS set` is true if :val:`set` is a subset of a property. +For example, a provider that introduces a set-valued property :property:`_exmpl_set`, may decide to override the :val:`CONTAINS` operator so that :filter:`identifier CONTAINS set` is true when :val:`set` is a subset of a property. Optional filter features ~~~~~~~~~~~~~~~~~~~~~~~~ From 1330717396a3b70ff6997702323ab8b6db35f9cb Mon Sep 17 00:00:00 2001 From: Andrius Merkys Date: Fri, 21 Jun 2024 09:48:18 +0300 Subject: [PATCH 5/6] Split database-provider-specific and definition-provider-specific data types off from basic data types. --- optimade.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index 7aca4377..6f5bd98b 100644 --- a/optimade.rst +++ b/optimade.rst @@ -215,11 +215,12 @@ Hence, entry properties are described in this proposal using context-independent types that are assumed to have some form of representation in all contexts. They are as follows: -- Basic types: **string**, **integer**, **float**, **boolean**, **timestamp**, database-provider-specific or definition-provider-specific data type. +- Basic types: **string**, **integer**, **float**, **boolean**, **timestamp** - **list**: an ordered collection of items, where all items are of the same type, unless they are unknown. A list can be empty, i.e., contain no items. - **dictionary**: an associative array of **keys** and **values**, where **keys** are pre-determined strings, i.e., for the same entry property, the **keys** remain the same among different entries whereas the **values** change. The **values** of a dictionary can be any basic type, list, dictionary, or unknown. +- Database-provider-specific or definition-provider-specific data type. An entry property value that is not present in the database is **unknown**. This is equivalently expressed by the statement that the value of that entry property is :val:`null`. From 702bf6a7d43c245338c9341c288898ed368e3424 Mon Sep 17 00:00:00 2001 From: Andrius Merkys Date: Fri, 21 Jun 2024 12:21:44 +0300 Subject: [PATCH 6/6] Update optimade.rst Co-authored-by: Antanas Vaitkus --- optimade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/optimade.rst b/optimade.rst index 6f5bd98b..ba2e1a20 100644 --- a/optimade.rst +++ b/optimade.rst @@ -215,7 +215,7 @@ Hence, entry properties are described in this proposal using context-independent types that are assumed to have some form of representation in all contexts. They are as follows: -- Basic types: **string**, **integer**, **float**, **boolean**, **timestamp** +- Basic types: **string**, **integer**, **float**, **boolean**, **timestamp**. - **list**: an ordered collection of items, where all items are of the same type, unless they are unknown. A list can be empty, i.e., contain no items. - **dictionary**: an associative array of **keys** and **values**, where **keys** are pre-determined strings, i.e., for the same entry property, the **keys** remain the same among different entries whereas the **values** change.