Add models for per-entry & per-property metadata

openapi/index_openapi.json

@@ -477,6 +477,19 @@
         "title": "BaseRelationshipResource",
         "description": "Minimum requirements to represent a relationship resource"
       },
+      "EntryMetadata": {
+        "properties": {
+          "property_metadata": {
+            "type": "object",
+            "title": "Property Metadata",
+            "description": "An object containing per-entry and per-property metadata. The keys are the names of the fields in attributes for which metadata is available. The values belonging to these keys are dictionaries containing the relevant metadata fields. See also [Metadata properties](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#metadata-properties)"
+          }
+        },
+        "additionalProperties": true,
+        "type": "object",
+        "title": "EntryMetadata",
+        "description": "Contains the metadata for the attributes of an entry"
+      },
       "EntryRelationships": {
         "properties": {
           "references": {
@@ -536,13 +549,13 @@
           "meta": {
             "anyOf": [
               {
-                "$ref": "#/components/schemas/Meta"
+                "$ref": "#/components/schemas/EntryMetadata"
               },
               {
                 "type": "null"
               }
             ],
-            "description": "a meta object containing non-standard meta-information about a resource that can not be represented as an attribute or relationship."
+            "description": "A [JSON API meta object](https://jsonapi.org/format/1.1/#document-meta) that is used to communicate metadata."
           },
           "attributes": {
             "$ref": "#/components/schemas/EntryResourceAttributes",
@@ -1283,13 +1296,13 @@
           "meta": {
             "anyOf": [
               {
-                "$ref": "#/components/schemas/Meta"
+                "$ref": "#/components/schemas/EntryMetadata"
               },
               {
                 "type": "null"
               }
             ],
-            "description": "a meta object containing non-standard meta-information about a resource that can not be represented as an attribute or relationship."
+            "description": "A [JSON API meta object](https://jsonapi.org/format/1.1/#document-meta) that is used to communicate metadata."
           },
           "attributes": {
             "$ref": "#/components/schemas/LinksResourceAttributes",

openapi/openapi.json

@@ -1797,6 +1797,19 @@
         ],
         "title": "EntryInfoResponse"
       },
+      "EntryMetadata": {
+        "properties": {
+          "property_metadata": {
+            "type": "object",
+            "title": "Property Metadata",
+            "description": "An object containing per-entry and per-property metadata. The keys are the names of the fields in attributes for which metadata is available. The values belonging to these keys are dictionaries containing the relevant metadata fields. See also [Metadata properties](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#metadata-properties)"
+          }
+        },
+        "additionalProperties": true,
+        "type": "object",
+        "title": "EntryMetadata",
+        "description": "Contains the metadata for the attributes of an entry"
+      },
       "EntryRelationships": {
         "properties": {
           "references": {
@@ -1856,13 +1869,13 @@
           "meta": {
             "anyOf": [
               {
-                "$ref": "#/components/schemas/Meta"
+                "$ref": "#/components/schemas/EntryMetadata"
               },
               {
                 "type": "null"
               }
             ],
-            "description": "a meta object containing non-standard meta-information about a resource that can not be represented as an attribute or relationship."
+            "description": "A [JSON API meta object](https://jsonapi.org/format/1.1/#document-meta) that is used to communicate metadata."
           },
           "attributes": {
             "$ref": "#/components/schemas/EntryResourceAttributes",
@@ -2443,13 +2456,13 @@
           "meta": {
             "anyOf": [
               {
-                "$ref": "#/components/schemas/Meta"
+                "$ref": "#/components/schemas/EntryMetadata"
               },
               {
                 "type": "null"
               }
             ],
-            "description": "a meta object containing non-standard meta-information about a resource that can not be represented as an attribute or relationship."
+            "description": "A [JSON API meta object](https://jsonapi.org/format/1.1/#document-meta) that is used to communicate metadata."
           },
           "attributes": {
             "$ref": "#/components/schemas/LinksResourceAttributes",
@@ -2943,13 +2956,13 @@
           "meta": {
             "anyOf": [
               {
-                "$ref": "#/components/schemas/Meta"
+                "$ref": "#/components/schemas/EntryMetadata"
               },
               {
                 "type": "null"
               }
             ],
-            "description": "a meta object containing non-standard meta-information about a resource that can not be represented as an attribute or relationship."
+            "description": "A [JSON API meta object](https://jsonapi.org/format/1.1/#document-meta) that is used to communicate metadata."
           },
           "attributes": {
             "$ref": "#/components/schemas/ReferenceResourceAttributes"
@@ -4070,13 +4083,13 @@
           "meta": {
             "anyOf": [
               {
-                "$ref": "#/components/schemas/Meta"
+                "$ref": "#/components/schemas/EntryMetadata"
               },
               {
                 "type": "null"
               }
             ],
-            "description": "a meta object containing non-standard meta-information about a resource that can not be represented as an attribute or relationship."
+            "description": "A [JSON API meta object](https://jsonapi.org/format/1.1/#document-meta) that is used to communicate metadata."
           },
           "attributes": {
             "$ref": "#/components/schemas/StructureResourceAttributes"

optimade/models/entries.py

@@ -1,9 +1,9 @@
 from datetime import datetime
 from typing import Annotated, Any, ClassVar, Literal
 
-from pydantic import BaseModel, field_validator
+from pydantic import BaseModel, field_validator, model_validator
 
-from optimade.models.jsonapi import Attributes, Relationships, Resource
+from optimade.models.jsonapi import Attributes, Meta, Relationships, Resource
 from optimade.models.optimade_json import (
     BaseRelationshipResource,
     DataType,
@@ -117,6 +117,36 @@ def cast_immutable_id_to_str(cls, value: Any) -> str:
         return value
 
 
+class EntryMetadata(Meta):
+    """Contains the metadata for the attributes of an entry"""
+
+    property_metadata: dict = StrictField(
+        None,
+        description="""An object containing per-entry and per-property metadata. The keys are the names of the fields in attributes for which metadata is available. The values belonging to these keys are dictionaries containing the relevant metadata fields. See also [Metadata properties](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#metadata-properties)""",
+    )
+
+    @field_validator("property_metadata", mode="before")
+    def check_property_metadata_subfields(cls, value: Any) -> dict:
+        """Loop through any per-property metadata field and check that
+        the subfields are prefixed correctly.
+
+        """
+        error_fields: list[str] = []
+
+        if value is not None and isinstance(value, dict):
+            for field in value:
+                if property_metadata := value.get(field):
+                    for subfield in property_metadata:
+                        if not subfield.startswith("_"):
+                            error_fields.append(subfield)
+
+        if error_fields:
+            raise ValueError(
+                f"The keys under the field `property_metadata` need to be prefixed. The field(s) {error_fields} are not prefixed."
+            )
+        return value
+
+
 class EntryResource(Resource):
     """The base model for an entry resource."""
 
@@ -171,6 +201,14 @@ class EntryResource(Resource):
         ),
     ]
 
+    meta: Annotated[
+        EntryMetadata | None,
+        StrictField(
+            None,
+            description="""A [JSON API meta object](https://jsonapi.org/format/1.1/#document-meta) that is used to communicate metadata.""",
+        ),
+    ] = None
+
     relationships: Annotated[
         EntryRelationships | None,
         StrictField(
@@ -179,6 +217,47 @@ class EntryResource(Resource):
         ),
     ] = None
 
+    @model_validator(mode="before")
+    def check_meta(cls, data: Any) -> dict | None:
+        """Validator to check whether the per-entry `meta` field is valid,
+        including stripping out any per-property metadata for properties that
+        do not otherwise appear in the model.
+
+        """
+
+        meta = data.get("meta")
+        if not meta:
+            return data
+
+        if property_metadata := meta.pop("property_metadata", None):
+            # check that all the fields under property metadata are in attributes
+            attributes = data.get("attributes", {})
+            property_error_fields: list[str] = []
+            for subfield in property_metadata:
+                if subfield not in attributes:
+                    property_error_fields.append(subfield)
+
+            if property_error_fields:
+                raise ValueError(
+                    f"The keys under the field `property_metadata` need to match with the field names in attributes. The field(s) {property_error_fields} are however not present in attributes {attributes}"
+                )
+
+        meta["property_metadata"] = property_metadata
+
+        meta_error_fields: list[str] = []
+        for field in meta:
+            if field not in EntryMetadata.model_fields:
+                if not field.startswith("_"):
+                    meta_error_fields.append(field)
+
+        if meta_error_fields:
+            raise ValueError(
+                f"The keys under the field `meta` need to be prefixed if not otherwise defined. The field(s) {meta_error_fields} are not defined for per-entry `meta`."
+            )
+
+        data["meta"] = meta
+        return data
+
 
 class EntryInfoProperty(BaseModel):
     description: Annotated[

optimade/server/data/test_structures.json

@@ -3,6 +3,13 @@
     "_id": {
       "$oid": "5cfb441f053b174410700d02"
     },
+    "meta": {
+      "property_metadata": {
+        "elements_ratios": {
+          "_exmpl_originates_from_project": "Pure Metals"
+        }
+      }
+    },
     "assemblies": null,
     "chemsys": "Ac",
     "cartesian_site_positions": [
@@ -80,6 +87,13 @@
     "_id": {
       "$oid": "5cfb441f053b174410700d03"
     },
+    "meta": {
+      "property_metadata": {
+        "elements_ratios": {
+          "_exmpl_originates_from_project": "Actinides_Alloys"
+        }
+      }
+    },
     "assemblies": null,
     "chemsys": "Ac-Ag-Ir",
     "cartesian_site_positions": [
@@ -197,6 +211,13 @@
     "_id": {
       "$oid": "5cfb441f053b174410700d04"
     },
+    "meta": {
+      "property_metadata": {
+        "elements_ratios": {
+          "_exmpl_originates_from_project": "Actinides_Alloys"
+        }
+      }
+    },
     "assemblies": null,
     "chemsys": "Ac-Ag-Pb",
     "cartesian_site_positions": [
@@ -323,6 +344,13 @@
     "_id": {
       "$oid": "5cfb441f053b174410700d18"
     },
+    "meta": {
+      "property_metadata": {
+        "elements_ratios": {
+          "_exmpl_originates_from_project": "Actinides_Alloys"
+        }
+      }
+    },
     "assemblies": null,
     "chemsys": "Ac-Mg",
     "cartesian_site_positions": [
@@ -413,6 +441,13 @@
     "_id": {
       "$oid": "5cfb441f053b174410700d1f"
     },
+    "meta": {
+      "property_metadata": {
+        "elements_ratios": {
+          "_exmpl_originates_from_project": null
+        }
+      }
+    },
     "assemblies": null,
     "chemsys": "Ac-O",
     "cartesian_site_positions": [
@@ -515,6 +550,11 @@
     "_id": {
       "$oid": "5cfb441f053b174410700d6f"
     },
+    "meta": {
+      "property_metadata": {
+        "elements_ratios": {}
+      }
+    },
     "assemblies": null,
     "chemsys": "Ac-Cu-F-O",
     "cartesian_site_positions": [
@@ -639,6 +679,13 @@
     "_id": {
       "$oid": "5cfb441f053b174410700dc9"
     },
+    "meta": {
+      "property_metadata": {
+        "elements_ratios": {
+          "_exmpl_originates_from_project": "Pure Metals"
+        }
+      }
+    },
     "assemblies": null,
     "chemsys": "Ag",
     "cartesian_site_positions": [
@@ -706,6 +753,11 @@
     "_id": {
       "$oid": "5cfb441f053b174410700ddd"
     },
+    "meta": {
+      "property_metadata": {
+        "elements_ratios": null
+      }
+    },
     "assemblies": null,
     "chemsys": "Ag-Br-Cl-Te",
     "cartesian_site_positions": [
@@ -896,6 +948,9 @@
     "_id": {
       "$oid": "5cfb441f053b174410700e04"
     },
+    "meta": {
+      "property_metadata": {}
+    },
     "assemblies": null,
     "chemsys": "Ag-C-Cl-N-O-S",
     "cartesian_site_positions": [
@@ -1072,6 +1127,9 @@
     "_id": {
       "$oid": "5cfb441f053b174410700e11"
     },
+    "meta": {
+      "property_metadata": null
+    },
     "assemblies": null,
     "chemsys": "Ag-C-Cl-H-N",
     "cartesian_site_positions": [