diff --git a/optimade.rst b/optimade.rst
index 3ca81829a..d8d243edc 100644
--- a/optimade.rst
+++ b/optimade.rst
@@ -489,3 +489,78 @@ 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 properties which have metadata and are present in the data part of the response.
+
+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"
+             }
+           }
+         }
+         // ...
+