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: