[WIP] Further updates to property definitions

.words.lst

@@ -204,3 +204,4 @@ yacc
 zeo
 zeolites
 �ngstr�m
+incrementing

optimade.rst

@@ -1871,6 +1871,8 @@ A Property Definition MUST be composed according to the combination of the requi
 
 **REQUIRED keys for all levels of the Property Definition:**
 
+.. _definition of the x-optimade-type field:
+
 - :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"`.
@@ -1884,6 +1886,10 @@ A Property Definition MUST be composed according to the combination of the requi
 - :field:`x-optimade-implementation`: Dictionary.
   A dictionary describing the level of OPTIMADE API functionality provided by the present implementation.
   If an implementation omits this field in its response, a client interacting with that implementation SHOULD NOT make any assumptions about the availability of these features.
+
+  This field should be seen as an annotation rather than an integral part of the Property Definition.
+  Two Property Definitions that only differ by the value of :field:`x-optimade-implementation` are considered the same, and as explained in the `definition of the $id field`_, they SHOULD share the same :field:`$id`.
+
   The dictionary has the following format:
 
   **OPTIONAL keys:**
@@ -1902,8 +1908,12 @@ A Property Definition MUST be composed according to the combination of the requi
     - :val:`partial`: the defined property MUST be queryable with support for a subset of the filter language operators as specified by the field :field:`query-support-operators`.
     - :val:`none`: the defined property does not need to be queryable with any features of the filter language.
 
+    Omitting the field or :val:`null` is equivalent to :val:`none`.
+
   - :field:`query-support-operators`: List of Strings.
     Defines the filter language features supported on this property.
+    MUST be present and not :val:`null` if and only if :field:`query-support` is :val:`partial`.
+
     Each string in the list MUST be one of :val:`<`, :val:`<=`, :val:`>`, :val:`>=`, :val:`=`, :val:`!=`, :val:`CONTAINS`, :val:`STARTS WITH`, :val:`ENDS WITH`:, :val:`HAS`, :val:`HAS ALL`, :val:`HAS ANY`, :val:`HAS ONLY`, :val:`IS KNOWN`, :val:`IS UNKNOWN` with the following meanings:
 
     - :val:`<`, :val:`<=`, :val:`>`, :val:`>=`, :val:`=`, :val:`!=`: indicating support for filtering this property using the respective operator.
@@ -1918,14 +1928,20 @@ A Property Definition MUST be composed according to the combination of the requi
 
     - :val:`IS KNOWN`, :val:`IS UNKNOWN`: indicating support for filtering this property on unknown values using the respective operator.
 
+  - :field:`response-default`: Boolean
+    The value :val:`TRUE` means the implementation includes the property in responses by default, i.e., when not specifically requested.
+    The value :val:`FALSE` means that the property is only included when requested.
+    Omitting the field or :val:`null` means the implementation does not declare if the property will be included in responses by default or not.
+
 - :field:`x-optimade-requirements`: Dictionary.
   A dictionary describing the level of OPTIMADE API functionality required by all implementations of this property.
   Omitting this field means the corresponding functionality is OPTIONAL.
-  The dictionary has the same format as :field:`x-optimade-implementation`, except that it also allows the following OPTIONAL field:
+  The dictionary has the same format as :field:`x-optimade-implementation`, *except that* the :field:`response-default` SHOULD NOT appear, and the following additional OPTIONAL fields are allowed:
 
   - :field:`support`: String.
     Describes the minimal required level of support for the Property by an implementation.
-    This field SHOULD only appear in an :field:`x-optimade-requirements` that is at the outermost level of a Property Definition, as the meaning of its inclusion on other levels is not defined.
+    This field only has meaning for the defined property when appearing in the :field:`x-optimade-requirements` at the outermost level of the definition.
+    Nevertheless, it MAY appear at other places, e.g., if a nested property definition has been inserted that references its own :field:`$id`.
     The string MUST be one of the following:
 
     - :val:`must`: the defined property MUST be recognized by the implementation (e.g., in filter strings) and MUST NOT be :val:`null`.
@@ -1937,6 +1953,21 @@ A Property Definition MUST be composed according to the combination of the requi
     Note: the specification by this field of whether the defined property can be :val:`null` or not MUST match the value of the :field:`type` field.
     If :val:`null` values are allowed, that field must be a list where the string :val:`"null"` is the second element.
 
