Add per entry and per property meta data field.

optimade.rst

@@ -492,6 +492,80 @@ Below follows an example of the :field:`data` and :field:`meta` parts of a respo
      // ...
    }
 
+Metadata properties
+-------------------
+
+A metadata property represents entry and property-specific metadata for a given entry.
+How these are communicated in the response depends on the response format.
+For the JSON response format, the metadata properties are stored in the resource object metadata field, :field:`meta` in a dictionary field :field:`property_metadata` with the keys equal to the names of the respective properties for which metadata is available, see `JSON Response Schema: Common Fields`_.
+
+The format of the metadata property is specified by the field :field:`x-optimade-metadata-definition` in the Property Definition of the field, see `Property Definitions`_.
+Database providers are allowed to define their own metadata properties in :field:`x-optimade-metadata-definition`, but they MUST use the database-provider-specific prefix even for metadata of database-specific fields.
+For example, the metadata property definition of the field :field:`_exmpl_example_field` MUST NOT define a metadata field named, e.g., :field:`accuracy`; the field rather needs to be named, e.g., :field:`_exmpl_accuracy`.
+The reason for this limitation is to avoid name collisions with metadata fields defined by the OPTIMADE standard in the future that apply also to database-specific data fields.
+
+Implementation of the :field:`meta` field is OPTIONAL.
+However, when an implementation supports the :field:`property_metadata` field, it SHOULD include metadata fields for all fields present in the data part of the response which has metadata.
+
+Example of a response in the JSON response format with two structure entries that each include a metadata property for the attribute field :field:`element_ratios` and the database-specific per entry metadata field :field:`_exmpl_originates_from_project` :
+
+.. code:: jsonc
+     {
+       "data": [
+         {
+           "type": "structures",
+           "id": "example.db:structs:0001",
+           "attributes": {
+             "element_ratios":[0.33336, 0.22229, 0.44425]
+           },
+           "meta": {
+             "property_metadata": {
+               "element_ratios": {
+                 "_exmpl_originates_from_project": "piezoelectic_perovskites"
+               }
+             }
+           }
+         },
+         {
+           "type": "structures",
+           "id": "example.db:structs:1234",
+           "attributes": {
+             "element_ratios":[0.5, 0.5]
+           },
+           "meta": {
+             "property_metadata":{
+               "element_ratios": {
+                 "_exmpl_originates_from_project": "ferroelectric_binaries"
+               }
+             }
+           }
+         }
+         //...
+       ]
+       // ...
+     }
+
+Example of the corresponding metadata property definition contained in the field :field:`x-optimade-metadata-definition` which is placed in the property definition of :field:`element_ratios`:
+
+    .. code:: jsonc
+         // ...
+         "x-optimade-metadata-definition": {
+           "title": "Metadata for the element_ratios field",
+           "description": "This field contains the per-entry metadata for the element_ratios field.",
+           "x-optimade-type": "dictionary",
+           "x-optimade-unit": "inapplicable",
+           "type": ["object", "null"],
+           "properties" : {
+             "_exmpl_originates_from_project": {
+               "$id": "https://properties.example.com/v1.2.0/element_ratios_meta/_exmpl_originates_from_project",
+               "description" : "A string naming the internal example.com project id where this property was added to the database.",
+               "x-optimade-type": "string",
+               "x-optimade-unit" : "inapplicable"
+             }
+           }
+         }
+         // ...
+
 Responses
 =========
 
@@ -643,7 +717,12 @@ Every response SHOULD contain the following fields, and MUST contain at least :f
 - **data**: The schema of this value varies by endpoint, it can be either a *single* `JSON API resource object <http://jsonapi.org/format/1.0/#document-resource-objects>`__ or a *list* of JSON API resource objects.
   Every resource object needs the :field:`type` and :field:`id` fields, and its attributes (described in section `API Endpoints`_) need to be in a dictionary corresponding to the :field:`attributes` field.
 
-  Every resource object MAY also contain a :field:`meta` field with the following keys:
+  Every resource object MAY also contain a :field:`meta` field which MAY contain the following keys:
+
+ - **property_metadata**: an object containing per-entry and per-property metadata.
+    The keys are the names of the fields in :field:`attributes` for which metadata is available.
+    The values belonging to these keys are dictionaries containing the relevant metadata fields.
+    See also `Metadata properties`_
 
   - **partial_data_links**: an object used to list links which can be used to fetch data that has been omitted from the :field:`data` part of the response.
     The keys are the names of the fields in :field:`attributes` for which partial data links are available.