OPTIMADE Data Models

This page provides documentation for the optimade.models submodule, where all the OPTIMADE (and JSON:API)-defined data models are located.

For example, the three OPTIMADE entry types, structures, references and links, are defined primarily through the corresponding attribute models:

• StructureResourceAttributes
• ReferenceResourceAttributes
• LinksResourceAttributes

As well as validating data types when creating instances of these models, this package defines several OPTIMADE-specific validators that ensure consistency between fields (e.g., the value of nsites matches the number of positions provided in cartesian_site_positions).

baseinfo

AvailableApiVersion (BaseModel) pydantic-model

A JSON object containing information about an available API version

Source code in optimade/models/baseinfo.py

class AvailableApiVersion(BaseModel):
    """A JSON object containing information about an available API version"""

    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 = 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'.
Examples: `1.0.0`, `1.0.0-rc.2`.""",
    )

    @validator("url")
    def url_must_be_versioned_base_url(cls, v):
        """The URL must be a valid versioned Base URL"""
        if not re.match(r".+/v[0-1](\.[0-9]+)*/?$", v):
            raise ValueError(f"url MUST be a versioned base URL. It is: {v}")
        return v

    @root_validator(pre=False, skip_on_failure=True)
    def crosscheck_url_and_version(cls, values):
        """Check that URL version and API version are compatible."""
        url_version = (
            values["url"]
            .split("/")[-2 if values["url"].endswith("/") else -1]
            .replace("v", "")
        )
        # as with version urls, we need to split any release tags or build metadata out of these URLs
        url_version = tuple(
            int(val) for val in url_version.split("-")[0].split("+")[0].split(".")
        )
        api_version = tuple(
            int(val) for val in values["version"].split("-")[0].split("+")[0].split(".")
        )
        if any(a != b for a, b in zip(url_version, api_version)):
            raise ValueError(
                f"API version {api_version} is not compatible with url version {url_version}."
            )
        return values

url: AnyHttpUrl pydantic-field required

A string specifying a versioned base URL that MUST adhere to the rules in section Base URL

version: SemanticVersion pydantic-field required

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'. Examples: 1.0.0, 1.0.0-rc.2.

crosscheck_url_and_version(values) classmethod

Check that URL version and API version are compatible.

Source code in optimade/models/baseinfo.py

@root_validator(pre=False, skip_on_failure=True)
def crosscheck_url_and_version(cls, values):
    """Check that URL version and API version are compatible."""
    url_version = (
        values["url"]
        .split("/")[-2 if values["url"].endswith("/") else -1]
        .replace("v", "")
    )
    # as with version urls, we need to split any release tags or build metadata out of these URLs
    url_version = tuple(
        int(val) for val in url_version.split("-")[0].split("+")[0].split(".")
    )
    api_version = tuple(
        int(val) for val in values["version"].split("-")[0].split("+")[0].split(".")
    )
    if any(a != b for a, b in zip(url_version, api_version)):
        raise ValueError(
            f"API version {api_version} is not compatible with url version {url_version}."
        )
    return values

url_must_be_versioned_base_url(v) classmethod

The URL must be a valid versioned Base URL

Source code in optimade/models/baseinfo.py

@validator("url")
def url_must_be_versioned_base_url(cls, v):
    """The URL must be a valid versioned Base URL"""
    if not re.match(r".+/v[0-1](\.[0-9]+)*/?$", v):
        raise ValueError(f"url MUST be a versioned base URL. It is: {v}")
    return v

BaseInfoAttributes (BaseModel) pydantic-model

Attributes for Base URL Info endpoint

Source code in optimade/models/baseinfo.py

class BaseInfoAttributes(BaseModel):
    """Attributes for Base URL Info endpoint"""

    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] = StrictField(
        ...,
        description="A list of dictionaries of available API versions at other base URLs",
    )
    formats: list[str] = StrictField(
        default=["json"], description="List of available output formats."
    )
    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]] = StrictField(
        ..., description="Available entry endpoints as a function of output formats."
    )
    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 "
        "(i.e., the default is for `is_index` to be `false`).",
    )

    @validator("entry_types_by_format", check_fields=False)
    def formats_and_endpoints_must_be_valid(cls, v, values):
        for format_, endpoints in v.items():
            if format_ not in values["formats"]:
                raise ValueError(f"'{format_}' must be listed in formats to be valid")
            for endpoint in endpoints:
                if endpoint not in values["available_endpoints"]:
                    raise ValueError(
                        f"'{endpoint}' must be listed in available_endpoints to be valid"
                    )
        return v

api_version: SemanticVersion pydantic-field required

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 pydantic-field required

A list of dictionaries of available API versions at other base URLs

available_endpoints: list pydantic-field required

List of available endpoints (i.e., the string to be appended to the versioned base URL).

entry_types_by_format: dict pydantic-field required

Available entry endpoints as a function of output formats.

formats: list pydantic-field

List of available output formats.

is_index: bool pydantic-field

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 (i.e., the default is for is_index to be false).

entries

EntryInfoProperty (BaseModel) pydantic-model

Source code in optimade/models/entries.py

class EntryInfoProperty(BaseModel):
    description: str = StrictField(
        ..., description="A human-readable description of the entry property"
    )

    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] = 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] = StrictField(
        None,
        title="Type",
        description="""The type of the property's value.
This MUST be any of the types defined in the Data types section.
For the purpose of compatibility with future versions of this specification, a client MUST accept values that are not `string` values specifying any of the OPTIMADE Data types, but MUST then also disregard the `type` field.
Note, if the value is a nested type, only the outermost type should be reported.
E.g., for the entry resource `structures`, the `species` property is defined as a list of dictionaries, hence its `type` value would be `list`.""",
    )

description: str pydantic-field required

A human-readable description of the entry property

sortable: bool pydantic-field

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: DataType pydantic-field

The type of the property's value. This MUST be any of the types defined in the Data types section. For the purpose of compatibility with future versions of this specification, a client MUST accept values that are not string values specifying any of the OPTIMADE Data types, but MUST then also disregard the type field. Note, if the value is a nested type, only the outermost type should be reported. E.g., for the entry resource structures, the species property is defined as a list of dictionaries, hence its type value would be list.

unit: str pydantic-field

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. It is RECOMMENDED that non-standard (non-SI) units are described in the description for the property.

EntryInfoResource (BaseModel) pydantic-model

Source code in optimade/models/entries.py

class EntryInfoResource(BaseModel):
    formats: list[str] = StrictField(
        ..., description="List of output formats available for this type of entry."
    )

    description: str = StrictField(..., description="Description of the entry.")

    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]] = 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.",
    )

description: str pydantic-field required

Description of the entry.

formats: list pydantic-field required

List of output formats available for this type of entry.

output_fields_by_format: dict pydantic-field required

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.

properties: dict pydantic-field required

A dictionary describing queryable properties for this entry type, where each key is a property name.

EntryRelationships (Relationships) pydantic-model

This model wraps the JSON API Relationships to include type-specific top level keys.

Source code in optimade/models/entries.py

class EntryRelationships(Relationships):
    """This model wraps the JSON API Relationships to include type-specific top level keys."""

    references: Optional[ReferenceRelationship] = StrictField(
        None,
        description="Object containing links to relationships with entries of the `references` type.",
    )

    structures: Optional[StructureRelationship] = StrictField(
        None,
        description="Object containing links to relationships with entries of the `structures` type.",
    )

references: ReferenceRelationship pydantic-field

Object containing links to relationships with entries of the references type.

structures: StructureRelationship pydantic-field

Object containing links to relationships with entries of the structures type.

EntryResource (Resource) pydantic-model

The base model for an entry resource.

Source code in optimade/models/entries.py

class EntryResource(Resource):
    """The base model for an entry resource."""

    id: str = OptimadeField(
        ...,
        description="""An entry's ID as defined in section Definition of Terms.

- **Type**: string.

- **Requirements/Conventions**:
    - **Support**: MUST be supported by all implementations, MUST NOT be `null`.
    - **Query**: MUST be a queryable property with support for all mandatory filter features.
    - **Response**: REQUIRED in the response.

- **Examples**:
    - `"db/1234567"`
    - `"cod/2000000"`
    - `"cod/2000000@1234567"`
    - `"nomad/L1234567890"`
    - `"42"`""",
        support=SupportLevel.MUST,
        queryable=SupportLevel.MUST,
    )

    type: str = OptimadeField(
        description="""The name of the type of an entry.

- **Type**: string.

- **Requirements/Conventions**:
    - **Support**: MUST be supported by all implementations, MUST NOT be `null`.
    - **Query**: MUST be a queryable property with support for all mandatory filter features.
    - **Response**: REQUIRED in the response.
    - MUST be an existing entry type.
    - 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 = 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] = 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.""",
    )

EntryResourceAttributes (Attributes) pydantic-model

Contains key-value pairs representing the entry's properties.

Source code in optimade/models/entries.py

class EntryResourceAttributes(Attributes):
    """Contains key-value pairs representing the entry's properties."""

    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.

- **Type**: string.

- **Requirements/Conventions**:
    - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.
    - **Query**: MUST be a queryable property with support for all mandatory filter features.

- **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: Optional[datetime] = OptimadeField(
        ...,
        description="""Date and time representing when the entry was last modified.

- **Type**: timestamp.

- **Requirements/Conventions**:
    - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.
    - **Query**: MUST be a queryable property with support for all mandatory filter features.
    - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.

- **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,
    )

    @validator("immutable_id", pre=True)
    def cast_immutable_id_to_str(cls, value):
        """Convenience validator for casting `immutable_id` to a string."""
        if value is not None and not isinstance(value, str):
            value = str(value)

        return value

immutable_id: str pydantic-field

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.

• Type: string.

• Requirements/Conventions:

  • Support: OPTIONAL support in implementations, i.e., MAY be null.
  • Query: MUST be a queryable property with support for all mandatory filter features.

• Examples:

  • "8bd3e750-b477-41a0-9b11-3a799f21b44f"
  • "fjeiwoj,54;@=%<>#32" (Strings that are not URL-safe are allowed.)

last_modified: datetime pydantic-field required

Date and time representing when the entry was last modified.

• Type: timestamp.

• Requirements/Conventions:

  • Support: SHOULD be supported by all implementations, i.e., SHOULD NOT be null.
  • Query: MUST be a queryable property with support for all mandatory filter features.
  • Response: REQUIRED in the response unless the query parameter response_fields is present and does not include this property.

• Example:

  • As part of JSON response format: "2007-04-05T14:30:20Z" (i.e., encoded as an RFC 3339 Internet Date/Time Format string.)

cast_immutable_id_to_str(value) classmethod

Convenience validator for casting immutable_id to a string.

Source code in optimade/models/entries.py

@validator("immutable_id", pre=True)
def cast_immutable_id_to_str(cls, value):
    """Convenience validator for casting `immutable_id` to a string."""
    if value is not None and not isinstance(value, str):
        value = str(value)

    return value

index_metadb

DefaultRelationship (Enum)

Enumeration of key(s) for relationship dictionary in IndexInfoResource

Source code in optimade/models/index_metadb.py

class DefaultRelationship(Enum):
    """Enumeration of key(s) for relationship dictionary in IndexInfoResource"""

    DEFAULT = "default"

IndexInfoAttributes (BaseInfoAttributes) pydantic-model

Attributes for Base URL Info endpoint for an Index Meta-Database

Source code in optimade/models/index_metadb.py

class IndexInfoAttributes(BaseInfoAttributes):
    """Attributes for Base URL Info endpoint for an Index Meta-Database"""

    is_index: bool = StrictField(
        True,
        description="This must be `true` since this is an index meta-database (see section Index Meta-Database).",
    )

IndexInfoResource (BaseInfoResource) pydantic-model

Index Meta-Database Base URL Info endpoint resource

Source code in optimade/models/index_metadb.py

class IndexInfoResource(BaseInfoResource):
    """Index Meta-Database Base URL Info endpoint resource"""

    attributes: IndexInfoAttributes = Field(...)
    relationships: Union[
        None, dict[DefaultRelationship, IndexRelationship]
    ] = StrictField(  # type: ignore[assignment]
        ...,
        title="Relationships",
        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.""",
    )

IndexRelationship (BaseModel) pydantic-model

Index Meta-Database relationship

Source code in optimade/models/index_metadb.py

