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.