+  - :field:`response-default-level`: String
+    Expresses if an implementation of this property is required to include or exclude it in responses when not specifically requested.
+    This field only has meaning for the defined property when appearing in the :field:`x-optimade-requirements` at the outermost level of the definition.
+    Nevertheless, it MAY appear at other places, e.g., if a nested property definition has been inserted that references its own :field:`$id`.
+
+    The string MUST be one of the following:
+
+    - :val:`must`: the defined property MUST be included in responses unless specifically excluded.
+    - :val:`should`: the defined property SHOULD be included in responses unless specifically excluded.
+    - :val:`may`: it is OPTIONAL for the implementation to include the defined property in responses or not.
+    - :val:`should not`: the defined property SHOULD NOT be included in responses unless specifically requested.
+    - :val:`must not`: the defined property MUST NOT be included in responses unless specifically requested.
+
+    Omitting the field is equivalent to :val:`may`.
+
 Property Definition keys from JSON Schema
 -----------------------------------------
 
@@ -1945,25 +1976,20 @@ The format described in this subsection forms a subset of the `JSON Schema Valid
 
 **REQUIRED keys**
 
-- :field:`type`: String or List.
+- :field:`type`: List.
   Specifies the corresponding JSON type for this level of the defined property and whether the property can be :val:`null` or not.
-  The value is directly correlated with :field:`x-optimade-type` as explained below.
-
-  It MUST be one of:
+  The value is directly correlated with :field:`x-optimade-type` (cf. the `definition of the x-optimade-type field`_).
 
-  - A string correlated with :field:`x-optimade-type` as follows.
-    If :field:`x-optimade-type` is:
+  It MUST be a list of one or two elements where the first element is a string correlated with :field:`x-optimade-type` as follows; if :field:`x-optimade-type` is:
 
     * :val:`"boolean"`, `"string"`, or `"integer"` then :field:`type` is the same string.
     * :val:`"dictionary"` then :field:`type` is `"object"`.
     * :val:`"list"` then :field:`type` is `"array"`.
     * :val:`"float"` then :field:`type` is `"number"`.
     * :val:`"timestamp"` then :field:`type` is `"string"`.
 
-  - A list where the first item MUST be the string described above (correlated to the field :field:`x-optimade-type` in the same way) and the second item MUST be the string :val:`"null"`.
-    This form specifies that the defined property can be :val:`null`.
-
-..
+  If the second element is included, it MUST be the string :val:`"null"`.
+  This two element form specifies that the defined property can be :val:`null`.
 
   Implementation notes:
 
@@ -1977,9 +2003,12 @@ The format described in this subsection forms a subset of the `JSON Schema Valid
 
 **OPTIONAL keys**
 
+.. _definition of the $id field:
+
 - :field:`$id`: String.
   A static URI identifier that is a URN or URL representing the specific version of this level of the defined property.
   It SHOULD NOT be changed as long as the property definition remains the same, and SHOULD be changed when the property definition changes.
+  The Property Definition SHOULD be regarded as the same if the only changes that have been made are to the following specific fields at any level: :field:`deprecated`, :field:`$comment`, or : field:`x-optimade-implementation`.
   (If it is a URL, clients SHOULD NOT assign any interpretation to the response when resolving that URL.)
 
 - :field:`title`: String.
@@ -1990,11 +2019,23 @@ The format described in this subsection forms a subset of the `JSON Schema Valid
   The format SHOULD be a one-line description, followed by a new paragraph (two newlines), followed by a more detailed description of all the requirements and conventions of the defined property.
   Formatting in the text SHOULD use Markdown in the `CommonMark v0.3 format <https://spec.commonmark.org/0.30/>`__.
 
+- :field:`$comment`: String.
+  A human-readable comment relevant in the context of the raw definition data.
+  These comments should be omitted in formatted descriptions of the property shown to the end users.
+  (Comments in descriptions relevant to the end users should go into :field:`description`.)
+  Formatting in the text SHOULD use Markdown in the `CommonMark v0.3 format <https://spec.commonmark.org/0.30/>`__.
+
+  This field should be seen as an annotation rather than an integral part of the Property Definition.
+  Two Property Definitions that only differ by the value of any :field:`$comment` fields are considered the same, and as explained in the `definition of the $id field`_, they SHOULD share the same :field:`$id`.
+
 - :field:`deprecated`: Boolean.
   If :val:`TRUE`, implementations SHOULD not use the defined property, and it MAY be removed in the future.
   If :val:`FALSE`, the defined property is not deprecated.
   The field not being present means :val:`FALSE`.
 
+  This field should be seen as an annotation rather than an integral part of the Property Definition.
+  Two Property Definitions that only differ by :field:`deprecated` fields are considered the same, and as explained in the `definition of the $id field`_, they SHOULD share the same :field:`$id`.
+
 - :field:`enum`: List.
   The defined property MUST take one of the values given in the provided list.
   The items in the list MUST all be of a data type that matches the :field:`type` field and otherwise adhere to the rest of the Property Description.