class IndexRelationship(BaseModel):
    """Index Meta-Database relationship"""

    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`""",
    )

data: RelatedLinksResource pydantic-field required

JSON API resource linkage. It MUST be either null or contain a single Links identifier object with the fields id and type

RelatedLinksResource (BaseResource) pydantic-model

A related Links resource object

Source code in optimade/models/index_metadb.py

class RelatedLinksResource(BaseResource):
    """A related Links resource object"""

    type: str = Field("links", regex="^links$")

jsonapi

This module should reproduce JSON API v1.0 https://jsonapi.org/format/1.0/

Attributes (BaseModel) pydantic-model

Members of the attributes object ("attributes") represent information about the resource object in which it's defined. The keys for Attributes MUST NOT be: relationships links id type

Source code in optimade/models/jsonapi.py

class Attributes(BaseModel):
    """
    Members of the attributes object ("attributes\") represent information about the resource object in which it's defined.
    The keys for Attributes MUST NOT be:
        relationships
        links
        id
        type
    """

    class Config:
        extra = "allow"

    @root_validator(pre=True)
    def check_illegal_attributes_fields(cls, values):
        illegal_fields = ("relationships", "links", "id", "type")
        for field in illegal_fields:
            if field in values:
                raise ValueError(
                    f"{illegal_fields} MUST NOT be fields under Attributes"
                )
        return values

BaseResource (BaseModel) pydantic-model

Minimum requirements to represent a Resource

Source code in optimade/models/jsonapi.py

class BaseResource(BaseModel):
    """Minimum requirements to represent a Resource"""

    id: str = StrictField(..., description="Resource ID")
    type: str = StrictField(..., description="Resource type")

    class Config:
        @staticmethod
        def schema_extra(schema: dict[str, Any], model: type["BaseResource"]) -> None:
            """Ensure `id` and `type` are the first two entries in the list required properties.

            Note:
                This _requires_ that `id` and `type` are the _first_ model fields defined
                for all sub-models of `BaseResource`.

            """
            if "id" not in schema.get("required", []):
                schema["required"] = ["id"] + schema.get("required", [])
            if "type" not in schema.get("required", []):
                required = []
                for field in schema.get("required", []):
                    required.append(field)
                    if field == "id":
                        # To make sure the property order match the listed properties,
                        # this ensures "type" is added immediately after "id".
                        required.append("type")
                schema["required"] = required

id: str pydantic-field required

Resource ID

type: str pydantic-field required

Resource type

Config

Source code in optimade/models/jsonapi.py

class Config:
    @staticmethod
    def schema_extra(schema: dict[str, Any], model: type["BaseResource"]) -> None:
        """Ensure `id` and `type` are the first two entries in the list required properties.

        Note:
            This _requires_ that `id` and `type` are the _first_ model fields defined
            for all sub-models of `BaseResource`.

        """
        if "id" not in schema.get("required", []):
            schema["required"] = ["id"] + schema.get("required", [])
        if "type" not in schema.get("required", []):
            required = []
            for field in schema.get("required", []):
                required.append(field)
                if field == "id":
                    # To make sure the property order match the listed properties,
                    # this ensures "type" is added immediately after "id".
                    required.append("type")
            schema["required"] = required

schema_extra(schema, model) staticmethod

Ensure id and type are the first two entries in the list required properties.

Note

This requires that id and type are the first model fields defined for all sub-models of BaseResource.

Source code in optimade/models/jsonapi.py

@staticmethod
def schema_extra(schema: dict[str, Any], model: type["BaseResource"]) -> None:
    """Ensure `id` and `type` are the first two entries in the list required properties.

    Note:
        This _requires_ that `id` and `type` are the _first_ model fields defined
        for all sub-models of `BaseResource`.

    """
    if "id" not in schema.get("required", []):
        schema["required"] = ["id"] + schema.get("required", [])
    if "type" not in schema.get("required", []):
        required = []
        for field in schema.get("required", []):
            required.append(field)
            if field == "id":
                # To make sure the property order match the listed properties,
                # this ensures "type" is added immediately after "id".
                required.append("type")
        schema["required"] = required

Error (BaseModel) pydantic-model

An error response

Source code in optimade/models/jsonapi.py

class Error(BaseModel):
    """An error response"""

    id: Optional[str] = StrictField(
        None,
        description="A unique identifier for this particular occurrence of the problem.",
    )
    links: Optional[ErrorLinks] = StrictField(
        None, description="A links object storing about"
    )
    status: Optional[str] = StrictField(
        None,
        description="the HTTP status code applicable to this problem, expressed as a string value.",
    )
    code: Optional[str] = StrictField(
        None,
        description="an application-specific error code, expressed as a string value.",
    )
    title: Optional[str] = StrictField(
        None,
        description="A short, human-readable summary of the problem. "
        "It **SHOULD NOT** change from occurrence to occurrence of the problem, except for purposes of localization.",
    )
    detail: Optional[str] = StrictField(
        None,
        description="A human-readable explanation specific to this occurrence of the problem.",
    )
    source: Optional[ErrorSource] = StrictField(
        None, description="An object containing references to the source of the error"
    )
    meta: Optional[Meta] = StrictField(
        None,
        description="a meta object containing non-standard meta-information about the error.",
    )

    def __hash__(self):
        return hash(self.json())

code: str pydantic-field

an application-specific error code, expressed as a string value.

detail: str pydantic-field

A human-readable explanation specific to this occurrence of the problem.

id: str pydantic-field

A unique identifier for this particular occurrence of the problem.

links: ErrorLinks pydantic-field

A links object storing about

meta: Meta pydantic-field

a meta object containing non-standard meta-information about the error.

source: ErrorSource pydantic-field

An object containing references to the source of the error

status: str pydantic-field

the HTTP status code applicable to this problem, expressed as a string value.

title: str pydantic-field

A short, human-readable summary of the problem. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.

__hash__(self) special

Return hash(self).

Source code in optimade/models/jsonapi.py

def __hash__(self):
    return hash(self.json())

ErrorLinks (BaseModel) pydantic-model

A Links object specific to Error objects

Source code in optimade/models/jsonapi.py

class ErrorLinks(BaseModel):
    """A Links object specific to Error objects"""

    about: Optional[Union[AnyUrl, Link]] = StrictField(
        None,
        description="A link that leads to further details about this particular occurrence of the problem.",
    )

about: Union[pydantic.networks.AnyUrl, optimade.models.jsonapi.Link] pydantic-field

A link that leads to further details about this particular occurrence of the problem.

ErrorSource (BaseModel) pydantic-model

an object containing references to the source of the error

Source code in optimade/models/jsonapi.py

class ErrorSource(BaseModel):
    """an object containing references to the source of the error"""

    pointer: Optional[str] = StrictField(
        None,
        description="a JSON Pointer [RFC6901] to the associated entity in the request document "
        '[e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute].',
    )
    parameter: Optional[str] = StrictField(
        None,
        description="a string indicating which URI query parameter caused the error.",
    )

parameter: str pydantic-field

a string indicating which URI query parameter caused the error.

pointer: str pydantic-field

a JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute].

JsonApi (BaseModel) pydantic-model

An object describing the server's implementation

Source code in optimade/models/jsonapi.py

class JsonApi(BaseModel):
    """An object describing the server's implementation"""

    version: str = StrictField(
        default="1.0", description="Version of the json API used"
    )
    meta: Optional[Meta] = StrictField(
        None, description="Non-standard meta information"
    )

meta: Meta pydantic-field

Non-standard meta information

version: str pydantic-field

Version of the json API used

Link (BaseModel) pydantic-model

A link MUST be represented as either: a string containing the link's URL or a link object.

Source code in optimade/models/jsonapi.py

class Link(BaseModel):
    """A link **MUST** be represented as either: a string containing the link's URL or a link object."""

    href: AnyUrl = StrictField(..., description="a string containing the link’s URL.")
    meta: Optional[Meta] = StrictField(
        None,
        description="a meta object containing non-standard meta-information about the link.",
    )

href: AnyUrl pydantic-field required

a string containing the link’s URL.

meta: Meta pydantic-field

a meta object containing non-standard meta-information about the link.

Meta (BaseModel) pydantic-model

Non-standard meta-information that can not be represented as an attribute or relationship.

Source code in optimade/models/jsonapi.py

class Meta(BaseModel):
    """Non-standard meta-information that can not be represented as an attribute or relationship."""

    class Config:
        extra = "allow"

Relationship (BaseModel) pydantic-model

Representation references from the resource object in which it’s defined to other resource objects.

Source code in optimade/models/jsonapi.py

class Relationship(BaseModel):
    """Representation references from the resource object in which it’s defined to other resource objects."""

    links: Optional[RelationshipLinks] = StrictField(
        None,
        description="a links object containing at least one of the following: self, related",
    )
    data: Optional[Union[BaseResource, list[BaseResource]]] = StrictField(
        None, description="Resource linkage"
    )
    meta: Optional[Meta] = StrictField(
        None,
        description="a meta object that contains non-standard meta-information about the relationship.",
    )

    @root_validator(pre=True)
    def at_least_one_relationship_key_must_be_set(cls, values):
        for value in values.values():
            if value is not None:
                break
        else:
            raise ValueError(
                "Either 'links', 'data', or 'meta' MUST be specified for Relationship"
            )
        return values

data: Union[optimade.models.jsonapi.BaseResource, list[optimade.models.jsonapi.BaseResource]] pydantic-field

Resource linkage

links: RelationshipLinks pydantic-field

a links object containing at least one of the following: self, related

meta: Meta pydantic-field

a meta object that contains non-standard meta-information about the relationship.

RelationshipLinks (BaseModel) pydantic-model

A resource object MAY contain references to other resource objects ("relationships"). Relationships may be to-one or to-many. Relationships can be specified by including a member in a resource's links object.

Source code in optimade/models/jsonapi.py

class RelationshipLinks(BaseModel):
    """A resource object **MAY** contain references to other resource objects ("relationships").
    Relationships may be to-one or to-many.
    Relationships can be specified by including a member in a resource's links object.

    """

    self: Optional[Union[AnyUrl, Link]] = StrictField(
        None,
        description="""A link for the relationship itself (a 'relationship link').
This link allows the client to directly manipulate the relationship.
When fetched successfully, this link returns the [linkage](https://jsonapi.org/format/1.0/#document-resource-object-linkage) for the related resources as its primary data.
(See [Fetching Relationships](https://jsonapi.org/format/1.0/#fetching-relationships).)""",
    )
    related: Optional[Union[AnyUrl, Link]] = StrictField(
        None,
        description="A [related resource link](https://jsonapi.org/format/1.0/#document-resource-object-related-resource-links).",
    )

    @root_validator(pre=True)
    def either_self_or_related_must_be_specified(cls, values):
        for value in values.values():
            if value is not None:
                break
        else:
            raise ValueError(
                "Either 'self' or 'related' MUST be specified for RelationshipLinks"
            )
        return values

related: Union[pydantic.networks.AnyUrl, optimade.models.jsonapi.Link] pydantic-field

A related resource link.

self: Union[pydantic.networks.AnyUrl, optimade.models.jsonapi.Link] pydantic-field

A link for the relationship itself (a 'relationship link'). This link allows the client to directly manipulate the relationship. When fetched successfully, this link returns the linkage for the related resources as its primary data. (See Fetching Relationships.)

Relationships (BaseModel) pydantic-model

Members of the relationships object ("relationships") represent references from the resource object in which it's defined to other resource objects. Keys MUST NOT be: type id

Source code in optimade/models/jsonapi.py

class Relationships(BaseModel):
    """
    Members of the relationships object (\"relationships\") represent references from the resource object in which it's defined to other resource objects.
    Keys MUST NOT be:
        type
        id
    """

    @root_validator(pre=True)
    def check_illegal_relationships_fields(cls, values):
        illegal_fields = ("id", "type")
        for field in illegal_fields:
            if field in values:
                raise ValueError(
                    f"{illegal_fields} MUST NOT be fields under Relationships"
                )
        return values

Resource (BaseResource) pydantic-model

Resource objects appear in a JSON API document to represent resources.

Source code in optimade/models/jsonapi.py

class Resource(BaseResource):
    """Resource objects appear in a JSON API document to represent resources."""

    links: Optional[ResourceLinks] = StrictField(
        None, description="a links object containing links related to the resource."
    )
    meta: Optional[Meta] = StrictField(
        None,
        description="a meta object containing non-standard meta-information about a resource that can not be represented as an attribute or relationship.",
    )
    attributes: Optional[Attributes] = StrictField(
        None,
        description="an attributes object representing some of the resource’s data.",
    )
    relationships: Optional[Relationships] = StrictField(
        None,
        description="""[Relationships object](https://jsonapi.org/format/1.0/#document-resource-object-relationships)
describing relationships between the resource and other JSON API resources.""",
    )

attributes: Attributes pydantic-field

an attributes object representing some of the resource’s data.

links: ResourceLinks pydantic-field

a links object containing links related to the resource.

meta: Meta pydantic-field

a meta object containing non-standard meta-information about a resource that can not be represented as an attribute or relationship.

relationships: Relationships pydantic-field

Relationships object describing relationships between the resource and other JSON API resources.

ResourceLinks (BaseModel) pydantic-model

A Resource Links object

Source code in optimade/models/jsonapi.py

class ResourceLinks(BaseModel):
    """A Resource Links object"""

    self: Optional[Union[AnyUrl, Link]] = StrictField(
        None,
        description="A link that identifies the resource represented by the resource object.",
    )

self: Union[pydantic.networks.AnyUrl, optimade.models.jsonapi.Link] pydantic-field

A link that identifies the resource represented by the resource object.

Response (BaseModel) pydantic-model

A top-level response

Source code in optimade/models/jsonapi.py

class Response(BaseModel):
    """A top-level response"""

    data: Optional[Union[None, Resource, list[Resource]]] = StrictField(
        None, description="Outputted Data", uniqueItems=True
    )
    meta: Optional[Meta] = StrictField(
        None,
        description="A meta object containing non-standard information related to the Success",
    )
    errors: Optional[list[Error]] = StrictField(
        None, description="A list of unique errors", uniqueItems=True
    )
    included: Optional[list[Resource]] = StrictField(
        None, description="A list of unique included resources", uniqueItems=True
    )
    links: Optional[ToplevelLinks] = StrictField(
        None, description="Links associated with the primary data or errors"
    )
    jsonapi: Optional[JsonApi] = StrictField(
        None, description="Information about the JSON API used"
    )

    @root_validator(pre=True)
    def either_data_meta_or_errors_must_be_set(cls, values):
        required_fields = ("data", "meta", "errors")
        if not any(field in values for field in required_fields):
            raise ValueError(
                f"At least one of {required_fields} MUST be specified in the top-level response"
            )
        if "errors" in values and not values.get("errors"):
            raise ValueError("Errors MUST NOT be an empty or 'null' value.")
        return values

    class Config:
        """The specification mandates that datetimes must be encoded following
        [RFC3339](https://tools.ietf.org/html/rfc3339), which does not support
        fractional seconds, thus they must be stripped in the response. This can
        cause issues when the underlying database contains fields that do include
        microseconds, as filters may return unexpected results.
        """

        json_encoders = {
            datetime: lambda v: v.astimezone(timezone.utc).strftime(
                "%Y-%m-%dT%H:%M:%SZ"
            ),
        }

data: Union[NoneType, optimade.models.jsonapi.Resource, list[optimade.models.jsonapi.Resource]] pydantic-field

Outputted Data

errors: list pydantic-field

A list of unique errors

included: list pydantic-field

A list of unique included resources

jsonapi: JsonApi pydantic-field

Information about the JSON API used

links: ToplevelLinks pydantic-field

Links associated with the primary data or errors

meta: Meta pydantic-field

A meta object containing non-standard information related to the Success

Config

The specification mandates that datetimes must be encoded following RFC3339, which does not support fractional seconds, thus they must be stripped in the response. This can cause issues when the underlying database contains fields that do include microseconds, as filters may return unexpected results.

Source code in optimade/models/jsonapi.py

class Config:
    """The specification mandates that datetimes must be encoded following
    [RFC3339](https://tools.ietf.org/html/rfc3339), which does not support
    fractional seconds, thus they must be stripped in the response. This can
    cause issues when the underlying database contains fields that do include
    microseconds, as filters may return unexpected results.
    """

    json_encoders = {
        datetime: lambda v: v.astimezone(timezone.utc).strftime(
            "%Y-%m-%dT%H:%M:%SZ"
        ),
    }

ToplevelLinks (BaseModel) pydantic-model

A set of Links objects, possibly including pagination

Source code in optimade/models/jsonapi.py

class ToplevelLinks(BaseModel):
    """A set of Links objects, possibly including pagination"""

    self: Optional[Union[AnyUrl, Link]] = StrictField(
        None, description="A link to itself"
    )
    related: Optional[Union[AnyUrl, Link]] = StrictField(
        None, description="A related resource link"
    )

    # Pagination
    first: Optional[Union[AnyUrl, Link]] = StrictField(
        None, description="The first page of data"
    )
    last: Optional[Union[AnyUrl, Link]] = StrictField(
        None, description="The last page of data"
    )
    prev: Optional[Union[AnyUrl, Link]] = StrictField(
        None, description="The previous page of data"
    )
    next: Optional[Union[AnyUrl, Link]] = StrictField(
        None, description="The next page of data"
    )

    @root_validator(pre=False)
    def check_additional_keys_are_links(cls, values):
        """The `ToplevelLinks` class allows any additional keys, as long as
        they are also Links or Urls themselves.

        """
        for key, value in values.items():
            if key not in cls.schema()["properties"]:
                values[key] = parse_obj_as(Optional[Union[AnyUrl, Link]], value)

        return values

    class Config:
        extra = "allow"

first: Union[pydantic.networks.AnyUrl, optimade.models.jsonapi.Link] pydantic-field

The first page of data

last: Union[pydantic.networks.AnyUrl, optimade.models.jsonapi.Link] pydantic-field

The last page of data

next: Union[pydantic.networks.AnyUrl, optimade.models.jsonapi.Link] pydantic-field

The next page of data

prev: Union[pydantic.networks.AnyUrl, optimade.models.jsonapi.Link] pydantic-field

The previous page of data

related: Union[pydantic.networks.AnyUrl, optimade.models.jsonapi.Link] pydantic-field

A related resource link

self: Union[pydantic.networks.AnyUrl, optimade.models.jsonapi.Link] pydantic-field

A link to itself

check_additional_keys_are_links(values) classmethod

The ToplevelLinks class allows any additional keys, as long as they are also Links or Urls themselves.

Source code in optimade/models/jsonapi.py

@root_validator(pre=False)
def check_additional_keys_are_links(cls, values):
    """The `ToplevelLinks` class allows any additional keys, as long as
    they are also Links or Urls themselves.

    """
    for key, value in values.items():
        if key not in cls.schema()["properties"]:
            values[key] = parse_obj_as(Optional[Union[AnyUrl, Link]], value)

    return values

links

Aggregate (Enum)

Enumeration of aggregate values

Source code in optimade/models/links.py

class Aggregate(Enum):
    """Enumeration of aggregate values"""

    OK = "ok"
    TEST = "test"
    STAGING = "staging"
    NO = "no"

LinkType (Enum)

Enumeration of link_type values

Source code in optimade/models/links.py

class LinkType(Enum):
    """Enumeration of link_type values"""

    CHILD = "child"
    ROOT = "root"
    EXTERNAL = "external"
    PROVIDERS = "providers"

LinksResource (EntryResource) pydantic-model

A Links endpoint resource object

Source code in optimade/models/links.py

class LinksResource(EntryResource):
    """A Links endpoint resource object"""

    type: str = StrictField(
        "links",
        description="These objects are described in detail in the section Links Endpoint",
        regex="^links$",
    )

    attributes: LinksResourceAttributes = StrictField(
        ...,
        description="A dictionary containing key-value pairs representing the Links resource's properties.",
    )

    @root_validator(pre=True)
    def relationships_must_not_be_present(cls, values):
        if values.get("relationships", None) is not None:
            raise ValueError('"relationships" is not allowed for links resources')
        return values

LinksResourceAttributes (Attributes) pydantic-model

Links endpoint resource object attributes

Source code in optimade/models/links.py

class LinksResourceAttributes(Attributes):
    """Links endpoint resource object attributes"""

    name: str = StrictField(
        ...,
        description="Human-readable name for the OPTIMADE API implementation, e.g., for use in clients to show the name to the end-user.",
    )
    description: str = StrictField(
        ...,
        description="Human-readable description for the OPTIMADE API implementation, e.g., for use in clients to show a description to the end-user.",
    )
    base_url: Optional[Union[AnyUrl, Link]] = StrictField(
        ...,
        description="JSON API links object, pointing to the base URL for this implementation",
    )

    homepage: Optional[Union[AnyUrl, Link]] = StrictField(
        ...,
        description="JSON API links object, pointing to a homepage URL for this implementation",
    )

    link_type: LinkType = StrictField(
        ...,
        title="Link Type",
        description="""The type of the linked relation.
MUST be one of these values: 'child', 'root', 'external', 'providers'.""",
    )

    aggregate: Optional[Aggregate] = StrictField(
        Aggregate.OK,
        title="Aggregate",
        description="""A string indicating whether a client that is following links to aggregate results from different OPTIMADE implementations should follow this link or not.
This flag SHOULD NOT be indicated for links where `link_type` is not `child`.

If not specified, clients MAY assume that the value is `ok`.
If specified, and the value is anything different than `ok`, the client MUST assume that the server is suggesting not to follow the link during aggregation by default (also if the value is not among the known ones, in case a future specification adds new accepted values).

Specific values indicate the reason why the server is providing the suggestion.
A client MAY follow the link anyway if it has reason to do so (e.g., if the client is looking for all test databases, it MAY follow the links marked with `aggregate`=`test`).

If specified, it MUST be one of the values listed in section Link Aggregate Options.""",
    )

    no_aggregate_reason: Optional[str] = StrictField(
        None,
        description="""An OPTIONAL human-readable string indicating the reason for suggesting not to aggregate results following the link.
It SHOULD NOT be present if `aggregate`=`ok`.""",
    )

aggregate: Aggregate pydantic-field

A string indicating whether a client that is following links to aggregate results from different OPTIMADE implementations should follow this link or not. This flag SHOULD NOT be indicated for links where link_type is not child.

If not specified, clients MAY assume that the value is ok. If specified, and the value is anything different than ok, the client MUST assume that the server is suggesting not to follow the link during aggregation by default (also if the value is not among the known ones, in case a future specification adds new accepted values).

Specific values indicate the reason why the server is providing the suggestion. A client MAY follow the link anyway if it has reason to do so (e.g., if the client is looking for all test databases, it MAY follow the links marked with aggregate=test).

If specified, it MUST be one of the values listed in section Link Aggregate Options.

base_url: Union[pydantic.networks.AnyUrl, optimade.models.jsonapi.Link] pydantic-field required

JSON API links object, pointing to the base URL for this implementation

description: str pydantic-field required

Human-readable description for the OPTIMADE API implementation, e.g., for use in clients to show a description to the end-user.

homepage: Union[pydantic.networks.AnyUrl, optimade.models.jsonapi.Link] pydantic-field required

JSON API links object, pointing to a homepage URL for this implementation

link_type: LinkType pydantic-field required

The type of the linked relation. MUST be one of these values: 'child', 'root', 'external', 'providers'.

name: str pydantic-field required

Human-readable name for the OPTIMADE API implementation, e.g., for use in clients to show the name to the end-user.

no_aggregate_reason: str pydantic-field

An OPTIONAL human-readable string indicating the reason for suggesting not to aggregate results following the link. It SHOULD NOT be present if aggregate=ok.

optimade_json

Modified JSON API v1.0 for OPTIMADE API

BaseRelationshipMeta (Meta) pydantic-model

Specific meta field for base relationship resource

Source code in optimade/models/optimade_json.py

class BaseRelationshipMeta(jsonapi.Meta):
    """Specific meta field for base relationship resource"""

    description: str = StrictField(
        ..., description="OPTIONAL human-readable description of the relationship."
    )

description: str pydantic-field required

OPTIONAL human-readable description of the relationship.

BaseRelationshipResource (BaseResource) pydantic-model

Minimum requirements to represent a relationship resource

Source code in optimade/models/optimade_json.py

class BaseRelationshipResource(jsonapi.BaseResource):
    """Minimum requirements to represent a relationship resource"""

    meta: Optional[BaseRelationshipMeta] = StrictField(
        None,
        description="Relationship meta field. MUST contain 'description' if supplied.",
    )

meta: BaseRelationshipMeta pydantic-field

Relationship meta field. MUST contain 'description' if supplied.

DataType (Enum)

Optimade Data Types

See the section "Data types" in the OPTIMADE API specification for more information.

Source code in optimade/models/optimade_json.py

class DataType(Enum):
    """Optimade Data Types

    See the section "Data types" in the OPTIMADE API specification for more information.
    """

    STRING = "string"
    INTEGER = "integer"
    FLOAT = "float"
    BOOLEAN = "boolean"
    TIMESTAMP = "timestamp"
    LIST = "list"
    DICTIONARY = "dictionary"
    UNKNOWN = "unknown"

    @classmethod
    def get_values(cls):
        """Get OPTIMADE data types (enum values) as a (sorted) list"""
        return sorted(_.value for _ in cls)

    @classmethod
    def from_python_type(cls, python_type: Union[type, str, object]):
        """Get OPTIMADE data type from a Python type"""
        mapping = {
            "bool": cls.BOOLEAN,
            "int": cls.INTEGER,
            "float": cls.FLOAT,
            "complex": None,
            "generator": cls.LIST,
            "list": cls.LIST,
            "tuple": cls.LIST,
            "range": cls.LIST,
            "hash": cls.INTEGER,
            "str": cls.STRING,
            "bytes": cls.STRING,
            "bytearray": None,
            "memoryview": None,
            "set": cls.LIST,
            "frozenset": cls.LIST,
            "dict": cls.DICTIONARY,
            "dict_keys": cls.LIST,
            "dict_values": cls.LIST,
            "dict_items": cls.LIST,
            "NoneType": cls.UNKNOWN,
            "None": cls.UNKNOWN,
            "datetime": cls.TIMESTAMP,
            "date": cls.TIMESTAMP,
            "time": cls.TIMESTAMP,
            "datetime.datetime": cls.TIMESTAMP,
            "datetime.date": cls.TIMESTAMP,
            "datetime.time": cls.TIMESTAMP,
        }

        if isinstance(python_type, type):
            python_type = python_type.__name__
        elif isinstance(python_type, object):
            if str(python_type) in mapping:
                python_type = str(python_type)
            else:
                python_type = type(python_type).__name__

        return mapping.get(python_type, None)

    @classmethod
    def from_json_type(cls, json_type: str):
        """Get OPTIMADE data type from a named JSON type"""
        mapping = {
            "string": cls.STRING,
            "integer": cls.INTEGER,
            "number": cls.FLOAT,  # actually includes both integer and float
            "object": cls.DICTIONARY,
            "array": cls.LIST,
            "boolean": cls.BOOLEAN,
            "null": cls.UNKNOWN,
            # OpenAPI "format"s:
            "double": cls.FLOAT,
            "float": cls.FLOAT,
            "int32": cls.INTEGER,
            "int64": cls.INTEGER,
            "date": cls.TIMESTAMP,
            "date-time": cls.TIMESTAMP,
            "password": cls.STRING,
            "byte": cls.STRING,
            "binary": cls.STRING,
            # Non-OpenAPI "format"s, but may still be used by pydantic/FastAPI
            "email": cls.STRING,
            "uuid": cls.STRING,
            "uri": cls.STRING,
            "hostname": cls.STRING,
            "ipv4": cls.STRING,
            "ipv6": cls.STRING,
        }

        return mapping.get(json_type, None)

Implementation (BaseModel) pydantic-model

Information on the server implementation

Source code in optimade/models/optimade_json.py

class Implementation(BaseModel):
    """Information on the server implementation"""

    name: Optional[str] = StrictField(None, description="name of the implementation")

    version: Optional[str] = StrictField(
        None, description="version string of the current implementation"
    )

    homepage: Optional[Union[AnyHttpUrl, jsonapi.Link]] = StrictField(
        None,
        description="A [JSON API links object](http://jsonapi.org/format/1.0/#document-links) pointing to the homepage of the implementation.",
    )

    source_url: Optional[Union[AnyUrl, jsonapi.Link]] = StrictField(
        None,
        description="A [JSON API links object](http://jsonapi.org/format/1.0/#document-links) pointing to the implementation source, either downloadable archive or version control system.",
    )

    maintainer: Optional[ImplementationMaintainer] = StrictField(
        None,
        description="A dictionary providing details about the maintainer of the implementation.",
    )

    issue_tracker: Optional[Union[AnyUrl, jsonapi.Link]] = StrictField(
        None,
        description="A [JSON API links object](http://jsonapi.org/format/1.0/#document-links) pointing to the implementation's issue tracker.",
    )

homepage: Union[pydantic.networks.AnyHttpUrl, optimade.models.jsonapi.Link] pydantic-field

A JSON API links object pointing to the homepage of the implementation.

issue_tracker: Union[pydantic.networks.AnyUrl, optimade.models.jsonapi.Link] pydantic-field

A JSON API links object pointing to the implementation's issue tracker.

maintainer: ImplementationMaintainer pydantic-field

A dictionary providing details about the maintainer of the implementation.

name: str pydantic-field

name of the implementation

source_url: Union[pydantic.networks.AnyUrl, optimade.models.jsonapi.Link] pydantic-field

A JSON API links object pointing to the implementation source, either downloadable archive or version control system.

version: str pydantic-field

version string of the current implementation

ImplementationMaintainer (BaseModel) pydantic-model

Details about the maintainer of the implementation

Source code in optimade/models/optimade_json.py

class ImplementationMaintainer(BaseModel):
    """Details about the maintainer of the implementation"""

    email: EmailStr = StrictField(..., description="the maintainer's email address")

email: EmailStr pydantic-field required

the maintainer's email address

OptimadeError (Error) pydantic-model

detail MUST be present

Source code in optimade/models/optimade_json.py

class OptimadeError(jsonapi.Error):
    """detail MUST be present"""

    detail: str = StrictField(
        ...,
        description="A human-readable explanation specific to this occurrence of the problem.",
    )

Provider (BaseModel) pydantic-model

Information on the database provider of the implementation.

Source code in optimade/models/optimade_json.py

class Provider(BaseModel):
    """Information on the database provider of the implementation."""

    name: str = StrictField(..., description="a short name for the database provider")

    description: str = StrictField(
        ..., description="a longer description of the database provider"
    )

    prefix: str = StrictField(
        ...,
        regex=r"^[a-z]([a-z]|[0-9]|_)*$",
        description="database-provider-specific prefix as found in section Database-Provider-Specific Namespace Prefixes.",
    )

    homepage: Optional[Union[AnyHttpUrl, jsonapi.Link]] = StrictField(
        None,
        description="a [JSON API links object](http://jsonapi.org/format/1.0#document-links) "
        "pointing to homepage of the database provider, either "
        "directly as a string, or as a link object.",
    )

description: str pydantic-field required

a longer description of the database provider

homepage: Union[pydantic.networks.AnyHttpUrl, optimade.models.jsonapi.Link] pydantic-field

a JSON API links object pointing to homepage of the database provider, either directly as a string, or as a link object.

name: str pydantic-field required

a short name for the database provider

prefix: ConstrainedStrValue pydantic-field required

database-provider-specific prefix as found in section Database-Provider-Specific Namespace Prefixes.

Relationship (Relationship) pydantic-model

Similar to normal JSON API relationship, but with addition of OPTIONAL meta field for a resource.

Source code in optimade/models/optimade_json.py

class Relationship(jsonapi.Relationship):
    """Similar to normal JSON API relationship, but with addition of OPTIONAL meta field for a resource."""

    data: Optional[
        Union[BaseRelationshipResource, list[BaseRelationshipResource]]
    ] = StrictField(None, description="Resource linkage", uniqueItems=True)

ResponseMeta (Meta) pydantic-model

A JSON API meta member that contains JSON API meta objects of non-standard meta-information.

OPTIONAL additional information global to the query that is not specified in this document, MUST start with a database-provider-specific prefix.

Source code in optimade/models/optimade_json.py

class ResponseMeta(jsonapi.Meta):
    """
    A [JSON API meta member](https://jsonapi.org/format/1.0#document-meta)
    that contains JSON API meta objects of non-standard
    meta-information.

    OPTIONAL additional information global to the query that is not
    specified in this document, MUST start with a
    database-provider-specific prefix.
    """

    query: ResponseMetaQuery = StrictField(
        ..., description="Information on the Query that was requested"
    )

    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`.""",
    )

    more_data_available: bool = StrictField(
        ...,
        description="`false` if the response contains all data for the request (e.g., a request issued to a single entry endpoint, or a `filter` query at the last page of a paginated response) and `true` if the response is incomplete in the sense that multiple objects match the request, and not all of them have been included in the response (e.g., a query with multiple pages that is not at the last page).",
    )

    # start of "SHOULD" fields for meta response
    optimade_schema: Optional[Union[AnyHttpUrl, jsonapi.Link]] = StrictField(
        None,
        alias="schema",
        description="""A [JSON API links object](http://jsonapi.org/format/1.0/#document-links) that points to a schema for the response.
If it is a string, or a dictionary containing no `meta` field, the provided URL MUST point at an [OpenAPI](https://swagger.io/specification/) schema.
It is possible that future versions of this specification allows for alternative schema types.
Hence, if the `meta` field of the JSON API links object is provided and contains a field `schema_type` that is not equal to the string `OpenAPI` the client MUST not handle failures to parse the schema or to validate the response against the schema as errors.""",
    )

    time_stamp: Optional[datetime] = StrictField(
        None,
        description="A timestamp containing the date and time at which the query was executed.",
    )

    data_returned: Optional[int] = StrictField(
        None,
        description="An integer containing the total number of data resource objects returned for the current `filter` query, independent of pagination.",
        ge=0,
    )

    provider: Optional[Provider] = StrictField(
        None, description="information on the database provider of the implementation."
    )

    # start of "MAY" fields for meta response
    data_available: Optional[int] = StrictField(
        None,
        description="An integer containing the total number of data resource objects available in the database for the endpoint.",
    )

    last_id: Optional[str] = StrictField(
        None, description="a string containing the last ID returned"
    )

    response_message: Optional[str] = StrictField(
        None, description="response string from the server"
    )

    implementation: Optional[Implementation] = StrictField(
        None, description="a dictionary describing the server implementation"
    )

    warnings: Optional[list[Warnings]] = StrictField(
        None,
        description="""A list of warning resource objects representing non-critical errors or warnings.
A warning resource object is defined similarly to a [JSON API error object](http://jsonapi.org/format/1.0/#error-objects), but MUST also include the field `type`, which MUST have the value `"warning"`.
The field `detail` MUST be present and SHOULD contain a non-critical message, e.g., reporting unrecognized search attributes or deprecated features.
The field `status`, representing a HTTP response status code, MUST NOT be present for a warning resource object.
This is an exclusive field for error resource objects.""",
        uniqueItems=True,
    )

api_version: SemanticVersion pydantic-field required

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.

data_available: int pydantic-field

An integer containing the total number of data resource objects available in the database for the endpoint.

data_returned: ConstrainedIntValue pydantic-field

An integer containing the total number of data resource objects returned for the current filter query, independent of pagination.

implementation: Implementation pydantic-field

a dictionary describing the server implementation

last_id: str pydantic-field

a string containing the last ID returned

more_data_available: bool pydantic-field required

false if the response contains all data for the request (e.g., a request issued to a single entry endpoint, or a filter query at the last page of a paginated response) and true if the response is incomplete in the sense that multiple objects match the request, and not all of them have been included in the response (e.g., a query with multiple pages that is not at the last page).

optimade_schema: Union[pydantic.networks.AnyHttpUrl, optimade.models.jsonapi.Link] pydantic-field

A JSON API links object that points to a schema for the response. If it is a string, or a dictionary containing no meta field, the provided URL MUST point at an OpenAPI schema. It is possible that future versions of this specification allows for alternative schema types. Hence, if the meta field of the JSON API links object is provided and contains a field schema_type that is not equal to the string OpenAPI the client MUST not handle failures to parse the schema or to validate the response against the schema as errors.

provider: Provider pydantic-field

information on the database provider of the implementation.

query: ResponseMetaQuery pydantic-field required

Information on the Query that was requested

response_message: str pydantic-field

response string from the server

time_stamp: datetime pydantic-field

A timestamp containing the date and time at which the query was executed.

warnings: list pydantic-field

A list of warning resource objects representing non-critical errors or warnings. A warning resource object is defined similarly to a JSON API error object, but MUST also include the field type, which MUST have the value "warning". The field detail MUST be present and SHOULD contain a non-critical message, e.g., reporting unrecognized search attributes or deprecated features. The field status, representing a HTTP response status code, MUST NOT be present for a warning resource object. This is an exclusive field for error resource objects.

ResponseMetaQuery (BaseModel) pydantic-model

Information on the query that was requested.

Source code in optimade/models/optimade_json.py

class ResponseMetaQuery(BaseModel):
    """Information on the query that was requested."""

    representation: str = StrictField(
        ...,
        description="""A string with the part of the URL following the versioned or unversioned base URL that serves the API.
Query parameters that have not been used in processing the request MAY be omitted.
In particular, if no query parameters have been involved in processing the request, the query part of the URL MAY be excluded.
Example: `/structures?filter=nelements=2`""",
    )

representation: str pydantic-field required

A string with the part of the URL following the versioned or unversioned base URL that serves the API. Query parameters that have not been used in processing the request MAY be omitted. In particular, if no query parameters have been involved in processing the request, the query part of the URL MAY be excluded. Example: /structures?filter=nelements=2

Success (Response) pydantic-model

errors are not allowed

Source code in optimade/models/optimade_json.py

class Success(jsonapi.Response):
    """errors are not allowed"""

    meta: ResponseMeta = StrictField(
        ..., description="A meta object containing non-standard information"
    )

    @root_validator(pre=True)
    def either_data_meta_or_errors_must_be_set(cls, values):
        """Overwriting the existing validation function, since 'errors' MUST NOT be set."""
        required_fields = ("data", "meta")
        if not any(field in values for field in required_fields):
            raise ValueError(
                f"At least one of {required_fields} MUST be specified in the top-level response."
            )

        # errors MUST be skipped
        if "errors" in values:
            raise ValueError("'errors' MUST be skipped for a successful response.")

        return values

either_data_meta_or_errors_must_be_set(values) classmethod

Overwriting the existing validation function, since 'errors' MUST NOT be set.

Source code in optimade/models/optimade_json.py

@root_validator(pre=True)
def either_data_meta_or_errors_must_be_set(cls, values):
    """Overwriting the existing validation function, since 'errors' MUST NOT be set."""
    required_fields = ("data", "meta")
    if not any(field in values for field in required_fields):
        raise ValueError(
            f"At least one of {required_fields} MUST be specified in the top-level response."
        )

    # errors MUST be skipped
    if "errors" in values:
        raise ValueError("'errors' MUST be skipped for a successful response.")

    return values

Warnings (OptimadeError) pydantic-model

OPTIMADE-specific warning class based on OPTIMADE-specific JSON API Error.

From the specification:

A warning resource object is defined similarly to a JSON API error object, but MUST also include the field type, which MUST have the value "warning". The field detail MUST be present and SHOULD contain a non-critical message, e.g., reporting unrecognized search attributes or deprecated features.

Note: Must be named "Warnings", since "Warning" is a built-in Python class.

Source code in optimade/models/optimade_json.py

class Warnings(OptimadeError):
    """OPTIMADE-specific warning class based on OPTIMADE-specific JSON API Error.

    From the specification:

    A warning resource object is defined similarly to a JSON API error object, but MUST also include the field type, which MUST have the value "warning".
    The field detail MUST be present and SHOULD contain a non-critical message, e.g., reporting unrecognized search attributes or deprecated features.

    Note: Must be named "Warnings", since "Warning" is a built-in Python class.

    """

    type: str = StrictField(
        "warning",
        description='Warnings must be of type "warning"',
        regex="^warning$",
    )

    @root_validator(pre=True)
    def status_must_not_be_specified(cls, values):
        if values.get("status", None) is not None:
            raise ValueError("status MUST NOT be specified for warnings")
        return values

    class Config:
        @staticmethod
        def schema_extra(schema: dict[str, Any], model: type["Warnings"]) -> None:
            """Update OpenAPI JSON schema model for `Warning`.

            * Ensure `type` is in the list required properties and in the correct place.
            * Remove `status` property.
              This property is not allowed for `Warning`, nor is it a part of the OPTIMADE
              definition of the `Warning` object.

            Note:
                Since `type` is the _last_ model field defined, it will simply be appended.

            """
            if "required" in schema:
                if "type" not in schema["required"]:
                    schema["required"].append("type")
                else:
                    schema["required"] = ["type"]
            schema.get("properties", {}).pop("status", None)

type: ConstrainedStrValue pydantic-field

Warnings must be of type "warning"

Config

Source code in optimade/models/optimade_json.py

class Config:
    @staticmethod
    def schema_extra(schema: dict[str, Any], model: type["Warnings"]) -> None:
        """Update OpenAPI JSON schema model for `Warning`.

        * Ensure `type` is in the list required properties and in the correct place.
        * Remove `status` property.
          This property is not allowed for `Warning`, nor is it a part of the OPTIMADE
          definition of the `Warning` object.

        Note:
            Since `type` is the _last_ model field defined, it will simply be appended.

        """
        if "required" in schema:
            if "type" not in schema["required"]:
                schema["required"].append("type")
            else:
                schema["required"] = ["type"]
        schema.get("properties", {}).pop("status", None)

schema_extra(schema, model) staticmethod

Update OpenAPI JSON schema model for Warning.

• Ensure type is in the list required properties and in the correct place.
• Remove status property. This property is not allowed for Warning, nor is it a part of the OPTIMADE definition of the Warning object.

Note

Since type is the last model field defined, it will simply be appended.

Source code in optimade/models/optimade_json.py

@staticmethod
def schema_extra(schema: dict[str, Any], model: type["Warnings"]) -> None:
    """Update OpenAPI JSON schema model for `Warning`.

    * Ensure `type` is in the list required properties and in the correct place.
    * Remove `status` property.
      This property is not allowed for `Warning`, nor is it a part of the OPTIMADE
      definition of the `Warning` object.

    Note:
        Since `type` is the _last_ model field defined, it will simply be appended.

    """
    if "required" in schema:
        if "type" not in schema["required"]:
            schema["required"].append("type")
        else:
            schema["required"] = ["type"]
    schema.get("properties", {}).pop("status", None)

references

Person (BaseModel) pydantic-model

A person, i.e., an author, editor or other.

Source code in optimade/models/references.py

class Person(BaseModel):
    """A person, i.e., an author, editor or other."""

    name: str = OptimadeField(
        ...,
        description="""Full name of the person, REQUIRED.""",
        support=SupportLevel.MUST,
        queryable=SupportLevel.OPTIONAL,
    )

    firstname: Optional[str] = OptimadeField(
        None,
        description="""First name of the person.""",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    lastname: Optional[str] = OptimadeField(
        None,
        description="""Last name of the person.""",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

firstname: str pydantic-field

First name of the person.

lastname: str pydantic-field

Last name of the person.

name: str pydantic-field required

Full name of the person, REQUIRED.

ReferenceResource (EntryResource) pydantic-model

The references entries describe bibliographic references.

The following properties are used to provide the bibliographic details:

• address, annote, booktitle, chapter, crossref, edition, howpublished, institution, journal, key, month, note, number, organization, pages, publisher, school, series, title, volume, year: meanings of these properties match the BibTeX specification, values are strings;
• bib_type: type of the reference, corresponding to type property in the BibTeX specification, value is string;
• authors and editors: lists of person objects which are dictionaries with the following keys:
  • name: Full name of the person, REQUIRED.
  • firstname, lastname: Parts of the person's name, OPTIONAL.
• doi and url: values are strings.
• Requirements/Conventions:
  • Support: OPTIONAL support in implementations, i.e., any of the properties MAY be null.
  • Query: Support for queries on any of these properties is OPTIONAL. If supported, filters MAY support only a subset of comparison operators.
  • Every references entry MUST contain at least one of the properties.

Source code in optimade/models/references.py

class ReferenceResource(EntryResource):
    """The `references` entries describe bibliographic references.

    The following properties are used to provide the bibliographic details:

    - **address**, **annote**, **booktitle**, **chapter**, **crossref**, **edition**, **howpublished**, **institution**, **journal**, **key**, **month**, **note**, **number**, **organization**, **pages**, **publisher**, **school**, **series**, **title**, **volume**, **year**: meanings of these properties match the [BibTeX specification](http://bibtexml.sourceforge.net/btxdoc.pdf), values are strings;
    - **bib_type**: type of the reference, corresponding to **type** property in the BibTeX specification, value is string;
    - **authors** and **editors**: lists of *person objects* which are dictionaries with the following keys:
        - **name**: Full name of the person, REQUIRED.
        - **firstname**, **lastname**: Parts of the person's name, OPTIONAL.
    - **doi** and **url**: values are strings.
    - **Requirements/Conventions**:
        - **Support**: OPTIONAL support in implementations, i.e., any of the properties MAY be `null`.
        - **Query**: Support for queries on any of these properties is OPTIONAL.
            If supported, filters MAY support only a subset of comparison operators.
        - Every references entry MUST contain at least one of the properties.

    """

    type: str = OptimadeField(
        "references",
        description="""The name of the type of an entry.
- **Type**: string.
- **Requirements/Conventions**:
    - **Support**: MUST be supported by all implementations, MUST NOT be `null`.
    - **Query**: MUST be a queryable property with support for all mandatory filter features.
    - **Response**: REQUIRED in the response.
    - MUST be an existing entry type.
    - 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"`""",
        regex="^references$",
        support=SupportLevel.MUST,
        queryable=SupportLevel.MUST,
    )
    attributes: ReferenceResourceAttributes

    @validator("attributes")
    def validate_attributes(cls, v):
        if not any(prop[1] is not None for prop in v):
            raise ValueError("reference object must have at least one field defined")
        return v

ReferenceResourceAttributes (EntryResourceAttributes) pydantic-model

Model that stores the attributes of a reference.

Many properties match the meaning described in the BibTeX specification.

Source code in optimade/models/references.py

class ReferenceResourceAttributes(EntryResourceAttributes):
    """Model that stores the attributes of a reference.

    Many properties match the meaning described in the
    [BibTeX specification](http://bibtexml.sourceforge.net/btxdoc.pdf).

    """

    authors: Optional[list[Person]] = OptimadeField(
        None,
        description="List of person objects containing the authors of the reference.",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    editors: Optional[list[Person]] = OptimadeField(
        None,
        description="List of person objects containing the editors of the reference.",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    doi: Optional[str] = OptimadeField(
        None,
        description="The digital object identifier of the reference.",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    url: Optional[AnyUrl] = OptimadeField(
        None,
        description="The URL of the reference.",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    address: Optional[str] = OptimadeField(
        None,
        description="Meaning of property matches the BiBTeX specification.",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    annote: Optional[str] = OptimadeField(
        None,
        description="Meaning of property matches the BiBTeX specification.",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    booktitle: Optional[str] = OptimadeField(
        None,
        description="Meaning of property matches the BiBTeX specification.",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    chapter: Optional[str] = OptimadeField(
        None,
        description="Meaning of property matches the BiBTeX specification.",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    crossref: Optional[str] = OptimadeField(
        None,
        description="Meaning of property matches the BiBTeX specification.",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    edition: Optional[str] = OptimadeField(
        None,
        description="Meaning of property matches the BiBTeX specification.",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    howpublished: Optional[str] = OptimadeField(
        None,
        description="Meaning of property matches the BiBTeX specification.",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    institution: Optional[str] = OptimadeField(
        None,
        description="Meaning of property matches the BiBTeX specification.",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    journal: Optional[str] = OptimadeField(
        None,
        description="Meaning of property matches the BiBTeX specification.",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    key: Optional[str] = OptimadeField(
        None,
        description="Meaning of property matches the BiBTeX specification.",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    month: Optional[str] = OptimadeField(
        None,
        description="Meaning of property matches the BiBTeX specification.",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    note: Optional[str] = OptimadeField(
        None,
        description="Meaning of property matches the BiBTeX specification.",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    number: Optional[str] = OptimadeField(
        None,
        description="Meaning of property matches the BiBTeX specification.",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    organization: Optional[str] = OptimadeField(
        None,
        description="Meaning of property matches the BiBTeX specification.",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    pages: Optional[str] = OptimadeField(
        None,
        description="Meaning of property matches the BiBTeX specification.",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    publisher: Optional[str] = OptimadeField(
        None,
        description="Meaning of property matches the BiBTeX specification.",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    school: Optional[str] = OptimadeField(
        None,
        description="Meaning of property matches the BiBTeX specification.",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    series: Optional[str] = OptimadeField(
        None,
        description="Meaning of property matches the BiBTeX specification.",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    title: Optional[str] = OptimadeField(
        None,
        description="Meaning of property matches the BiBTeX specification.",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    bib_type: Optional[str] = OptimadeField(
        None,
        description="Type of the reference, corresponding to the **type** property in the BiBTeX specification.",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    volume: Optional[str] = OptimadeField(
        None,
        description="Meaning of property matches the BiBTeX specification.",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    year: Optional[str] = OptimadeField(
        None,
        description="Meaning of property matches the BiBTeX specification.",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

address: str pydantic-field

Meaning of property matches the BiBTeX specification.

annote: str pydantic-field

Meaning of property matches the BiBTeX specification.

authors: list pydantic-field

List of person objects containing the authors of the reference.

bib_type: str pydantic-field

Type of the reference, corresponding to the type property in the BiBTeX specification.

booktitle: str pydantic-field

Meaning of property matches the BiBTeX specification.

chapter: str pydantic-field

Meaning of property matches the BiBTeX specification.

crossref: str pydantic-field

Meaning of property matches the BiBTeX specification.

doi: str pydantic-field

The digital object identifier of the reference.

edition: str pydantic-field

Meaning of property matches the BiBTeX specification.

editors: list pydantic-field

List of person objects containing the editors of the reference.

howpublished: str pydantic-field

Meaning of property matches the BiBTeX specification.

institution: str pydantic-field

Meaning of property matches the BiBTeX specification.

journal: str pydantic-field

Meaning of property matches the BiBTeX specification.

key: str pydantic-field

Meaning of property matches the BiBTeX specification.

month: str pydantic-field

Meaning of property matches the BiBTeX specification.

note: str pydantic-field

Meaning of property matches the BiBTeX specification.

number: str pydantic-field

Meaning of property matches the BiBTeX specification.

organization: str pydantic-field

Meaning of property matches the BiBTeX specification.

pages: str pydantic-field

Meaning of property matches the BiBTeX specification.

publisher: str pydantic-field

Meaning of property matches the BiBTeX specification.

school: str pydantic-field

Meaning of property matches the BiBTeX specification.

series: str pydantic-field

Meaning of property matches the BiBTeX specification.

title: str pydantic-field

Meaning of property matches the BiBTeX specification.

url: AnyUrl pydantic-field

The URL of the reference.

volume: str pydantic-field

Meaning of property matches the BiBTeX specification.

year: str pydantic-field

Meaning of property matches the BiBTeX specification.

responses

ErrorResponse (Response) pydantic-model

errors MUST be present and data MUST be skipped

Source code in optimade/models/responses.py

class ErrorResponse(Response):
    """errors MUST be present and data MUST be skipped"""

    meta: ResponseMeta = StrictField(
        ..., description="A meta object containing non-standard information."
    )
    errors: list[OptimadeError] = StrictField(
        ...,
        description="A list of OPTIMADE-specific JSON API error objects, where the field detail MUST be present.",
        uniqueItems=True,
    )

    @root_validator(pre=True)
    def data_must_be_skipped(cls, values):
        if "data" in values:
            raise ValueError("data MUST be skipped for failures reporting errors.")
        return values

structures

Assembly (BaseModel) pydantic-model

A description of groups of sites that are statistically correlated.

• Examples (for each entry of the assemblies list):
  • {"sites_in_groups": [[0], [1]], "group_probabilities: [0.3, 0.7]}: the first site and the second site never occur at the same time in the unit cell. Statistically, 30 % of the times the first site is present, while 70 % of the times the second site is present.
  • {"sites_in_groups": [[1,2], [3]], "group_probabilities: [0.3, 0.7]}: the second and third site are either present together or not present; they form the first group of atoms for this assembly. The second group is formed by the fourth site. Sites of the first group (the second and the third) are never present at the same time as the fourth site. 30 % of times sites 1 and 2 are present (and site 3 is absent); 70 % of times site 3 is present (and sites 1 and 2 are absent).

Source code in optimade/models/structures.py

class Assembly(BaseModel):
    """A description of groups of sites that are statistically correlated.

    - **Examples** (for each entry of the assemblies list):
        - `{"sites_in_groups": [[0], [1]], "group_probabilities: [0.3, 0.7]}`: the first site and the second site never occur at the same time in the unit cell.
          Statistically, 30 % of the times the first site is present, while 70 % of the times the second site is present.
        - `{"sites_in_groups": [[1,2], [3]], "group_probabilities: [0.3, 0.7]}`: the second and third site are either present together or not present; they form the first group of atoms for this assembly.
          The second group is formed by the fourth site. Sites of the first group (the second and the third) are never present at the same time as the fourth site.
          30 % of times sites 1 and 2 are present (and site 3 is absent); 70 % of times site 3 is present (and sites 1 and 2 are absent).

    """

    sites_in_groups: list[list[int]] = OptimadeField(
        ...,
        description="""Index of the sites (0-based) that belong to each group for each assembly.

- **Examples**:
    - `[[1], [2]]`: two groups, one with the second site, one with the third.
    - `[[1,2], [3]]`: one group with the second and third site, one with the fourth.""",
        support=SupportLevel.MUST,
        queryable=SupportLevel.OPTIONAL,
    )

    group_probabilities: list[float] = OptimadeField(
        ...,
        description="""Statistical probability of each group. It MUST have the same length as `sites_in_groups`.
It SHOULD sum to one.
See below for examples of how to specify the probability of the occurrence of a vacancy.
The possible reasons for the values not to sum to one are the same as already specified above for the `concentration` of each `species`.""",
        support=SupportLevel.MUST,
        queryable=SupportLevel.OPTIONAL,
    )

    @validator("sites_in_groups")
    def validate_sites_in_groups(cls, v):
        sites = []
        for group in v:
            sites.extend(group)
        if len(set(sites)) != len(sites):
            raise ValueError(
                f"A site MUST NOT appear in more than one group. Given value: {v}"
            )
        return v

    @validator("group_probabilities")
    def check_self_consistency(cls, v, values):
        if len(v) != len(values.get("sites_in_groups", [])):
            raise ValueError(
                f"sites_in_groups and group_probabilities MUST be of same length, "
                f"but are {len(values.get('sites_in_groups', []))} and {len(v)}, respectively"
            )
        return v

group_probabilities: list pydantic-field required

Statistical probability of each group. It MUST have the same length as sites_in_groups. It SHOULD sum to one. See below for examples of how to specify the probability of the occurrence of a vacancy. The possible reasons for the values not to sum to one are the same as already specified above for the concentration of each species.

sites_in_groups: list pydantic-field required

Index of the sites (0-based) that belong to each group for each assembly.

• Examples:
  • [[1], [2]]: two groups, one with the second site, one with the third.
  • [[1,2], [3]]: one group with the second and third site, one with the fourth.

Periodicity (IntEnum)

Integer enumeration of dimension_types values

Source code in optimade/models/structures.py

class Periodicity(IntEnum):
    """Integer enumeration of dimension_types values"""

    APERIODIC = 0
    PERIODIC = 1

Species (BaseModel) pydantic-model

A list describing the species of the sites of this structure.

Species can represent pure chemical elements, virtual-crystal atoms representing a statistical occupation of a given site by multiple chemical elements, and/or a location to which there are attached atoms, i.e., atoms whose precise location are unknown beyond that they are attached to that position (frequently used to indicate hydrogen atoms attached to another element, e.g., a carbon with three attached hydrogens might represent a methyl group, -CH3).

• Examples:
  • [ {"name": "Ti", "chemical_symbols": ["Ti"], "concentration": [1.0]} ]: any site with this species is occupied by a Ti atom.
  • [ {"name": "Ti", "chemical_symbols": ["Ti", "vacancy"], "concentration": [0.9, 0.1]} ]: any site with this species is occupied by a Ti atom with 90 % probability, and has a vacancy with 10 % probability.
  • [ {"name": "BaCa", "chemical_symbols": ["vacancy", "Ba", "Ca"], "concentration": [0.05, 0.45, 0.5], "mass": [0.0, 137.327, 40.078]} ]: any site with this species is occupied by a Ba atom with 45 % probability, a Ca atom with 50 % probability, and by a vacancy with 5 % probability. The mass of this site is (on average) 88.5 a.m.u.
  • [ {"name": "C12", "chemical_symbols": ["C"], "concentration": [1.0], "mass": [12.0]} ]: any site with this species is occupied by a carbon isotope with mass 12.
  • [ {"name": "C13", "chemical_symbols": ["C"], "concentration": [1.0], "mass": [13.0]} ]: any site with this species is occupied by a carbon isotope with mass 13.
  • [ {"name": "CH3", "chemical_symbols": ["C"], "concentration": [1.0], "attached": ["H"], "nattached": [3]} ]: any site with this species is occupied by a methyl group, -CH3, which is represented without specifying precise positions of the hydrogen atoms.

Source code in optimade/models/structures.py

class Species(BaseModel):
    """A list describing the species of the sites of this structure.

    Species can represent pure chemical elements, virtual-crystal atoms representing a
    statistical occupation of a given site by multiple chemical elements, and/or a
    location to which there are attached atoms, i.e., atoms whose precise location are
    unknown beyond that they are attached to that position (frequently used to indicate
    hydrogen atoms attached to another element, e.g., a carbon with three attached
    hydrogens might represent a methyl group, -CH3).

    - **Examples**:
        - `[ {"name": "Ti", "chemical_symbols": ["Ti"], "concentration": [1.0]} ]`: any site with this species is occupied by a Ti atom.
        - `[ {"name": "Ti", "chemical_symbols": ["Ti", "vacancy"], "concentration": [0.9, 0.1]} ]`: any site with this species is occupied by a Ti atom with 90 % probability, and has a vacancy with 10 % probability.
        - `[ {"name": "BaCa", "chemical_symbols": ["vacancy", "Ba", "Ca"], "concentration": [0.05, 0.45, 0.5], "mass": [0.0, 137.327, 40.078]} ]`: any site with this species is occupied by a Ba atom with 45 % probability, a Ca atom with 50 % probability, and by a vacancy with 5 % probability. The mass of this site is (on average) 88.5 a.m.u.
        - `[ {"name": "C12", "chemical_symbols": ["C"], "concentration": [1.0], "mass": [12.0]} ]`: any site with this species is occupied by a carbon isotope with mass 12.
        - `[ {"name": "C13", "chemical_symbols": ["C"], "concentration": [1.0], "mass": [13.0]} ]`: any site with this species is occupied by a carbon isotope with mass 13.
        - `[ {"name": "CH3", "chemical_symbols": ["C"], "concentration": [1.0], "attached": ["H"], "nattached": [3]} ]`: any site with this species is occupied by a methyl group, -CH3, which is represented without specifying precise positions of the hydrogen atoms.

    """

    name: str = OptimadeField(
        ...,
        description="""Gives the name of the species; the **name** value MUST be unique in the `species` list.""",
        support=SupportLevel.MUST,
        queryable=SupportLevel.OPTIONAL,
    )

    chemical_symbols: list[str] = OptimadeField(
        ...,
        description="""MUST be a list of strings of all chemical elements composing this species. Each item of the list MUST be one of the following:

- a valid chemical-element symbol, or
- the special value `"X"` to represent a non-chemical element, or
- the special value `"vacancy"` to represent that this site has a non-zero probability of having a vacancy (the respective probability is indicated in the `concentration` list, see below).

If any one entry in the `species` list has a `chemical_symbols` list that is longer than 1 element, the correct flag MUST be set in the list `structure_features`.""",
        support=SupportLevel.MUST,
        queryable=SupportLevel.OPTIONAL,
    )

    concentration: list[float] = OptimadeField(
        ...,
        description="""MUST be a list of floats, with same length as `chemical_symbols`. The numbers represent the relative concentration of the corresponding chemical symbol in this species. The numbers SHOULD sum to one. Cases in which the numbers do not sum to one typically fall only in the following two categories:

- Numerical errors when representing float numbers in fixed precision, e.g. for two chemical symbols with concentrations `1/3` and `2/3`, the concentration might look something like `[0.33333333333, 0.66666666666]`. If the client is aware that the sum is not one because of numerical precision, it can renormalize the values so that the sum is exactly one.
- Experimental errors in the data present in the database. In this case, it is the responsibility of the client to decide how to process the data.

Note that concentrations are uncorrelated between different site (even of the same species).""",
        support=SupportLevel.MUST,
        queryable=SupportLevel.OPTIONAL,
    )

    mass: Optional[list[float]] = OptimadeField(
        None,
        description="""If present MUST be a list of floats expressed in a.m.u.
Elements denoting vacancies MUST have masses equal to 0.""",
        unit="a.m.u.",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    original_name: Optional[str] = OptimadeField(
        None,
        description="""Can be any valid Unicode string, and SHOULD contain (if specified) the name of the species that is used internally in the source database.

Note: With regards to "source database", we refer to the immediate source being queried via the OPTIMADE API implementation.""",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    attached: Optional[list[str]] = OptimadeField(
        None,
        description="""If provided MUST be a list of length 1 or more of strings of chemical symbols for the elements attached to this site, or "X" for a non-chemical element.""",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    nattached: Optional[list[int]] = OptimadeField(
        None,
        description="""If provided MUST be a list of length 1 or more of integers indicating the number of attached atoms of the kind specified in the value of the :field:`attached` key.""",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    @validator("chemical_symbols", each_item=True)
    def validate_chemical_symbols(cls, v):
        if v not in EXTENDED_CHEMICAL_SYMBOLS:
            raise ValueError(
                f'{v!r} MUST be an element symbol, e.g., "C", "He", or a special symbol from {EXTRA_SYMBOLS}.'
            )
        return v

    @validator("concentration", "mass")
    def validate_concentration_and_mass(cls, v, values, field):
        if not v:
            return v
        if values.get("chemical_symbols"):
            if len(v) != len(values["chemical_symbols"]):
                raise ValueError(
                    f"Length of concentration ({len(v)}) MUST equal length of chemical_symbols "
                    f"({len(values.get('chemical_symbols', []))})"
                )
            return v

        raise ValueError(
            f"Could not validate {field.name!r} as 'chemical_symbols' is missing/invalid."
        )

    @validator("attached", "nattached")
    def validate_minimum_list_length(cls, v):
        if v is not None and len(v) < 1:
            raise ValueError(
                f"The list's length MUST be 1 or more, instead it was found to be {len(v)}"
            )
        return v

    @root_validator
    def attached_nattached_mutually_exclusive(cls, values):
        attached, nattached = (
            values.get("attached", None),
            values.get("nattached", None),
        )
        if (attached is None and nattached is not None) or (
            attached is not None and nattached is None
        ):
            raise ValueError(
                f"Either both or none of attached ({attached}) and nattached ({nattached}) MUST be set."
            )

        if (
            attached is not None
            and nattached is not None
            and len(attached) != len(nattached)
        ):
            raise ValueError(
                f"attached ({attached}) and nattached ({nattached}) MUST be lists of equal length."
            )

        return values

attached: list pydantic-field

If provided MUST be a list of length 1 or more of strings of chemical symbols for the elements attached to this site, or "X" for a non-chemical element.

chemical_symbols: list pydantic-field required

MUST be a list of strings of all chemical elements composing this species. Each item of the list MUST be one of the following:

• a valid chemical-element symbol, or
• the special value "X" to represent a non-chemical element, or
• the special value "vacancy" to represent that this site has a non-zero probability of having a vacancy (the respective probability is indicated in the concentration list, see below).

If any one entry in the species list has a chemical_symbols list that is longer than 1 element, the correct flag MUST be set in the list structure_features.

concentration: list pydantic-field required

MUST be a list of floats, with same length as chemical_symbols. The numbers represent the relative concentration of the corresponding chemical symbol in this species. The numbers SHOULD sum to one. Cases in which the numbers do not sum to one typically fall only in the following two categories:

• Numerical errors when representing float numbers in fixed precision, e.g. for two chemical symbols with concentrations 1/3 and 2/3, the concentration might look something like [0.33333333333, 0.66666666666]. If the client is aware that the sum is not one because of numerical precision, it can renormalize the values so that the sum is exactly one.
• Experimental errors in the data present in the database. In this case, it is the responsibility of the client to decide how to process the data.

Note that concentrations are uncorrelated between different site (even of the same species).

mass: list pydantic-field

If present MUST be a list of floats expressed in a.m.u. Elements denoting vacancies MUST have masses equal to 0.

name: str pydantic-field required

Gives the name of the species; the name value MUST be unique in the species list.

nattached: list pydantic-field

If provided MUST be a list of length 1 or more of integers indicating the number of attached atoms of the kind specified in the value of the :field:attached key.

original_name: str pydantic-field

Can be any valid Unicode string, and SHOULD contain (if specified) the name of the species that is used internally in the source database.

Note: With regards to "source database", we refer to the immediate source being queried via the OPTIMADE API implementation.

StructureFeatures (Enum)

Enumeration of structure_features values

Source code in optimade/models/structures.py

class StructureFeatures(Enum):
    """Enumeration of structure_features values"""

    DISORDER = "disorder"
    IMPLICIT_ATOMS = "implicit_atoms"
    SITE_ATTACHMENTS = "site_attachments"
    ASSEMBLIES = "assemblies"

StructureResource (EntryResource) pydantic-model

Representing a structure.

Source code in optimade/models/structures.py

class StructureResource(EntryResource):
    """Representing a structure."""

    type: str = StrictField(
        "structures",
        description="""The name of the type of an entry.

- **Type**: string.

- **Requirements/Conventions**:
    - **Support**: MUST be supported by all implementations, MUST NOT be `null`.
    - **Query**: MUST be a queryable property with support for all mandatory filter features.
    - **Response**: REQUIRED in the response.
    - MUST be an existing entry type.
    - The entry of type `<type>` and ID `<id>` MUST be returned in response to a request for `/<type>/<id>` under the versioned base URL.

- **Examples**:
    - `"structures"`""",
        regex="^structures$",
        support=SupportLevel.MUST,
        queryable=SupportLevel.MUST,
    )

    attributes: StructureResourceAttributes

StructureResourceAttributes (EntryResourceAttributes) pydantic-model

This class contains the Field for the attributes used to represent a structure, e.g. unit cell, atoms, positions.

Source code in optimade/models/structures.py

class StructureResourceAttributes(EntryResourceAttributes):
    """This class contains the Field for the attributes used to represent a structure, e.g. unit cell, atoms, positions."""

    elements: Optional[list[str]] = OptimadeField(
        ...,
        description="""The chemical symbols of the different elements present in the structure.

- **Type**: list of strings.

- **Requirements/Conventions**:
    - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.
    - **Query**: MUST be a queryable property with support for all mandatory filter features.
    - The strings are the chemical symbols, i.e., either a single uppercase letter or an uppercase letter followed by a number of lowercase letters.
    - The order MUST be alphabetical.
    - MUST refer to the same elements in the same order, and therefore be of the same length, as `elements_ratios`, if the latter is provided.
    - Note: This property SHOULD NOT contain the string "X" to indicate non-chemical elements or "vacancy" to indicate vacancies (in contrast to the field `chemical_symbols` for the `species` property).

- **Examples**:
    - `["Si"]`
    - `["Al","O","Si"]`

- **Query examples**:
    - A filter that matches all records of structures that contain Si, Al **and** O, and possibly other elements: `elements HAS ALL "Si", "Al", "O"`.
    - To match structures with exactly these three elements, use `elements HAS ALL "Si", "Al", "O" AND elements LENGTH 3`.
    - Note: length queries on this property can be equivalently formulated by filtering on the `nelements`_ property directly.""",
        support=SupportLevel.SHOULD,
        queryable=SupportLevel.MUST,
    )

    nelements: Optional[int] = OptimadeField(
        ...,
        description="""Number of different elements in the structure as an integer.

- **Type**: integer

- **Requirements/Conventions**:
    - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.
    - **Query**: MUST be a queryable property with support for all mandatory filter features.
    - MUST be equal to the lengths of the list properties `elements` and `elements_ratios`, if they are provided.

- **Examples**:
    - `3`

- **Querying**:
    - Note: queries on this property can equivalently be formulated using `elements LENGTH`.
    - A filter that matches structures that have exactly 4 elements: `nelements=4`.
    - A filter that matches structures that have between 2 and 7 elements: `nelements>=2 AND nelements<=7`.""",
        support=SupportLevel.SHOULD,
        queryable=SupportLevel.MUST,
    )

    elements_ratios: Optional[list[float]] = OptimadeField(
        ...,
        description="""Relative proportions of different elements in the structure.

- **Type**: list of floats

- **Requirements/Conventions**:
    - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.
    - **Query**: MUST be a queryable property with support for all mandatory filter features.
    - Composed by the proportions of elements in the structure as a list of floating point numbers.
    - The sum of the numbers MUST be 1.0 (within floating point accuracy)
    - MUST refer to the same elements in the same order, and therefore be of the same length, as `elements`, if the latter is provided.

- **Examples**:
    - `[1.0]`
    - `[0.3333333333333333, 0.2222222222222222, 0.4444444444444444]`

- **Query examples**:
    - Note: Useful filters can be formulated using the set operator syntax for correlated values.
      However, since the values are floating point values, the use of equality comparisons is generally inadvisable.
    - OPTIONAL: a filter that matches structures where approximately 1/3 of the atoms in the structure are the element Al is: `elements:elements_ratios HAS ALL "Al":>0.3333, "Al":<0.3334`.""",
        support=SupportLevel.SHOULD,
        queryable=SupportLevel.MUST,
    )

    chemical_formula_descriptive: Optional[str] = OptimadeField(
        ...,
        description="""The chemical formula for a structure as a string in a form chosen by the API implementation.

- **Type**: string

- **Requirements/Conventions**:
    - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.
    - **Query**: MUST be a queryable property with support for all mandatory filter features.
    - The chemical formula is given as a string consisting of properly capitalized element symbols followed by integers or decimal numbers, balanced parentheses, square, and curly brackets `(`,`)`, `[`,`]`, `{`, `}`, commas, the `+`, `-`, `:` and `=` symbols. The parentheses are allowed to be followed by a number. Spaces are allowed anywhere except within chemical symbols. The order of elements and any groupings indicated by parentheses or brackets are chosen freely by the API implementation.
    - The string SHOULD be arithmetically consistent with the element ratios in the `chemical_formula_reduced` property.
    - It is RECOMMENDED, but not mandatory, that symbols, parentheses and brackets, if used, are used with the meanings prescribed by [IUPAC's Nomenclature of Organic Chemistry](https://www.qmul.ac.uk/sbcs/iupac/bibliog/blue.html).

- **Examples**:
    - `"(H2O)2 Na"`
    - `"NaCl"`
    - `"CaCO3"`
    - `"CCaO3"`
    - `"(CH3)3N+ - [CH2]2-OH = Me3N+ - CH2 - CH2OH"`

- **Query examples**:
    - Note: the free-form nature of this property is likely to make queries on it across different databases inconsistent.
    - A filter that matches an exactly given formula: `chemical_formula_descriptive="(H2O)2 Na"`.
    - A filter that does a partial match: `chemical_formula_descriptive CONTAINS "H2O"`.""",
        support=SupportLevel.SHOULD,
        queryable=SupportLevel.MUST,
    )

    chemical_formula_reduced: Optional[str] = OptimadeField(
        ...,
        description="""The reduced chemical formula for a structure as a string with element symbols and integer chemical proportion numbers.
The proportion number MUST be omitted if it is 1.

- **Type**: string

- **Requirements/Conventions**:
    - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.
    - **Query**: MUST be a queryable property.
      However, support for filters using partial string matching with this property is OPTIONAL (i.e., BEGINS WITH, ENDS WITH, and CONTAINS).
      Intricate queries on formula components are instead suggested to be formulated using set-type filter operators on the multi valued `elements` and `elements_ratios` properties.
    - Element symbols MUST have proper capitalization (e.g., `"Si"`, not `"SI"` for "silicon").
    - Elements MUST be placed in alphabetical order, followed by their integer chemical proportion number.
    - For structures with no partial occupation, the chemical proportion numbers are the smallest integers for which the chemical proportion is exactly correct.
    - For structures with partial occupation, the chemical proportion numbers are integers that within reasonable approximation indicate the correct chemical proportions. The precise details of how to perform the rounding is chosen by the API implementation.
    - No spaces or separators are allowed.

- **Examples**:
    - `"H2NaO"`
    - `"ClNa"`
    - `"CCaO3"`

- **Query examples**:
    - A filter that matches an exactly given formula is `chemical_formula_reduced="H2NaO"`.""",
        support=SupportLevel.SHOULD,
        queryable=SupportLevel.MUST,
        regex=CHEMICAL_FORMULA_REGEXP,
    )

    chemical_formula_hill: Optional[str] = OptimadeField(
        None,
        description="""The chemical formula for a structure in [Hill form](https://dx.doi.org/10.1021/ja02046a005) with element symbols followed by integer chemical proportion numbers. The proportion number MUST be omitted if it is 1.

- **Type**: string

- **Requirements/Conventions**:
    - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.
    - **Query**: Support for queries on this property is OPTIONAL.
      If supported, only a subset of the filter features MAY be supported.
    - The overall scale factor of the chemical proportions is chosen such that the resulting values are integers that indicate the most chemically relevant unit of which the system is composed.
      For example, if the structure is a repeating unit cell with four hydrogens and four oxygens that represents two hydroperoxide molecules, `chemical_formula_hill` is `"H2O2"` (i.e., not `"HO"`, nor `"H4O4"`).
    - If the chemical insight needed to ascribe a Hill formula to the system is not present, the property MUST be handled as unset.
    - Element symbols MUST have proper capitalization (e.g., `"Si"`, not `"SI"` for "silicon").
    - Elements MUST be placed in [Hill order](https://dx.doi.org/10.1021/ja02046a005), followed by their integer chemical proportion number.
      Hill order means: if carbon is present, it is placed first, and if also present, hydrogen is placed second.
      After that, all other elements are ordered alphabetically.
      If carbon is not present, all elements are ordered alphabetically.
    - If the system has sites with partial occupation and the total occupations of each element do not all sum up to integers, then the Hill formula SHOULD be handled as unset.
    - No spaces or separators are allowed.

- **Examples**:
    - `"H2O2"`

- **Query examples**:
    - A filter that matches an exactly given formula is `chemical_formula_hill="H2O2"`.""",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
        regex=CHEMICAL_FORMULA_REGEXP,
    )

    chemical_formula_anonymous: Optional[str] = OptimadeField(
        ...,
        description="""The anonymous formula is the `chemical_formula_reduced`, but where the elements are instead first ordered by their chemical proportion number, and then, in order left to right, replaced by anonymous symbols A, B, C, ..., Z, Aa, Ba, ..., Za, Ab, Bb, ... and so on.

- **Type**: string

- **Requirements/Conventions**:
    - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.
    - **Query**: MUST be a queryable property.
      However, support for filters using partial string matching with this property is OPTIONAL (i.e., BEGINS WITH, ENDS WITH, and CONTAINS).

- **Examples**:
    - `"A2B"`
    - `"A42B42C16D12E10F9G5"`

- **Querying**:
    - A filter that matches an exactly given formula is `chemical_formula_anonymous="A2B"`.""",
        support=SupportLevel.SHOULD,
        queryable=SupportLevel.MUST,
        regex=CHEMICAL_FORMULA_REGEXP,
    )

    dimension_types: Optional[  # type: ignore[valid-type]
        conlist(Periodicity, min_items=3, max_items=3)
    ] = OptimadeField(
        None,
        title="Dimension Types",
        description="""List of three integers.
For each of the three directions indicated by the three lattice vectors (see property `lattice_vectors`), this list indicates if the direction is periodic (value `1`) or non-periodic (value `0`).
Note: the elements in this list each refer to the direction of the corresponding entry in `lattice_vectors` and *not* the Cartesian x, y, z directions.

- **Type**: list of integers.

- **Requirements/Conventions**:
    - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.
    - **Query**: Support for queries on this property is OPTIONAL.
    - MUST be a list of length 3.
    - Each integer element MUST assume only the value 0 or 1.

- **Examples**:
    - For a molecule: `[0, 0, 0]`
    - For a wire along the direction specified by the third lattice vector: `[0, 0, 1]`
    - For a 2D surface/slab, periodic on the plane defined by the first and third lattice vectors: `[1, 0, 1]`
    - For a bulk 3D system: `[1, 1, 1]`""",
        support=SupportLevel.SHOULD,
        queryable=SupportLevel.OPTIONAL,
    )

    nperiodic_dimensions: Optional[int] = OptimadeField(
        ...,
        description="""An integer specifying the number of periodic dimensions in the structure, equivalent to the number of non-zero entries in `dimension_types`.

- **Type**: integer

- **Requirements/Conventions**:
    - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.
    - **Query**: MUST be a queryable property with support for all mandatory filter features.
    - The integer value MUST be between 0 and 3 inclusive and MUST be equal to the sum of the items in the `dimension_types` property.
    - This property only reflects the treatment of the lattice vectors provided for the structure, and not any physical interpretation of the dimensionality of its contents.

- **Examples**:
    - `2` should be indicated in cases where `dimension_types` is any of `[1, 1, 0]`, `[1, 0, 1]`, `[0, 1, 1]`.

- **Query examples**:
    - Match only structures with exactly 3 periodic dimensions: `nperiodic_dimensions=3`
    - Match all structures with 2 or fewer periodic dimensions: `nperiodic_dimensions<=2`""",
        support=SupportLevel.SHOULD,
        queryable=SupportLevel.MUST,
    )

    lattice_vectors: Optional[  # type: ignore[valid-type]
        conlist(Vector3D_unknown, min_items=3, max_items=3)
    ] = OptimadeField(
        None,
        description="""The three lattice vectors in Cartesian coordinates, in ångström (Å).

- **Type**: list of list of floats or unknown values.

- **Requirements/Conventions**:
    - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.
    - **Query**: Support for queries on this property is OPTIONAL.
      If supported, filters MAY support only a subset of comparison operators.
    - MUST be a list of three vectors *a*, *b*, and *c*, where each of the vectors MUST BE a list of the vector's coordinates along the x, y, and z Cartesian coordinates.
      (Therefore, the first index runs over the three lattice vectors and the second index runs over the x, y, z Cartesian coordinates).
    - For databases that do not define an absolute Cartesian system (e.g., only defining the length and angles between vectors), the first lattice vector SHOULD be set along *x* and the second on the *xy*-plane.
    - MUST always contain three vectors of three coordinates each, independently of the elements of property `dimension_types`.
      The vectors SHOULD by convention be chosen so the determinant of the `lattice_vectors` matrix is different from zero.
      The vectors in the non-periodic directions have no significance beyond fulfilling these requirements.
    - The coordinates of the lattice vectors of non-periodic dimensions (i.e., those dimensions for which `dimension_types` is `0`) MAY be given as a list of all `null` values.
        If a lattice vector contains the value `null`, all coordinates of that lattice vector MUST be `null`.

- **Examples**:
    - `[[4.0,0.0,0.0],[0.0,4.0,0.0],[0.0,1.0,4.0]]` represents a cell, where the first vector is `(4, 0, 0)`, i.e., a vector aligned along the `x` axis of length 4 Å; the second vector is `(0, 4, 0)`; and the third vector is `(0, 1, 4)`.""",
        unit="Å",
        support=SupportLevel.SHOULD,
        queryable=SupportLevel.OPTIONAL,
    )

    cartesian_site_positions: Optional[list[Vector3D]] = OptimadeField(  # type: ignore[valid-type]
        ...,
        description="""Cartesian positions of each site in the structure.
A site is usually used to describe positions of atoms; what atoms can be encountered at a given site is conveyed by the `species_at_sites` property, and the species themselves are described in the `species` property.

- **Type**: list of list of floats

- **Requirements/Conventions**:
    - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.
    - **Query**: Support for queries on this property is OPTIONAL.
      If supported, filters MAY support only a subset of comparison operators.
    - It MUST be a list of length equal to the number of sites in the structure, where every element is a list of the three Cartesian coordinates of a site expressed as float values in the unit angstrom (Å).
    - An entry MAY have multiple sites at the same Cartesian position (for a relevant use of this, see e.g., the property `assemblies`).

- **Examples**:
    - `[[0,0,0],[0,0,2]]` indicates a structure with two sites, one sitting at the origin and one along the (positive) *z*-axis, 2 Å away from the origin.""",
        unit="Å",
        support=SupportLevel.SHOULD,
        queryable=SupportLevel.OPTIONAL,
    )

    nsites: Optional[int] = OptimadeField(
        ...,
        description="""An integer specifying the length of the `cartesian_site_positions` property.

- **Type**: integer

- **Requirements/Conventions**:
    - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.
    - **Query**: MUST be a queryable property with support for all mandatory filter features.

- **Examples**:
    - `42`

- **Query examples**:
    - Match only structures with exactly 4 sites: `nsites=4`
    - Match structures that have between 2 and 7 sites: `nsites>=2 AND nsites<=7`""",
        queryable=SupportLevel.MUST,
        support=SupportLevel.SHOULD,
    )

    species: Optional[list[Species]] = OptimadeField(
        ...,
        description="""A list describing the species of the sites of this structure.
Species can represent pure chemical elements, virtual-crystal atoms representing a statistical occupation of a given site by multiple chemical elements, and/or a location to which there are attached atoms, i.e., atoms whose precise location are unknown beyond that they are attached to that position (frequently used to indicate hydrogen atoms attached to another element, e.g., a carbon with three attached hydrogens might represent a methyl group, -CH3).

- **Type**: list of dictionary with keys:
    - `name`: string (REQUIRED)
    - `chemical_symbols`: list of strings (REQUIRED)
    - `concentration`: list of float (REQUIRED)
    - `attached`: list of strings (REQUIRED)
    - `nattached`: list of integers (OPTIONAL)
    - `mass`: list of floats (OPTIONAL)
    - `original_name`: string (OPTIONAL).

- **Requirements/Conventions**:
    - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.
    - **Query**: Support for queries on this property is OPTIONAL.
        If supported, filters MAY support only a subset of comparison operators.
    - Each list member MUST be a dictionary with the following keys:
        - **name**: REQUIRED; gives the name of the species; the **name** value MUST be unique in the `species` list;
        - **chemical_symbols**: REQUIRED; MUST be a list of strings of all chemical elements composing this species.
          Each item of the list MUST be one of the following:
            - a valid chemical-element symbol, or
            - the special value `"X"` to represent a non-chemical element, or
            - the special value `"vacancy"` to represent that this site has a non-zero probability of having a vacancy (the respective probability is indicated in the `concentration` list, see below).

          If any one entry in the `species` list has a `chemical_symbols` list that is longer than 1 element, the correct flag MUST be set in the list `structure_features`.

        - **concentration**: REQUIRED; MUST be a list of floats, with same length as `chemical_symbols`.
          The numbers represent the relative concentration of the corresponding chemical symbol in this species.
          The numbers SHOULD sum to one. Cases in which the numbers do not sum to one typically fall only in the following two categories:

            - Numerical errors when representing float numbers in fixed precision, e.g. for two chemical symbols with concentrations `1/3` and `2/3`, the concentration might look something like `[0.33333333333, 0.66666666666]`. If the client is aware that the sum is not one because of numerical precision, it can renormalize the values so that the sum is exactly one.
            - Experimental errors in the data present in the database. In this case, it is the responsibility of the client to decide how to process the data.

            Note that concentrations are uncorrelated between different sites (even of the same species).

        - **attached**: OPTIONAL; if provided MUST be a list of length 1 or more of strings of chemical symbols for the elements attached to this site, or "X" for a non-chemical element.

        - **nattached**: OPTIONAL; if provided MUST be a list of length 1 or more of integers indicating the number of attached atoms of the kind specified in the value of the `attached` key.

          The implementation MUST include either both or none of the `attached` and `nattached` keys, and if they are provided, they MUST be of the same length.
          Furthermore, if they are provided, the `structure_features` property MUST include the string `site_attachments`.

        - **mass**: OPTIONAL. If present MUST be a list of floats, with the same length as `chemical_symbols`, providing element masses expressed in a.m.u.
          Elements denoting vacancies MUST have masses equal to 0.

        - **original_name**: OPTIONAL. Can be any valid Unicode string, and SHOULD contain (if specified) the name of the species that is used internally in the source database.

          Note: With regards to "source database", we refer to the immediate source being queried via the OPTIMADE API implementation.

          The main use of this field is for source databases that use species names, containing characters that are not allowed (see description of the list property `species_at_sites`).

    - For systems that have only species formed by a single chemical symbol, and that have at most one species per chemical symbol, SHOULD use the chemical symbol as species name (e.g., `"Ti"` for titanium, `"O"` for oxygen, etc.)
      However, note that this is OPTIONAL, and client implementations MUST NOT assume that the key corresponds to a chemical symbol, nor assume that if the species name is a valid chemical symbol, that it represents a species with that chemical symbol.
      This means that a species `{"name": "C", "chemical_symbols": ["Ti"], "concentration": [1.0]}` is valid and represents a titanium species (and *not* a carbon species).
    - It is NOT RECOMMENDED that a structure includes species that do not have at least one corresponding site.

- **Examples**:
    - `[ {"name": "Ti", "chemical_symbols": ["Ti"], "concentration": [1.0]} ]`: any site with this species is occupied by a Ti atom.
    - `[ {"name": "Ti", "chemical_symbols": ["Ti", "vacancy"], "concentration": [0.9, 0.1]} ]`: any site with this species is occupied by a Ti atom with 90 % probability, and has a vacancy with 10 % probability.
    - `[ {"name": "BaCa", "chemical_symbols": ["vacancy", "Ba", "Ca"], "concentration": [0.05, 0.45, 0.5], "mass": [0.0, 137.327, 40.078]} ]`: any site with this species is occupied by a Ba atom with 45 % probability, a Ca atom with 50 % probability, and by a vacancy with 5 % probability. The mass of this site is (on average) 88.5 a.m.u.
    - `[ {"name": "C12", "chemical_symbols": ["C"], "concentration": [1.0], "mass": [12.0]} ]`: any site with this species is occupied by a carbon isotope with mass 12.
    - `[ {"name": "C13", "chemical_symbols": ["C"], "concentration": [1.0], "mass": [13.0]} ]`: any site with this species is occupied by a carbon isotope with mass 13.
    - `[ {"name": "CH3", "chemical_symbols": ["C"], "concentration": [1.0], "attached": ["H"], "nattached": [3]} ]`: any site with this species is occupied by a methyl group, -CH3, which is represented without specifying precise positions of the hydrogen atoms.""",
        support=SupportLevel.SHOULD,
        queryable=SupportLevel.OPTIONAL,
    )

    species_at_sites: Optional[list[str]] = OptimadeField(
        ...,
        description="""Name of the species at each site (where values for sites are specified with the same order of the property `cartesian_site_positions`).
The properties of the species are found in the property `species`.

- **Type**: list of strings.

- **Requirements/Conventions**:
    - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.
    - **Query**: Support for queries on this property is OPTIONAL.
      If supported, filters MAY support only a subset of comparison operators.
    - MUST have length equal to the number of sites in the structure (first dimension of the list property `cartesian_site_positions`).
    - Each species name mentioned in the `species_at_sites` list MUST be described in the list property `species` (i.e. for each value in the `species_at_sites` list there MUST exist exactly one dictionary in the `species` list with the `name` attribute equal to the corresponding `species_at_sites` value).
    - Each site MUST be associated only to a single species.
      **Note**: However, species can represent mixtures of atoms, and multiple species MAY be defined for the same chemical element.
      This latter case is useful when different atoms of the same type need to be grouped or distinguished, for instance in simulation codes to assign different initial spin states.

- **Examples**:
    - `["Ti","O2"]` indicates that the first site is hosting a species labeled `"Ti"` and the second a species labeled `"O2"`.
    - `["Ac", "Ac", "Ag", "Ir"]` indicating the first two sites contains the `"Ac"` species, while the third and fourth sites contain the `"Ag"` and `"Ir"` species, respectively.""",
        support=SupportLevel.SHOULD,
        queryable=SupportLevel.OPTIONAL,
    )

    assemblies: Optional[list[Assembly]] = OptimadeField(
        None,
        description="""A description of groups of sites that are statistically correlated.

- **Type**: list of dictionary with keys:
    - `sites_in_groups`: list of list of integers (REQUIRED)
    - `group_probabilities`: list of floats (REQUIRED)

- **Requirements/Conventions**:
    - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.
    - **Query**: Support for queries on this property is OPTIONAL.
        If supported, filters MAY support only a subset of comparison operators.
    - The property SHOULD be `null` for entries that have no partial occupancies.
    - If present, the correct flag MUST be set in the list `structure_features`.
    - Client implementations MUST check its presence (as its presence changes the interpretation of the structure).
    - If present, it MUST be a list of dictionaries, each of which represents an assembly and MUST have the following two keys:
        - **sites_in_groups**: Index of the sites (0-based) that belong to each group for each assembly.

            Example: `[[1], [2]]`: two groups, one with the second site, one with the third.
            Example: `[[1,2], [3]]`: one group with the second and third site, one with the fourth.

        - **group_probabilities**: Statistical probability of each group. It MUST have the same length as `sites_in_groups`.
            It SHOULD sum to one.
            See below for examples of how to specify the probability of the occurrence of a vacancy.
            The possible reasons for the values not to sum to one are the same as already specified above for the `concentration` of each `species`.

    - If a site is not present in any group, it means that it is present with 100 % probability (as if no assembly was specified).
    - A site MUST NOT appear in more than one group.

- **Examples** (for each entry of the assemblies list):
    - `{"sites_in_groups": [[0], [1]], "group_probabilities: [0.3, 0.7]}`: the first site and the second site never occur at the same time in the unit cell.
        Statistically, 30 % of the times the first site is present, while 70 % of the times the second site is present.
    - `{"sites_in_groups": [[1,2], [3]], "group_probabilities: [0.3, 0.7]}`: the second and third site are either present together or not present; they form the first group of atoms for this assembly.
        The second group is formed by the fourth site.
        Sites of the first group (the second and the third) are never present at the same time as the fourth site.
        30 % of times sites 1 and 2 are present (and site 3 is absent); 70 % of times site 3 is present (and sites 1 and 2 are absent).

- **Notes**:
    - Assemblies are essential to represent, for instance, the situation where an atom can statistically occupy two different positions (sites).

    - By defining groups, it is possible to represent, e.g., the case where a functional molecule (and not just one atom) is either present or absent (or the case where it it is present in two conformations)

    - Considerations on virtual alloys and on vacancies: In the special case of a virtual alloy, these specifications allow two different, equivalent ways of specifying them.
        For instance, for a site at the origin with 30 % probability of being occupied by Si, 50 % probability of being occupied by Ge, and 20 % of being a vacancy, the following two representations are possible:

        - Using a single species:
            ```json
            {
              "cartesian_site_positions": [[0,0,0]],
              "species_at_sites": ["SiGe-vac"],
              "species": [
              {
                "name": "SiGe-vac",
                "chemical_symbols": ["Si", "Ge", "vacancy"],
                "concentration": [0.3, 0.5, 0.2]
              }
              ]
              // ...
            }
            ```

        - Using multiple species and the assemblies:
            ```json
            {
              "cartesian_site_positions": [ [0,0,0], [0,0,0], [0,0,0] ],
              "species_at_sites": ["Si", "Ge", "vac"],
              "species": [
                { "name": "Si", "chemical_symbols": ["Si"], "concentration": [1.0] },
                { "name": "Ge", "chemical_symbols": ["Ge"], "concentration": [1.0] },
                { "name": "vac", "chemical_symbols": ["vacancy"], "concentration": [1.0] }
              ],
              "assemblies": [
                {
              "sites_in_groups": [ [0], [1], [2] ],
              "group_probabilities": [0.3, 0.5, 0.2]
                }
              ]
              // ...
            }
            ```

    - It is up to the database provider to decide which representation to use, typically depending on the internal format in which the structure is stored.
        However, given a structure identified by a unique ID, the API implementation MUST always provide the same representation for it.

    - The probabilities of occurrence of different assemblies are uncorrelated.
        So, for instance in the following case with two assemblies:
        ```json
        {
          "assemblies": [
            {
              "sites_in_groups": [ [0], [1] ],
              "group_probabilities": [0.2, 0.8],
            },
            {
              "sites_in_groups": [ [2], [3] ],
              "group_probabilities": [0.3, 0.7]
            }
          ]
        }
        ```

        Site 0 is present with a probability of 20 % and site 1 with a probability of 80 %. These two sites are correlated (either site 0 or 1 is present). Similarly, site 2 is present with a probability of 30 % and site 3 with a probability of 70 %.
        These two sites are correlated (either site 2 or 3 is present).
        However, the presence or absence of sites 0 and 1 is not correlated with the presence or absence of sites 2 and 3 (in the specific example, the pair of sites (0, 2) can occur with 0.2*0.3 = 6 % probability; the pair (0, 3) with 0.2*0.7 = 14 % probability; the pair (1, 2) with 0.8*0.3 = 24 % probability; and the pair (1, 3) with 0.8*0.7 = 56 % probability).""",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    structure_features: list[StructureFeatures] = OptimadeField(
        ...,
        title="Structure Features",
        description="""A list of strings that flag which special features are used by the structure.

- **Type**: list of strings

- **Requirements/Conventions**:
    - **Support**: MUST be supported by all implementations, MUST NOT be `null`.
    - **Query**: MUST be a queryable property.
    Filters on the list MUST support all mandatory HAS-type queries.
    Filter operators for comparisons on the string components MUST support equality, support for other comparison operators are OPTIONAL.
    - MUST be an empty list if no special features are used.
    - MUST be sorted alphabetically.
    - If a special feature listed below is used, the list MUST contain the corresponding string.
    - If a special feature listed below is not used, the list MUST NOT contain the corresponding string.
    - **List of strings used to indicate special structure features**:
        - `disorder`: this flag MUST be present if any one entry in the `species` list has a `chemical_symbols` list that is longer than 1 element.
        - `implicit_atoms`: this flag MUST be present if the structure contains atoms that are not assigned to sites via the property `species_at_sites` (e.g., because their positions are unknown).
           When this flag is present, the properties related to the chemical formula will likely not match the type and count of atoms represented by the `species_at_sites`, `species` and `assemblies` properties.
        - `site_attachments`: this flag MUST be present if any one entry in the `species` list includes `attached` and `nattached`.
        - `assemblies`: this flag MUST be present if the property `assemblies` is present.

- **Examples**: A structure having implicit atoms and using assemblies: `["assemblies", "implicit_atoms"]`""",
        support=SupportLevel.MUST,
        queryable=SupportLevel.MUST,
    )

    class Config:
        def schema_extra(schema, model):
            """Two things need to be added to the schema:

            1. Constrained types in pydantic do not currently play nicely with
            "Required Optional" fields, i.e. fields must be specified but can be null.
            The two contrained list fields, `dimension_types` and `lattice_vectors`,
            are OPTIMADE 'SHOULD' fields, which means that they are allowed to be null.

            2. All OPTIMADE 'SHOULD' fields are allowed to be null, so we manually set them
            to be `nullable` according to the OpenAPI definition.

            """
            schema["required"].insert(7, "dimension_types")
            schema["required"].insert(9, "lattice_vectors")

            nullable_props = (
                prop
                for prop in schema["required"]
                if schema["properties"][prop].get("x-optimade-support")
                == SupportLevel.SHOULD
            )
            for prop in nullable_props:
                schema["properties"][prop]["nullable"] = True

    @root_validator(pre=True)
    def warn_on_missing_correlated_fields(cls, values):
        """Emit warnings if a field takes a null value when a value
        was expected based on the value/nullity of another field.
        """
        accumulated_warnings = []
        for field_set in CORRELATED_STRUCTURE_FIELDS:
            missing_fields = {f for f in field_set if values.get(f) is None}
            if missing_fields and len(missing_fields) != len(field_set):
                accumulated_warnings += [
                    f"Structure with values {values} is missing fields {missing_fields} which are required if {field_set - missing_fields} are present."
                ]

        for warn in accumulated_warnings:
            warnings.warn(warn, MissingExpectedField)

        return values

    @validator("chemical_formula_reduced", "chemical_formula_hill")
    def check_ordered_formula(cls, v, field):
        if v is None:
            return v

        elements = re.findall(r"[A-Z][a-z]?", v)
        expected_elements = sorted(elements)

        if field.name == "chemical_formula_hill":
            # Make sure C is first (and H is second, if present along with C).
            if "C" in expected_elements:
                expected_elements = sorted(
                    expected_elements,
                    key=lambda elem: {"C": "0", "H": "1"}.get(elem, elem),
                )

        if any(elem not in CHEMICAL_SYMBOLS for elem in elements):
            raise ValueError(
                f"Cannot use unknown chemical symbols {[elem for elem in elements if elem not in CHEMICAL_SYMBOLS]} in {field.name!r}"
            )

        if expected_elements != elements:
            order = "Hill" if field.name == "chemical_formula_hill" else "alphabetical"
            raise ValueError(
                f"Elements in {field.name!r} must appear in {order} order: {expected_elements} not {elements}."
            )

        return v

    @validator("chemical_formula_anonymous")
    def check_anonymous_formula(cls, v):
        if v is None:
            return v

        elements = tuple(re.findall(r"[A-Z][a-z]*", v))
        numbers = re.split(r"[A-Z][a-z]*", v)[1:]
        numbers = [int(i) if i else 1 for i in numbers]

        expected_labels = ANONYMOUS_ELEMENTS[: len(elements)]
        expected_numbers = sorted(numbers, reverse=True)

        if expected_numbers != numbers:
            raise ValueError(
                f"'chemical_formula_anonymous' {v} has wrong order: elements with highest proportion should appear first: {numbers} vs expected {expected_numbers}"
            )
        if elements != expected_labels:
            raise ValueError(
                f"'chemical_formula_anonymous' {v} has wrong labels: {elements} vs expected {expected_labels}."
            )

        return v

    @validator("chemical_formula_anonymous", "chemical_formula_reduced")
    def check_reduced_formulae(cls, value, field):
        if value is None:
            return value

        reduced_formula = reduce_formula(value)
        if reduced_formula != value:
            raise ValueError(
                f"{field.name} {value!r} is not properly reduced: expected {reduced_formula!r}."
            )

        return value

    @validator("elements", each_item=True)
    def element_must_be_chemical_symbol(cls, v):
        if v not in CHEMICAL_SYMBOLS:
            raise ValueError(f"Only chemical symbols are allowed, you passed: {v}")
        return v

    @validator("elements")
    def elements_must_be_alphabetical(cls, v):
        if v is None:
            return v

        if sorted(v) != v:
            raise ValueError(f"elements must be sorted alphabetically, but is: {v}")
        return v

    @validator("elements_ratios")
    def ratios_must_sum_to_one(cls, v):
        if v is None:
            return v

        if abs(sum(v) - 1) > EPS:
            raise ValueError(
                f"elements_ratios MUST sum to 1 within (at least single precision) floating point accuracy. It sums to: {sum(v)}"
            )
        return v

    @validator("nperiodic_dimensions")
    def check_periodic_dimensions(cls, v, values):
        if v is None:
            return v

        if values.get("dimension_types") and v != sum(values.get("dimension_types")):
            raise ValueError(
                f"nperiodic_dimensions ({v}) does not match expected value of {sum(values['dimension_types'])} "
                f"from dimension_types ({values['dimension_types']})"
            )

        return v

    @validator("lattice_vectors", always=True)
    def required_if_dimension_types_has_one(cls, v, values):
        if v is None:
            return v

        if values.get("dimension_types"):
            for dim_type, vector in zip(values.get("dimension_types", (None,) * 3), v):
                if None in vector and dim_type == Periodicity.PERIODIC.value:
                    raise ValueError(
                        f"Null entries in lattice vectors are only permitted when the corresponding dimension type is {Periodicity.APERIODIC.value}. "
                        f"Here: dimension_types = {tuple(getattr(_, 'value', None) for _ in values.get('dimension_types', []))}, lattice_vectors = {v}"
                    )

        return v

    @validator("lattice_vectors")
    def null_values_for_whole_vector(cls, v):
        if v is None:
            return v

        for vector in v:
            if None in vector and any(isinstance(_, float) for _ in vector):
                raise ValueError(
                    f"A lattice vector MUST be either all `null` or all numbers (vector: {vector}, all vectors: {v})"
                )
        return v

    @validator("nsites")
    def validate_nsites(cls, v, values):
        if v is None:
            return v

        if values.get("cartesian_site_positions") and v != len(
            values.get("cartesian_site_positions", [])
        ):
            raise ValueError(
                f"nsites (value: {v}) MUST equal length of cartesian_site_positions "
                f"(value: {len(values.get('cartesian_site_positions', []))})"
            )
        return v

    @validator("species_at_sites")
    def validate_species_at_sites(cls, v, values):
        if v is None:
            return v

        if values.get("nsites") and len(v) != values.get("nsites"):
            raise ValueError(
                f"Number of species_at_sites (value: {len(v)}) MUST equal number of sites "
                f"(value: {values.get('nsites', 'Not specified')})"
            )
        if values.get("species"):
            all_species_names = {
                getattr(_, "name", None) for _ in values.get("species", [{}])
            }
            all_species_names -= {None}
            for value in v:
                if value not in all_species_names:
                    raise ValueError(
                        "species_at_sites MUST be represented by a species' name, "
                        f"but {value} was not found in the list of species names: {all_species_names}"
                    )
        return v

    @validator("species")
    def validate_species(cls, v):
        if v is None:
            return v

        all_species = [_.name for _ in v]
        unique_species = set(all_species)
        if len(all_species) != len(unique_species):
            raise ValueError(
                f"Species MUST be unique based on their 'name'. Found species names: {all_species}"
            )

        return v

    @validator("structure_features", always=True)
    def validate_structure_features(cls, v, values):
        if [StructureFeatures(value) for value in sorted(_.value for _ in v)] != v:
            raise ValueError(
                f"structure_features MUST be sorted alphabetically, given value: {v}"
            )

        # assemblies
        if values.get("assemblies") is not None:
            if StructureFeatures.ASSEMBLIES not in v:
                raise ValueError(
                    f"{StructureFeatures.ASSEMBLIES.value} MUST be present, since the property of the same name is present"
                )
        elif StructureFeatures.ASSEMBLIES in v:
            raise ValueError(
                f"{StructureFeatures.ASSEMBLIES.value} MUST NOT be present, "
                "since the property of the same name is not present"
            )

        if values.get("species"):
            # disorder
            for species in values.get("species", []):
                if len(species.chemical_symbols) > 1:
                    if StructureFeatures.DISORDER not in v:
                        raise ValueError(
                            f"{StructureFeatures.DISORDER.value} MUST be present when any one entry in species "
                            "has a chemical_symbols list greater than one element"
                        )
                    break
            else:
                if StructureFeatures.DISORDER in v:
                    raise ValueError(
                        f"{StructureFeatures.DISORDER.value} MUST NOT be present, since all species' chemical_symbols "
                        "lists are equal to or less than one element"
                    )
            # site_attachments
            for species in values.get("species", []):
                # There is no need to also test "nattached",
                # since a Species validator makes sure either both are present or both are None.
                if getattr(species, "attached", None) is not None:
                    if StructureFeatures.SITE_ATTACHMENTS not in v:
                        raise ValueError(
                            f"{StructureFeatures.SITE_ATTACHMENTS.value} MUST be present when any one entry "
                            "in species includes attached and nattached"
                        )
                    break
            else:
                if StructureFeatures.SITE_ATTACHMENTS in v:
                    raise ValueError(
                        f"{StructureFeatures.SITE_ATTACHMENTS.value} MUST NOT be present, since no species includes "
                        "the attached and nattached fields"
                    )
            # implicit_atoms
            species_names = [_.name for _ in values.get("species", [])]
            for name in species_names:
                if values.get(
                    "species_at_sites"
                ) is not None and name not in values.get("species_at_sites", []):
                    if StructureFeatures.IMPLICIT_ATOMS not in v:
                        raise ValueError(
                            f"{StructureFeatures.IMPLICIT_ATOMS.value} MUST be present when any one entry in species "
                            "is not represented in species_at_sites"
                        )
                    break
            else:
                if StructureFeatures.IMPLICIT_ATOMS in v:
                    raise ValueError(
                        f"{StructureFeatures.IMPLICIT_ATOMS.value} MUST NOT be present, since all species are "
                        "represented in species_at_sites"
                    )

        return v

assemblies: list pydantic-field

A description of groups of sites that are statistically correlated.

• Type: list of dictionary with keys:

  • sites_in_groups: list of list of integers (REQUIRED)
  • group_probabilities: list of floats (REQUIRED)

• Requirements/Conventions:

  • Support: OPTIONAL support in implementations, i.e., MAY be null.
  • Query: Support for queries on this property is OPTIONAL. If supported, filters MAY support only a subset of comparison operators.
  • The property SHOULD be null for entries that have no partial occupancies.
  • If present, the correct flag MUST be set in the list structure_features.
  • Client implementations MUST check its presence (as its presence changes the interpretation of the structure).

  • If present, it MUST be a list of dictionaries, each of which represents an assembly and MUST have the following two keys:

    • sites_in_groups: Index of the sites (0-based) that belong to each group for each assembly.

      Example: [[1], [2]]: two groups, one with the second site, one with the third. Example: [[1,2], [3]]: one group with the second and third site, one with the fourth.

    • group_probabilities: Statistical probability of each group. It MUST have the same length as sites_in_groups. It SHOULD sum to one. See below for examples of how to specify the probability of the occurrence of a vacancy. The possible reasons for the values not to sum to one are the same as already specified above for the concentration of each species.

  • If a site is not present in any group, it means that it is present with 100 % probability (as if no assembly was specified).

  • A site MUST NOT appear in more than one group.

• Examples (for each entry of the assemblies list):

  • {"sites_in_groups": [[0], [1]], "group_probabilities: [0.3, 0.7]}: the first site and the second site never occur at the same time in the unit cell. Statistically, 30 % of the times the first site is present, while 70 % of the times the second site is present.
  • {"sites_in_groups": [[1,2], [3]], "group_probabilities: [0.3, 0.7]}: the second and third site are either present together or not present; they form the first group of atoms for this assembly. The second group is formed by the fourth site. Sites of the first group (the second and the third) are never present at the same time as the fourth site. 30 % of times sites 1 and 2 are present (and site 3 is absent); 70 % of times site 3 is present (and sites 1 and 2 are absent).

• Notes:

  • Assemblies are essential to represent, for instance, the situation where an atom can statistically occupy two different positions (sites).

  • By defining groups, it is possible to represent, e.g., the case where a functional molecule (and not just one atom) is either present or absent (or the case where it it is present in two conformations)

  • Considerations on virtual alloys and on vacancies: In the special case of a virtual alloy, these specifications allow two different, equivalent ways of specifying them. For instance, for a site at the origin with 30 % probability of being occupied by Si, 50 % probability of being occupied by Ge, and 20 % of being a vacancy, the following two representations are possible:

    • Using a single species:

      {
        "cartesian_site_positions": [[0,0,0]],
        "species_at_sites": ["SiGe-vac"],
        "species": [
        {
          "name": "SiGe-vac",
          "chemical_symbols": ["Si", "Ge", "vacancy"],
          "concentration": [0.3, 0.5, 0.2]
        }
        ]
        // ...
      }
      

    • Using multiple species and the assemblies:

      {
        "cartesian_site_positions": [ [0,0,0], [0,0,0], [0,0,0] ],
        "species_at_sites": ["Si", "Ge", "vac"],
        "species": [
          { "name": "Si", "chemical_symbols": ["Si"], "concentration": [1.0] },
          { "name": "Ge", "chemical_symbols": ["Ge"], "concentration": [1.0] },
          { "name": "vac", "chemical_symbols": ["vacancy"], "concentration": [1.0] }
        ],
        "assemblies": [
          {
        "sites_in_groups": [ [0], [1], [2] ],
        "group_probabilities": [0.3, 0.5, 0.2]
          }
        ]
        // ...
      }
      

  • It is up to the database provider to decide which representation to use, typically depending on the internal format in which the structure is stored. However, given a structure identified by a unique ID, the API implementation MUST always provide the same representation for it.

  • The probabilities of occurrence of different assemblies are uncorrelated. So, for instance in the following case with two assemblies:

    {
      "assemblies": [
        {
          "sites_in_groups": [ [0], [1] ],
          "group_probabilities": [0.2, 0.8],
        },
        {
          "sites_in_groups": [ [2], [3] ],
          "group_probabilities": [0.3, 0.7]
        }
      ]
    }
    

    Site 0 is present with a probability of 20 % and site 1 with a probability of 80 %. These two sites are correlated (either site 0 or 1 is present). Similarly, site 2 is present with a probability of 30 % and site 3 with a probability of 70 %. These two sites are correlated (either site 2 or 3 is present). However, the presence or absence of sites 0 and 1 is not correlated with the presence or absence of sites 2 and 3 (in the specific example, the pair of sites (0, 2) can occur with 0.20.3 = 6 % probability; the pair (0, 3) with 0.20.7 = 14 % probability; the pair (1, 2) with 0.80.3 = 24 % probability; and the pair (1, 3) with 0.80.7 = 56 % probability).

cartesian_site_positions: list pydantic-field required

Cartesian positions of each site in the structure. A site is usually used to describe positions of atoms; what atoms can be encountered at a given site is conveyed by the species_at_sites property, and the species themselves are described in the species property.

• Type: list of list of floats

• Requirements/Conventions:

  • Support: SHOULD be supported by all implementations, i.e., SHOULD NOT be null.
  • Query: Support for queries on this property is OPTIONAL. If supported, filters MAY support only a subset of comparison operators.
  • It MUST be a list of length equal to the number of sites in the structure, where every element is a list of the three Cartesian coordinates of a site expressed as float values in the unit angstrom (Å).
  • An entry MAY have multiple sites at the same Cartesian position (for a relevant use of this, see e.g., the property assemblies).

• Examples:

  • [[0,0,0],[0,0,2]] indicates a structure with two sites, one sitting at the origin and one along the (positive) z-axis, 2 Å away from the origin.

chemical_formula_anonymous: ConstrainedStrValue pydantic-field required

The anonymous formula is the chemical_formula_reduced, but where the elements are instead first ordered by their chemical proportion number, and then, in order left to right, replaced by anonymous symbols A, B, C, ..., Z, Aa, Ba, ..., Za, Ab, Bb, ... and so on.

• Type: string

• Requirements/Conventions:

  • Support: SHOULD be supported by all implementations, i.e., SHOULD NOT be null.
  • Query: MUST be a queryable property. However, support for filters using partial string matching with this property is OPTIONAL (i.e., BEGINS WITH, ENDS WITH, and CONTAINS).

• Examples:

  • "A2B"
  • "A42B42C16D12E10F9G5"

• Querying:

  • A filter that matches an exactly given formula is chemical_formula_anonymous="A2B".

chemical_formula_descriptive: str pydantic-field required

The chemical formula for a structure as a string in a form chosen by the API implementation.

• Type: string

• Requirements/Conventions:

  • Support: SHOULD be supported by all implementations, i.e., SHOULD NOT be null.
  • Query: MUST be a queryable property with support for all mandatory filter features.
  • The chemical formula is given as a string consisting of properly capitalized element symbols followed by integers or decimal numbers, balanced parentheses, square, and curly brackets (,), [,], {, }, commas, the +, -, : and = symbols. The parentheses are allowed to be followed by a number. Spaces are allowed anywhere except within chemical symbols. The order of elements and any groupings indicated by parentheses or brackets are chosen freely by the API implementation.
  • The string SHOULD be arithmetically consistent with the element ratios in the chemical_formula_reduced property.
  • It is RECOMMENDED, but not mandatory, that symbols, parentheses and brackets, if used, are used with the meanings prescribed by IUPAC's Nomenclature of Organic Chemistry.

• Examples:

  • "(H2O)2 Na"
  • "NaCl"
  • "CaCO3"
  • "CCaO3"
  • "(CH3)3N+ - [CH2]2-OH = Me3N+ - CH2 - CH2OH"

• Query examples:

  • Note: the free-form nature of this property is likely to make queries on it across different databases inconsistent.
  • A filter that matches an exactly given formula: chemical_formula_descriptive="(H2O)2 Na".
  • A filter that does a partial match: chemical_formula_descriptive CONTAINS "H2O".

chemical_formula_hill: ConstrainedStrValue pydantic-field

The chemical formula for a structure in Hill form with element symbols followed by integer chemical proportion numbers. The proportion number MUST be omitted if it is 1.

• Type: string

• Requirements/Conventions:

  • Support: OPTIONAL support in implementations, i.e., MAY be null.
  • Query: Support for queries on this property is OPTIONAL. If supported, only a subset of the filter features MAY be supported.
  • The overall scale factor of the chemical proportions is chosen such that the resulting values are integers that indicate the most chemically relevant unit of which the system is composed. For example, if the structure is a repeating unit cell with four hydrogens and four oxygens that represents two hydroperoxide molecules, chemical_formula_hill is "H2O2" (i.e., not "HO", nor "H4O4").
  • If the chemical insight needed to ascribe a Hill formula to the system is not present, the property MUST be handled as unset.
  • Element symbols MUST have proper capitalization (e.g., "Si", not "SI" for "silicon").
  • Elements MUST be placed in Hill order, followed by their integer chemical proportion number. Hill order means: if carbon is present, it is placed first, and if also present, hydrogen is placed second. After that, all other elements are ordered alphabetically. If carbon is not present, all elements are ordered alphabetically.
  • If the system has sites with partial occupation and the total occupations of each element do not all sum up to integers, then the Hill formula SHOULD be handled as unset.
  • No spaces or separators are allowed.

• Examples:

  • "H2O2"

• Query examples:

  • A filter that matches an exactly given formula is chemical_formula_hill="H2O2".

chemical_formula_reduced: ConstrainedStrValue pydantic-field required

The reduced chemical formula for a structure as a string with element symbols and integer chemical proportion numbers. The proportion number MUST be omitted if it is 1.

• Type: string

• Requirements/Conventions:

  • Support: SHOULD be supported by all implementations, i.e., SHOULD NOT be null.
  • Query: MUST be a queryable property. However, support for filters using partial string matching with this property is OPTIONAL (i.e., BEGINS WITH, ENDS WITH, and CONTAINS). Intricate queries on formula components are instead suggested to be formulated using set-type filter operators on the multi valued elements and elements_ratios properties.
  • Element symbols MUST have proper capitalization (e.g., "Si", not "SI" for "silicon").
  • Elements MUST be placed in alphabetical order, followed by their integer chemical proportion number.
  • For structures with no partial occupation, the chemical proportion numbers are the smallest integers for which the chemical proportion is exactly correct.
  • For structures with partial occupation, the chemical proportion numbers are integers that within reasonable approximation indicate the correct chemical proportions. The precise details of how to perform the rounding is chosen by the API implementation.
  • No spaces or separators are allowed.

• Examples:

  • "H2NaO"
  • "ClNa"
  • "CCaO3"

• Query examples:

  • A filter that matches an exactly given formula is chemical_formula_reduced="H2NaO".

dimension_types: ConstrainedListValue pydantic-field

List of three integers. For each of the three directions indicated by the three lattice vectors (see property lattice_vectors), this list indicates if the direction is periodic (value 1) or non-periodic (value 0). Note: the elements in this list each refer to the direction of the corresponding entry in lattice_vectors and not the Cartesian x, y, z directions.

• Type: list of integers.

• Requirements/Conventions:

  • Support: SHOULD be supported by all implementations, i.e., SHOULD NOT be null.
  • Query: Support for queries on this property is OPTIONAL.
  • MUST be a list of length 3.
  • Each integer element MUST assume only the value 0 or 1.

• Examples:

  • For a molecule: [0, 0, 0]
  • For a wire along the direction specified by the third lattice vector: [0, 0, 1]
  • For a 2D surface/slab, periodic on the plane defined by the first and third lattice vectors: [1, 0, 1]
  • For a bulk 3D system: [1, 1, 1]

elements: list pydantic-field required

The chemical symbols of the different elements present in the structure.

• Type: list of strings.

• Requirements/Conventions:

  • Support: SHOULD be supported by all implementations, i.e., SHOULD NOT be null.
  • Query: MUST be a queryable property with support for all mandatory filter features.
  • The strings are the chemical symbols, i.e., either a single uppercase letter or an uppercase letter followed by a number of lowercase letters.
  • The order MUST be alphabetical.
  • MUST refer to the same elements in the same order, and therefore be of the same length, as elements_ratios, if the latter is provided.
  • Note: This property SHOULD NOT contain the string "X" to indicate non-chemical elements or "vacancy" to indicate vacancies (in contrast to the field chemical_symbols for the species property).

• Examples:

  • ["Si"]
  • ["Al","O","Si"]

• Query examples:

  • A filter that matches all records of structures that contain Si, Al and O, and possibly other elements: elements HAS ALL "Si", "Al", "O".
  • To match structures with exactly these three elements, use elements HAS ALL "Si", "Al", "O" AND elements LENGTH 3.
  • Note: length queries on this property can be equivalently formulated by filtering on the nelements_ property directly.

elements_ratios: list pydantic-field required

Relative proportions of different elements in the structure.

• Type: list of floats

• Requirements/Conventions:

  • Support: SHOULD be supported by all implementations, i.e., SHOULD NOT be null.
  • Query: MUST be a queryable property with support for all mandatory filter features.
  • Composed by the proportions of elements in the structure as a list of floating point numbers.
  • The sum of the numbers MUST be 1.0 (within floating point accuracy)
  • MUST refer to the same elements in the same order, and therefore be of the same length, as elements, if the latter is provided.

• Examples:

  • [1.0]
  • [0.3333333333333333, 0.2222222222222222, 0.4444444444444444]

• Query examples:

  • Note: Useful filters can be formulated using the set operator syntax for correlated values. However, since the values are floating point values, the use of equality comparisons is generally inadvisable.
  • OPTIONAL: a filter that matches structures where approximately 1/3 of the atoms in the structure are the element Al is: elements:elements_ratios HAS ALL "Al":>0.3333, "Al":<0.3334.

lattice_vectors: ConstrainedListValue pydantic-field

The three lattice vectors in Cartesian coordinates, in ångström (Å).

• Type: list of list of floats or unknown values.

• Requirements/Conventions:

  • Support: SHOULD be supported by all implementations, i.e., SHOULD NOT be null.
  • Query: Support for queries on this property is OPTIONAL. If supported, filters MAY support only a subset of comparison operators.
  • MUST be a list of three vectors a, b, and c, where each of the vectors MUST BE a list of the vector's coordinates along the x, y, and z Cartesian coordinates. (Therefore, the first index runs over the three lattice vectors and the second index runs over the x, y, z Cartesian coordinates).
  • For databases that do not define an absolute Cartesian system (e.g., only defining the length and angles between vectors), the first lattice vector SHOULD be set along x and the second on the xy-plane.
  • MUST always contain three vectors of three coordinates each, independently of the elements of property dimension_types. The vectors SHOULD by convention be chosen so the determinant of the lattice_vectors matrix is different from zero. The vectors in the non-periodic directions have no significance beyond fulfilling these requirements.
  • The coordinates of the lattice vectors of non-periodic dimensions (i.e., those dimensions for which dimension_types is 0) MAY be given as a list of all null values. If a lattice vector contains the value null, all coordinates of that lattice vector MUST be null.

• Examples:

  • [[4.0,0.0,0.0],[0.0,4.0,0.0],[0.0,1.0,4.0]] represents a cell, where the first vector is (4, 0, 0), i.e., a vector aligned along the x axis of length 4 Å; the second vector is (0, 4, 0); and the third vector is (0, 1, 4).

nelements: int pydantic-field required

Number of different elements in the structure as an integer.

• Type: integer

• Requirements/Conventions:

  • Support: SHOULD be supported by all implementations, i.e., SHOULD NOT be null.
  • Query: MUST be a queryable property with support for all mandatory filter features.
  • MUST be equal to the lengths of the list properties elements and elements_ratios, if they are provided.

• Examples:

  • 3

• Querying:

  • Note: queries on this property can equivalently be formulated using elements LENGTH.
  • A filter that matches structures that have exactly 4 elements: nelements=4.
  • A filter that matches structures that have between 2 and 7 elements: nelements>=2 AND nelements<=7.

nperiodic_dimensions: int pydantic-field required

An integer specifying the number of periodic dimensions in the structure, equivalent to the number of non-zero entries in dimension_types.

• Type: integer

• Requirements/Conventions:

  • Support: SHOULD be supported by all implementations, i.e., SHOULD NOT be null.
  • Query: MUST be a queryable property with support for all mandatory filter features.
  • The integer value MUST be between 0 and 3 inclusive and MUST be equal to the sum of the items in the dimension_types property.
  • This property only reflects the treatment of the lattice vectors provided for the structure, and not any physical interpretation of the dimensionality of its contents.

• Examples:

  • 2 should be indicated in cases where dimension_types is any of [1, 1, 0], [1, 0, 1], [0, 1, 1].

• Query examples:

  • Match only structures with exactly 3 periodic dimensions: nperiodic_dimensions=3
  • Match all structures with 2 or fewer periodic dimensions: nperiodic_dimensions<=2

nsites: int pydantic-field required

An integer specifying the length of the cartesian_site_positions property.

• Type: integer

• Requirements/Conventions:

  • Support: SHOULD be supported by all implementations, i.e., SHOULD NOT be null.
  • Query: MUST be a queryable property with support for all mandatory filter features.

• Examples:

  • 42

• Query examples:

  • Match only structures with exactly 4 sites: nsites=4
  • Match structures that have between 2 and 7 sites: nsites>=2 AND nsites<=7

species: list pydantic-field required

A list describing the species of the sites of this structure. Species can represent pure chemical elements, virtual-crystal atoms representing a statistical occupation of a given site by multiple chemical elements, and/or a location to which there are attached atoms, i.e., atoms whose precise location are unknown beyond that they are attached to that position (frequently used to indicate hydrogen atoms attached to another element, e.g., a carbon with three attached hydrogens might represent a methyl group, -CH3).

• Type: list of dictionary with keys:

  • name: string (REQUIRED)
  • chemical_symbols: list of strings (REQUIRED)
  • concentration: list of float (REQUIRED)
  • attached: list of strings (REQUIRED)
  • nattached: list of integers (OPTIONAL)
  • mass: list of floats (OPTIONAL)
  • original_name: string (OPTIONAL).

• Requirements/Conventions:

  • Support: SHOULD be supported by all implementations, i.e., SHOULD NOT be null.
  • Query: Support for queries on this property is OPTIONAL. If supported, filters MAY support only a subset of comparison operators.

  • Each list member MUST be a dictionary with the following keys:

    • name: REQUIRED; gives the name of the species; the name value MUST be unique in the species list;
    • chemical_symbols: REQUIRED; MUST be a list of strings of all chemical elements composing this species. Each item of the list MUST be one of the following:
      • a valid chemical-element symbol, or
      • the special value "X" to represent a non-chemical element, or
      • the special value "vacancy" to represent that this site has a non-zero probability of having a vacancy (the respective probability is indicated in the concentration list, see below).

    If any one entry in the species list has a chemical_symbols list that is longer than 1 element, the correct flag MUST be set in the list structure_features.

    • concentration: REQUIRED; MUST be a list of floats, with same length as chemical_symbols. The numbers represent the relative concentration of the corresponding chemical symbol in this species. The numbers SHOULD sum to one. Cases in which the numbers do not sum to one typically fall only in the following two categories:

      • Numerical errors when representing float numbers in fixed precision, e.g. for two chemical symbols with concentrations 1/3 and 2/3, the concentration might look something like [0.33333333333, 0.66666666666]. If the client is aware that the sum is not one because of numerical precision, it can renormalize the values so that the sum is exactly one.
      • Experimental errors in the data present in the database. In this case, it is the responsibility of the client to decide how to process the data.

      Note that concentrations are uncorrelated between different sites (even of the same species).

    • attached: OPTIONAL; if provided MUST be a list of length 1 or more of strings of chemical symbols for the elements attached to this site, or "X" for a non-chemical element.

    • nattached: OPTIONAL; if provided MUST be a list of length 1 or more of integers indicating the number of attached atoms of the kind specified in the value of the attached key.

    The implementation MUST include either both or none of the attached and nattached keys, and if they are provided, they MUST be of the same length. Furthermore, if they are provided, the structure_features property MUST include the string site_attachments.

    • mass: OPTIONAL. If present MUST be a list of floats, with the same length as chemical_symbols, providing element masses expressed in a.m.u. Elements denoting vacancies MUST have masses equal to 0.

    • original_name: OPTIONAL. Can be any valid Unicode string, and SHOULD contain (if specified) the name of the species that is used internally in the source database.

    Note: With regards to "source database", we refer to the immediate source being queried via the OPTIMADE API implementation.

    The main use of this field is for source databases that use species names, containing characters that are not allowed (see description of the list property species_at_sites).

  • For systems that have only species formed by a single chemical symbol, and that have at most one species per chemical symbol, SHOULD use the chemical symbol as species name (e.g., "Ti" for titanium, "O" for oxygen, etc.) However, note that this is OPTIONAL, and client implementations MUST NOT assume that the key corresponds to a chemical symbol, nor assume that if the species name is a valid chemical symbol, that it represents a species with that chemical symbol. This means that a species {"name": "C", "chemical_symbols": ["Ti"], "concentration": [1.0]} is valid and represents a titanium species (and not a carbon species).

  • It is NOT RECOMMENDED that a structure includes species that do not have at least one corresponding site.

• Examples:

  • [ {"name": "Ti", "chemical_symbols": ["Ti"], "concentration": [1.0]} ]: any site with this species is occupied by a Ti atom.
  • [ {"name": "Ti", "chemical_symbols": ["Ti", "vacancy"], "concentration": [0.9, 0.1]} ]: any site with this species is occupied by a Ti atom with 90 % probability, and has a vacancy with 10 % probability.
  • [ {"name": "BaCa", "chemical_symbols": ["vacancy", "Ba", "Ca"], "concentration": [0.05, 0.45, 0.5], "mass": [0.0, 137.327, 40.078]} ]: any site with this species is occupied by a Ba atom with 45 % probability, a Ca atom with 50 % probability, and by a vacancy with 5 % probability. The mass of this site is (on average) 88.5 a.m.u.
  • [ {"name": "C12", "chemical_symbols": ["C"], "concentration": [1.0], "mass": [12.0]} ]: any site with this species is occupied by a carbon isotope with mass 12.
  • [ {"name": "C13", "chemical_symbols": ["C"], "concentration": [1.0], "mass": [13.0]} ]: any site with this species is occupied by a carbon isotope with mass 13.
  • [ {"name": "CH3", "chemical_symbols": ["C"], "concentration": [1.0], "attached": ["H"], "nattached": [3]} ]: any site with this species is occupied by a methyl group, -CH3, which is represented without specifying precise positions of the hydrogen atoms.

species_at_sites: list pydantic-field required

Name of the species at each site (where values for sites are specified with the same order of the property cartesian_site_positions). The properties of the species are found in the property species.

• Type: list of strings.

• Requirements/Conventions:

  • Support: SHOULD be supported by all implementations, i.e., SHOULD NOT be null.
  • Query: Support for queries on this property is OPTIONAL. If supported, filters MAY support only a subset of comparison operators.
  • MUST have length equal to the number of sites in the structure (first dimension of the list property cartesian_site_positions).
  • Each species name mentioned in the species_at_sites list MUST be described in the list property species (i.e. for each value in the species_at_sites list there MUST exist exactly one dictionary in the species list with the name attribute equal to the corresponding species_at_sites value).
  • Each site MUST be associated only to a single species. Note: However, species can represent mixtures of atoms, and multiple species MAY be defined for the same chemical element. This latter case is useful when different atoms of the same type need to be grouped or distinguished, for instance in simulation codes to assign different initial spin states.

• Examples:

  • ["Ti","O2"] indicates that the first site is hosting a species labeled "Ti" and the second a species labeled "O2".
  • ["Ac", "Ac", "Ag", "Ir"] indicating the first two sites contains the "Ac" species, while the third and fourth sites contain the "Ag" and "Ir" species, respectively.

structure_features: list pydantic-field required

A list of strings that flag which special features are used by the structure.

• Type: list of strings

• Requirements/Conventions:

  • Support: MUST be supported by all implementations, MUST NOT be null.
  • Query: MUST be a queryable property. Filters on the list MUST support all mandatory HAS-type queries. Filter operators for comparisons on the string components MUST support equality, support for other comparison operators are OPTIONAL.
  • MUST be an empty list if no special features are used.
  • MUST be sorted alphabetically.
  • If a special feature listed below is used, the list MUST contain the corresponding string.
  • If a special feature listed below is not used, the list MUST NOT contain the corresponding string.
  • List of strings used to indicate special structure features:
    • disorder: this flag MUST be present if any one entry in the species list has a chemical_symbols list that is longer than 1 element.
    • implicit_atoms: this flag MUST be present if the structure contains atoms that are not assigned to sites via the property species_at_sites (e.g., because their positions are unknown). When this flag is present, the properties related to the chemical formula will likely not match the type and count of atoms represented by the species_at_sites, species and assemblies properties.
    • site_attachments: this flag MUST be present if any one entry in the species list includes attached and nattached.
    • assemblies: this flag MUST be present if the property assemblies is present.

• Examples: A structure having implicit atoms and using assemblies: ["assemblies", "implicit_atoms"]

Config

Source code in optimade/models/structures.py

class Config:
    def schema_extra(schema, model):
        """Two things need to be added to the schema:

        1. Constrained types in pydantic do not currently play nicely with
        "Required Optional" fields, i.e. fields must be specified but can be null.
        The two contrained list fields, `dimension_types` and `lattice_vectors`,
        are OPTIMADE 'SHOULD' fields, which means that they are allowed to be null.

        2. All OPTIMADE 'SHOULD' fields are allowed to be null, so we manually set them
        to be `nullable` according to the OpenAPI definition.

        """
        schema["required"].insert(7, "dimension_types")
        schema["required"].insert(9, "lattice_vectors")

        nullable_props = (
            prop
            for prop in schema["required"]
            if schema["properties"][prop].get("x-optimade-support")
            == SupportLevel.SHOULD
        )
        for prop in nullable_props:
            schema["properties"][prop]["nullable"] = True

schema_extra(schema, model)

Two things need to be added to the schema:

1. Constrained types in pydantic do not currently play nicely with "Required Optional" fields, i.e. fields must be specified but can be null. The two contrained list fields, dimension_types and lattice_vectors, are OPTIMADE 'SHOULD' fields, which means that they are allowed to be null.

2. All OPTIMADE 'SHOULD' fields are allowed to be null, so we manually set them to be nullable according to the OpenAPI definition.

Source code in optimade/models/structures.py

def schema_extra(schema, model):
    """Two things need to be added to the schema:

    1. Constrained types in pydantic do not currently play nicely with
    "Required Optional" fields, i.e. fields must be specified but can be null.
    The two contrained list fields, `dimension_types` and `lattice_vectors`,
    are OPTIMADE 'SHOULD' fields, which means that they are allowed to be null.

    2. All OPTIMADE 'SHOULD' fields are allowed to be null, so we manually set them
    to be `nullable` according to the OpenAPI definition.

    """
    schema["required"].insert(7, "dimension_types")
    schema["required"].insert(9, "lattice_vectors")

    nullable_props = (
        prop
        for prop in schema["required"]
        if schema["properties"][prop].get("x-optimade-support")
        == SupportLevel.SHOULD
    )
    for prop in nullable_props:
        schema["properties"][prop]["nullable"] = True

warn_on_missing_correlated_fields(values) classmethod

Emit warnings if a field takes a null value when a value was expected based on the value/nullity of another field.

Source code in optimade/models/structures.py

@root_validator(pre=True)
def warn_on_missing_correlated_fields(cls, values):
    """Emit warnings if a field takes a null value when a value
    was expected based on the value/nullity of another field.
    """
    accumulated_warnings = []
    for field_set in CORRELATED_STRUCTURE_FIELDS:
        missing_fields = {f for f in field_set if values.get(f) is None}
        if missing_fields and len(missing_fields) != len(field_set):
            accumulated_warnings += [
                f"Structure with values {values} is missing fields {missing_fields} which are required if {field_set - missing_fields} are present."
            ]

    for warn in accumulated_warnings:
        warnings.warn(warn, MissingExpectedField)

    return values

utils

ANONYMOUS_ELEMENTS

Returns the first 150 values of the anonymous element generator.

SemanticVersion (str)

A custom type for a semantic version, using the recommended semver regexp from https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string.

Source code in optimade/models/utils.py

class SemanticVersion(str):
    """A custom type for a semantic version, using the recommended
    semver regexp from
    https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string.

    """

    regex = re.compile(
        r"^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$"
    )

    @classmethod
    def __get_validators__(cls):
        yield cls.validate

    @classmethod
    def __modify_schema__(cls, field_schema):
        field_schema.update(
            pattern=cls.regex.pattern,
            example=["0.10.1", "1.0.0-rc.2", "1.2.3-rc.5+develop"],
        )

    @classmethod
    def validate(cls, v: str):
        if not cls.regex.match(v):
            raise ValueError(
                f"Unable to validate the version string {v!r} as a semantic version (expected <major>.<minor>.<patch>)."
                "See https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string for more information."
            )

        return v

    @property
    def _match(self):
        """The result of the regex match."""
        return self.regex.match(self)

    @property
    def major(self) -> int:
        """The major version number."""
        return int(self._match.group(1))

    @property
    def minor(self) -> int:
        """The minor version number."""
        return int(self._match.group(2))

    @property
    def patch(self) -> int:
        """The patch version number."""
        return int(self._match.group(3))

    @property
    def prerelease(self) -> str:
        """The pre-release tag."""
        return self._match.group(4)

    @property
    def build_metadata(self) -> str:
        """The build metadata."""
        return self._match.group(5)

    @property
    def base_version(self) -> str:
        """The base version string without patch and metadata info."""
        return f"{self.major}.{self.minor}.{self.patch}"

base_version: str property readonly

The base version string without patch and metadata info.

build_metadata: str property readonly

The build metadata.

major: int property readonly

The major version number.

minor: int property readonly

The minor version number.

patch: int property readonly

The patch version number.

prerelease: str property readonly

The pre-release tag.

StrictFieldInfo (FieldInfo)

Wraps the standard pydantic FieldInfo in order to prefix any custom keys from StrictField.

Source code in optimade/models/utils.py

class StrictFieldInfo(FieldInfo):
    """Wraps the standard pydantic `FieldInfo` in order
    to prefix any custom keys from `StrictField`.

    """

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        for key in OPTIMADE_SCHEMA_EXTENSION_KEYS:
            if key in self.extra:
                self.extra[f"{OPTIMADE_SCHEMA_EXTENSION_PREFIX}{key}"] = self.extra.pop(
                    key
                )

__init__(self, *args, **kwargs) special

Initialize self. See help(type(self)) for accurate signature.

Source code in optimade/models/utils.py

def __init__(self, *args, **kwargs):
    super().__init__(*args, **kwargs)
    for key in OPTIMADE_SCHEMA_EXTENSION_KEYS:
        if key in self.extra:
            self.extra[f"{OPTIMADE_SCHEMA_EXTENSION_PREFIX}{key}"] = self.extra.pop(
                key
            )

SupportLevel (Enum)

OPTIMADE property/field support levels

Source code in optimade/models/utils.py

class SupportLevel(Enum):
    """OPTIMADE property/field support levels"""

    MUST = "must"
    SHOULD = "should"
    OPTIONAL = "optional"

OptimadeField(*args, *, support=None, queryable=None, unit=None, **kwargs)

A wrapper around pydantic.Field that adds OPTIMADE-specific field paramters queryable, support and unit, indicating the corresponding support level in the specification and the physical unit of the field.

Parameters:

Name	Type	Description	Default
support	Union[str, optimade.models.utils.SupportLevel]	The support level of the field itself, i.e. whether the field can be null or omitted by an implementation.	None
queryable	Union[str, optimade.models.utils.SupportLevel]	The support level corresponding to the queryablility of this field.	None
unit	Optional[str]	A string describing the unit of the field.	None

Returns:

Type	Description
<cyfunction Field at 0x7fad4228e810>	The pydantic field with extra validation provided by StrictField.

Source code in optimade/models/utils.py

def OptimadeField(
    *args,
    support: Optional[Union[str, SupportLevel]] = None,
    queryable: Optional[Union[str, SupportLevel]] = None,
    unit: Optional[str] = None,
    **kwargs,
) -> Field:
    """A wrapper around `pydantic.Field` that adds OPTIMADE-specific
    field paramters `queryable`, `support` and `unit`, indicating
    the corresponding support level in the specification and the
    physical unit of the field.

    Arguments:
        support: The support level of the field itself, i.e. whether the field
            can be null or omitted by an implementation.
        queryable: The support level corresponding to the queryablility
            of this field.
        unit: A string describing the unit of the field.

    Returns:
        The pydantic field with extra validation provided by [`StrictField`][optimade.models.utils.StrictField].

    """

    # Collect non-null keyword arguments to add to the Field schema
    if unit is not None:
        kwargs["unit"] = unit
    if queryable is not None:
        if isinstance(queryable, str):
            queryable = SupportLevel(queryable.lower())
        kwargs["queryable"] = queryable
    if support is not None:
        if isinstance(support, str):
            support = SupportLevel(support.lower())
        kwargs["support"] = support

    return StrictField(*args, **kwargs)

StrictField(*args, *, description=None, **kwargs)

A wrapper around pydantic.Field that does the following:

• Forbids any "extra" keys that would be passed to pydantic.Field, except those used elsewhere to modify the schema in-place, e.g. "uniqueItems", "pattern" and those added by OptimadeField, e.g. "unit", "queryable" and "sortable".
• Emits a warning when no description is provided.

Parameters:

Name	Type	Description	Default
*args	Any	Positional arguments passed through to Field.	()
description	Optional[str]	The description of the Field; if this is not specified then a UserWarning will be emitted.	None
**kwargs	Any	Extra keyword arguments to be passed to Field.	{}

Exceptions:

Type	Description
RuntimeError	If **kwargs contains a key not found in the function signature of Field, or in the extensions used by models in this package (see above).

Returns:

Type	Description
StrictFieldInfo	The pydantic Field.

Source code in optimade/models/utils.py

def StrictField(
    *args: "Any",
    description: Optional[str] = None,
    **kwargs: "Any",
) -> StrictFieldInfo:
    """A wrapper around `pydantic.Field` that does the following:

    - Forbids any "extra" keys that would be passed to `pydantic.Field`,
      except those used elsewhere to modify the schema in-place,
      e.g. "uniqueItems", "pattern" and those added by OptimadeField, e.g.
      "unit", "queryable" and "sortable".
    - Emits a warning when no description is provided.

    Arguments:
        *args: Positional arguments passed through to `Field`.
        description: The description of the `Field`; if this is not
            specified then a `UserWarning` will be emitted.
        **kwargs: Extra keyword arguments to be passed to `Field`.

    Raises:
        RuntimeError: If `**kwargs` contains a key not found in the
            function signature of `Field`, or in the extensions used
            by models in this package (see above).

    Returns:
        The pydantic `Field`.

    """

    allowed_keys = [
        "pattern",
        "uniqueItems",
        "nullable",
    ] + OPTIMADE_SCHEMA_EXTENSION_KEYS
    _banned = [k for k in kwargs if k not in set(_PYDANTIC_FIELD_KWARGS + allowed_keys)]

    if _banned:
        raise RuntimeError(
            f"Not creating StrictField({args}, {kwargs}) with forbidden keywords {_banned}."
        )

    if description is not None:
        kwargs["description"] = description

    if description is None:
        warnings.warn(
            f"No description provided for StrictField specified by {args}, {kwargs}."
        )

    return StrictPydanticField(*args, **kwargs)

StrictPydanticField(*args, **kwargs)

Wrapper for Field that uses StrictFieldInfo instead of the pydantic FieldInfo.

Source code in optimade/models/utils.py

def StrictPydanticField(*args, **kwargs):
    """Wrapper for `Field` that uses `StrictFieldInfo` instead of
    the pydantic `FieldInfo`.
    """
    field_info = StrictFieldInfo(*args, **kwargs)
    field_info._validate()
    return field_info

anonymize_formula(formula)

Takes a string representation of a chemical formula of the form [A-Z][a-z]*[0-9]* (potentially with whitespace) and returns the OPTIMADE chemical_formula_anonymous representation, i.e., a reduced chemical formula comprising of element symbols drawn from A, B, C... ordered from largest proportion to smallest.

Returns:

Type	Description
str	The anonymous chemical formula in the OPTIMADE representation.

Source code in optimade/models/utils.py

def anonymize_formula(formula: str) -> str:
    """Takes a string representation of a chemical formula of the form `[A-Z][a-z]*[0-9]*` (potentially with whitespace) and
    returns the OPTIMADE `chemical_formula_anonymous` representation, i.e., a reduced chemical formula comprising of element symbols
    drawn from A, B, C... ordered from largest proportion to smallest.

    Returns:
        The anonymous chemical formula in the OPTIMADE representation.

    """
    return _reduce_or_anonymize_formula(formula, alphabetize=False, anonymize=True)

anonymous_element_generator()

Generator that yields the next symbol in the A, B, Aa, ... Az naming scheme.

Source code in optimade/models/utils.py

def anonymous_element_generator():
    """Generator that yields the next symbol in the A, B, Aa, ... Az naming scheme."""
    from string import ascii_lowercase

    for size in itertools.count(1):
        for s in itertools.product(ascii_lowercase, repeat=size):
            s = list(s)
            s[0] = s[0].upper()
            yield "".join(s)

reduce_formula(formula)

Takes a string representation of a chemical formula of the form [A-Z][a-z]*[0-9]* (potentially with whitespace) and reduces it by the GCD of the proportion integers present in the formula, stripping any leftover "1" values.

Returns:

Type	Description
str	The reduced chemical formula in the OPTIMADE representation.

Source code in optimade/models/utils.py

def reduce_formula(formula: str) -> str:
    """Takes a string representation of a chemical formula of the form `[A-Z][a-z]*[0-9]*` (potentially with whitespace) and
    reduces it by the GCD of the proportion integers present in the formula, stripping any leftover "1" values.

    Returns:
        The reduced chemical formula in the OPTIMADE representation.

    """
    return _reduce_or_anonymize_formula(formula, alphabetize=True, anonymize=False)