Add per entry and per property meta data field.

optimade.rst

@@ -381,7 +381,7 @@ API implementations SHOULD NOT make up and use new prefixes without first gettin
 
 **Examples**:
 
-- A database-provider-specific prefix: ``exmpl``. Used as a field name in a response: :field:`_exmpl_custom_field`.
+- A database-provider-specific prefix: ``exmpl``. Used in a field name in a response: :field:`_exmpl_custom_field`.
 
 The initial underscore indicates an identifier that is under a separate namespace under the ownership of that organization.
 Identifiers prefixed with underscores will not be used for standardized names.
@@ -442,6 +442,109 @@ For example, the following query can be sent to API implementations `exmpl1` and
 
 :filter:`filter=_exmpl1_band_gap<2.0 OR _exmpl2_band_gap<2.5`
 
+Per property metadata fields
+----------------------------
+
+Implementations are allowed to specify an OPTIONAL field containing per entry metadata for a property.
+The name of the metadata field consists of the name of the property for which it contains the metadata, suffixed with "_meta".
+For example, when the field is :property:`cartesian_site_positions` the metadata field would be :field:`cartesian_site_positions_meta`.
+
+This metadata field consists of a dictionary which MAY contain database specific fields.
+Fields in this metadata MAY also have a metadata field.
+If an implementation supports the metadata field, it SHOULD return the metadata field whenever the property to which the metadata field belongs is returned.
+
+The metadata fields and their subfields should be described in the property definitions as described in the section `property definitions`_ just as regular fields.
+If a subfield is present in multiple metadata fields these subfields should have a separate entry under each of these metadata fields.
+The subfields SHOULD have the same value for the $id field if the $id field is present and the subfields are otherwise identical.
+
+It SHOULD contain the field :
+
+- **metadata_for**: which contains a string with the name of the property for which this meta data property contains the meta data,
+
+Example of a returned metadata field:
+
+    .. code:: jsonc
+
+       {
+         "element_ratios":[0.33336, 0.22229, 0.44425],
+         "element_ratios_meta": {
+           "metadata_for": "element_ratios",
+           "_exmpl_confidence_interval": [[0.33325,0.33347],[0.22190,0.22268],[0.44392,0.44458]],
+           "_exmpl_confidence_interval_meta": {
+              "_exmpl_confidence_level": 0.95,
+              "metadata_for": "_exmpl_confidence_interval",
+           }
+         //...
+       }
+
+Example of the property definition of a metadata field:
+
+    .. code:: jsonc
+       {
+         "element_ratios_meta": {
+           "$id": "https://properties.example.com/v1.2.0/element_ratios_meta",
+           "title": "Metadata for the element_ratios field",
+           "description": "This field contains the metadata for the element_ratios field that is specific to each individual entry.",
+           "x-optimade-property": {
+             "property-format": "1.2"
+           },
+           "x-optimade-type": "dictionary",
+           "x-optimade-unit": "inapplicable",
+           "type": ["object", "null"],
+           "properties" : {
+             "metadata_for": {
+               "$id": "https://properties.example.com/v1.2.0/element_ratios_meta/metadata_for",
+               "description" : "Defines the property for which this metadata field contains metadata.",
+               "x-optimade-type": "string",
+               "x-optimade-unit" : "inapplicable",
+               "type": "string"
+             },
+             "_exmpl_confidence_interval": {
+               "$id": "https://properties.example.com/v1.2.0/element_ratios_meta/_exmpl_confidence_interval",
+               "description" : "This field consists of a list with a list that contains the lower and upper bounds of the confidence interval.",
+               "x-optimade-type": "list",
+               "x-optimade-unit" : "inapplicable",
+               "type": "array",
+               "items": {
+                 "x-optimade-type": "list",
+                 "description" : "The first value in this list is the lower bound for the confidence interval the second value is the upper bound.",
+                 "x-optimade-unit" : "inapplicable",
+                 "type": "array",
+                 "items": {
+                   "x-optimade-type": "float",
+                   "x-optimade-unit" : "dimensionless",
+                   "type": "number"
+                 }
+               }
+             },
+             "_exmpl_confidence_interval_meta": {
+               "$id": "https://properties.example.com/v1.2.0/element_ratios_meta/_exmpl_confidence_interval_meta",
+               "title": "Metadata for the _exmpl_confidence_interval field",
+               "x-optimade-type": "dictionary",
+               "x-optimade-unit": "inapplicable",
+               "type": ["object", "null"],
+               "properties" : {
+                 "metadata_for": {
+                   "$id": "https://properties.example.com/v1.2.0/element_ratios_meta/metadata_for",
+                   "description" : "Defines the property for which this metadata field contains metadata.",
+                   "x-optimade-type": "string",
+                   "x-optimade-unit" : "inapplicable",
+                   "type": "string"
+                 },
+                 "_exmpl_confidence_level": {
+                   "x-optimade-type": "float",
+                   "description" : "The confidence level for this interval e.g. 0.95",
+                   "maximum": 1.0,
+                   "minimum": 0.0,
+                   "x-optimade-unit" : "dimensionless",
+                   "type": "number"
+                 }
+               }
+             }
+           }
+         }
+       }
+
 Responses
 =========
 
@@ -2307,6 +2410,7 @@ database-provider-specific properties
     Implementations are thus allowed to decide that some of these properties are part of what can be seen as the default value of :query-param:`response_fields` when that query parameter is omitted.
     Implementations SHOULD NOT include database-provider-specific properties when the query parameter :query-param:`response_fields` is present but does not list them.
   - These MUST be prefixed by a database-provider-specific prefix (see appendix `Database-Provider-Specific Namespace Prefixes`_).
+  - The suffix ``_meta`` is reserved for properties that contain metadata, as described in the section `Per property metadata fields`_ and MUST not be used for fields that do not follow the guidelines described there.
   - Implementations MUST add the properties to the list of :property:`properties` under the respective entry listing :endpoint:`info` endpoint (see `Entry Listing Info Endpoints`_).
 
 - **Examples**: A few examples of valid database-provided-specific property names follows: