SHOULD/MUST/OPTIONAL fields in models

openapi/openapi.json

@@ -2116,7 +2116,8 @@
         "properties": {
           "name": {
             "title": "Name",
-            "type": "string"
+            "type": "string",
+            "description": "Full name of the person, REQUIRED."
           },
           "firstname": {
             "title": "Firstname",
@@ -2128,7 +2129,8 @@
             "type": "string",
             "description": "Last name of the person."
           }
-        }
+        },
+        "description": "A person, i.e., an author, editor or other."
       },
       "Provider": {
         "title": "Provider",
@@ -2836,7 +2838,8 @@
         "properties": {
           "name": {
             "title": "Name",
-            "type": "string"
+            "type": "string",
+            "description": "Gives the name of the species; the **name** value MUST be unique in the `species` list."
           },
           "chemical_symbols": {
             "title": "Chemical Symbols",

optimade/models/baseinfo.py

@@ -5,7 +5,7 @@
 from pydantic import BaseModel, AnyHttpUrl, Field, validator, root_validator
 
 from optimade.models.jsonapi import Resource
-from optimade.models.utils import SemanticVersion
+from optimade.models.utils import SemanticVersion, StrictField
 
 
 __all__ = ("AvailableApiVersion", "BaseInfoAttributes", "BaseInfoResource")
@@ -14,13 +14,13 @@
 class AvailableApiVersion(BaseModel):
     """A JSON object containing information about an available API version"""
 
-    url: AnyHttpUrl = Field(
+    url: AnyHttpUrl = StrictField(
         ...,
         description="A string specifying a versioned base URL that MUST adhere to the rules in section Base URL",
         pattern=r".+/v[0-1](\.[0-9]+)*/?$",
     )
 
-    version: SemanticVersion = Field(
+    version: SemanticVersion = StrictField(
         ...,
         description="""A string containing the full version number of the API served at that versioned base URL.
 The version number string MUST NOT be prefixed by, e.g., 'v'.
@@ -59,27 +59,27 @@ def crosscheck_url_and_version(cls, values):
 class BaseInfoAttributes(BaseModel):
     """Attributes for Base URL Info endpoint"""
 
-    api_version: SemanticVersion = Field(
+    api_version: SemanticVersion = StrictField(
         ...,
         description="""Presently used full version of the OPTIMADE API.
 The version number string MUST NOT be prefixed by, e.g., "v".
 Examples: `1.0.0`, `1.0.0-rc.2`.""",
     )
-    available_api_versions: List[AvailableApiVersion] = Field(
+    available_api_versions: List[AvailableApiVersion] = StrictField(
         ...,
         description="A list of dictionaries of available API versions at other base URLs",
     )
-    formats: List[str] = Field(
+    formats: List[str] = StrictField(
         default=["json"], description="List of available output formats."
     )
-    available_endpoints: List[str] = Field(
+    available_endpoints: List[str] = StrictField(
         ...,
         description="List of available endpoints (i.e., the string to be appended to the versioned base URL).",
     )
-    entry_types_by_format: Dict[str, List[str]] = Field(
+    entry_types_by_format: Dict[str, List[str]] = StrictField(
         ..., description="Available entry endpoints as a function of output formats."
     )
-    is_index: Optional[bool] = Field(
+    is_index: Optional[bool] = StrictField(
         default=False,
         description="If true, this is an index meta-database base URL (see section Index Meta-Database). "
         "If this member is not provided, the client MUST assume this is not an index meta-database base URL "

optimade/models/entries.py

@@ -5,6 +5,7 @@
 
 from optimade.models.jsonapi import Relationships, Attributes, Resource
 from optimade.models.optimade_json import Relationship, DataType
+from optimade.models.utils import StrictField, OptimadeField, SupportLevel
 
 
 __all__ = (
@@ -42,12 +43,12 @@ class StructureRelationship(TypedRelationship):
 class EntryRelationships(Relationships):
     """This model wraps the JSON API Relationships to include type-specific top level keys. """
 
-    references: Optional[ReferenceRelationship] = Field(
+    references: Optional[ReferenceRelationship] = StrictField(
         None,
         description="Object containing links to relationships with entries of the `references` type.",
     )
 
-    structures: Optional[StructureRelationship] = Field(
+    structures: Optional[StructureRelationship] = StrictField(
         None,
         description="Object containing links to relationships with entries of the `structures` type.",
     )
@@ -56,7 +57,7 @@ class EntryRelationships(Relationships):
 class EntryResourceAttributes(Attributes):
     """Contains key-value pairs representing the entry's properties."""
 
-    immutable_id: Optional[str] = Field(
+    immutable_id: Optional[str] = OptimadeField(
         None,
         description="""The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to "the latest version" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future.
 
@@ -69,9 +70,11 @@ class EntryResourceAttributes(Attributes):
 - **Examples**:
     - `"8bd3e750-b477-41a0-9b11-3a799f21b44f"`
     - `"fjeiwoj,54;@=%<>#32"` (Strings that are not URL-safe are allowed.)""",
+        support=SupportLevel.OPTIONAL,
+        queryable=SupportLevel.MUST,
     )
 
-    last_modified: datetime = Field(
+    last_modified: datetime = OptimadeField(
         ...,
         description="""Date and time representing when the entry was last modified.
 
@@ -84,13 +87,15 @@ class EntryResourceAttributes(Attributes):
 
 - **Example**:
     - As part of JSON response format: `"2007-04-05T14:30:20Z"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)""",
+        support=SupportLevel.SHOULD,
+        queryable=SupportLevel.MUST,
     )
 
 
 class EntryResource(Resource):
     """The base model for an entry resource."""
 
-    id: str = Field(
+    id: str = OptimadeField(
         ...,
         description="""An entry's ID as defined in section Definition of Terms.
 
@@ -107,6 +112,8 @@ class EntryResource(Resource):
     - `"cod/2000000@1234567"`
     - `"nomad/L1234567890"`
     - `"42"`""",
+        support=SupportLevel.MUST,
+        queryable=SupportLevel.MUST,
     )
 
     type: str = Field(
@@ -122,15 +129,17 @@ class EntryResource(Resource):
     - The entry of type `<type>` and ID `<id>` MUST be returned in response to a request for `/<type>/<id>` under the versioned base URL.
 
 - **Example**: `"structures"`""",
+        support=SupportLevel.MUST,
+        queryable=SupportLevel.MUST,
     )
 
-    attributes: EntryResourceAttributes = Field(
+    attributes: EntryResourceAttributes = StrictField(
         ...,
         description="""A dictionary, containing key-value pairs representing the entry's properties, except for `type` and `id`.
 Database-provider-specific properties need to include the database-provider-specific prefix (see section on Database-Provider-Specific Namespace Prefixes).""",
     )
 
-    relationships: Optional[EntryRelationships] = Field(
+    relationships: Optional[EntryRelationships] = StrictField(
         None,
         description="""A dictionary containing references to other entries according to the description in section Relationships encoded as [JSON API Relationships](https://jsonapi.org/format/1.0/#document-resource-object-relationships).
 The OPTIONAL human-readable description of the relationship MAY be provided in the `description` field inside the `meta` dictionary of the JSON API resource identifier object.""",
@@ -139,24 +148,24 @@ class EntryResource(Resource):
 
 class EntryInfoProperty(BaseModel):
 
-    description: str = Field(
+    description: str = StrictField(
         ..., description="A human-readable description of the entry property"
     )
 
-    unit: Optional[str] = Field(
+    unit: Optional[str] = StrictField(
         None,
         description="""The physical unit of the entry property.
 This MUST be a valid representation of units according to version 2.1 of [The Unified Code for Units of Measure](https://unitsofmeasure.org/ucum.html).
 It is RECOMMENDED that non-standard (non-SI) units are described in the description for the property.""",
     )
 
-    sortable: Optional[bool] = Field(
+    sortable: Optional[bool] = StrictField(
         None,
         description="""Defines whether the entry property can be used for sorting with the "sort" parameter.
 If the entry listing endpoint supports sorting, this key MUST be present for sortable properties with value `true`.""",
     )
 
-    type: Optional[DataType] = Field(
+    type: Optional[DataType] = StrictField(
         None,
         description="""The type of the property's value.
 This MUST be any of the types defined in the Data types section.
@@ -168,18 +177,18 @@ class EntryInfoProperty(BaseModel):
 
 class EntryInfoResource(BaseModel):
 
-    formats: List[str] = Field(
+    formats: List[str] = StrictField(
         ..., description="List of output formats available for this type of entry."
     )
 
-    description: str = Field(..., description="Description of the entry.")
+    description: str = StrictField(..., description="Description of the entry.")
 
-    properties: Dict[str, EntryInfoProperty] = Field(
+    properties: Dict[str, EntryInfoProperty] = StrictField(
         ...,
         description="A dictionary describing queryable properties for this entry type, where each key is a property name.",
     )
 
-    output_fields_by_format: Dict[str, List[str]] = Field(
+    output_fields_by_format: Dict[str, List[str]] = StrictField(
         ...,
         description="Dictionary of available output fields for this entry type, where the keys are the values of the `formats` list and the values are the keys of the `properties` dictionary.",
     )

optimade/models/index_metadb.py

@@ -6,6 +6,7 @@
 
 from optimade.models.jsonapi import BaseResource
 from optimade.models.baseinfo import BaseInfoAttributes, BaseInfoResource
+from optimade.models.utils import StrictField
 
 
 __all__ = (
@@ -25,7 +26,7 @@ class DefaultRelationship(Enum):
 class IndexInfoAttributes(BaseInfoAttributes):
     """Attributes for Base URL Info endpoint for an Index Meta-Database"""
 
-    is_index: bool = Field(
+    is_index: bool = StrictField(
         True,
         const=True,
         description="This must be `true` since this is an index meta-database (see section Index Meta-Database).",
@@ -35,13 +36,13 @@ class IndexInfoAttributes(BaseInfoAttributes):
 class RelatedLinksResource(BaseResource):
     """A related Links resource object"""
 
-    type: str = Field("links", const="links", pattern="^links$")
+    type: str = Field("links", const="links", regex="^links$")
 
 
 class IndexRelationship(BaseModel):
     """Index Meta-Database relationship"""
 
-    data: Union[None, RelatedLinksResource] = Field(
+    data: Union[None, RelatedLinksResource] = StrictField(
         ...,
         description="""[JSON API resource linkage](http://jsonapi.org/format/1.0/#document-links).
 It MUST be either `null` or contain a single Links identifier object with the fields `id` and `type`""",
@@ -52,7 +53,9 @@ class IndexInfoResource(BaseInfoResource):
     """Index Meta-Database Base URL Info endpoint resource"""
 
     attributes: IndexInfoAttributes = Field(...)
-    relationships: Union[None, Dict[DefaultRelationship, IndexRelationship]] = Field(
+    relationships: Union[
+        None, Dict[DefaultRelationship, IndexRelationship]
+    ] = StrictField(
         ...,
         description="""Reference to the Links identifier object under the `links` endpoint that the provider has chosen as their 'default' OPTIMADE API database.
 A client SHOULD present this database as the first choice when an end-user chooses this provider.""",