Skip to content

entries

EntryInfoProperty

Bases: BaseModel

Source code in optimade/models/entries.py 
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
class EntryInfoProperty(BaseModel):
    description: Annotated[
        str,
        StrictField(description="A human-readable description of the entry property"),
    ]

    unit: Annotated[
        str | None,
        StrictField(
            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.""",
        ),
    ] = None

    sortable: Annotated[
        bool | None,
        StrictField(
            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`.""",
        ),
    ] = None

    type: Annotated[
        DataType | None,
        StrictField(
            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`.""",
        ),
    ] = None

description: Annotated[str, StrictField(description='A human-readable description of the entry property')] instance-attribute

sortable: Annotated[bool | None, StrictField(description='Defines whether the entry property can be used for sorting with the "sort" parameter.\nIf the entry listing endpoint supports sorting, this key MUST be present for sortable properties with value `true`.')] = None class-attribute instance-attribute

type: Annotated[DataType | None, StrictField(title=Type, description="The type of the property's value.\nThis MUST be any of the types defined in the Data types section.\nFor 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.\nNote, if the value is a nested type, only the outermost type should be reported.\nE.g., for the entry resource `structures`, the `species` property is defined as a list of dictionaries, hence its `type` value would be `list`.")] = None class-attribute instance-attribute

unit: Annotated[str | None, StrictField(description='The physical unit of the entry property.\nThis 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).\nIt is RECOMMENDED that non-standard (non-SI) units are described in the description for the property.')] = None class-attribute instance-attribute

EntryInfoResource

Bases: BaseModel

Source code in optimade/models/entries.py 
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
class EntryInfoResource(BaseModel):
    formats: Annotated[
        list[str],
        StrictField(
            description="List of output formats available for this type of entry."
        ),
    ]

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

    properties: Annotated[
        dict[ValidIdentifier, EntryInfoProperty],
        StrictField(
            description="A dictionary describing queryable properties for this entry type, where each key is a property name.",
        ),
    ]

    output_fields_by_format: Annotated[
        dict[str, list[ValidIdentifier]],
        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: Annotated[str, StrictField(description='Description of the entry.')] instance-attribute

formats: Annotated[list[str], StrictField(description='List of output formats available for this type of entry.')] instance-attribute

output_fields_by_format: Annotated[dict[str, list[ValidIdentifier]], 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.')] instance-attribute

properties: Annotated[dict[ValidIdentifier, EntryInfoProperty], StrictField(description='A dictionary describing queryable properties for this entry type, where each key is a property name.')] instance-attribute

EntryRelationships

Bases: Relationships

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

Source code in optimade/models/entries.py 
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
class EntryRelationships(Relationships):
    """This model wraps the JSON API Relationships to include type-specific top level keys."""

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

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

references: Annotated[ReferenceRelationship | None, StrictField(description='Object containing links to relationships with entries of the `references` type.')] = None class-attribute instance-attribute

structures: Annotated[StructureRelationship | None, StrictField(description='Object containing links to relationships with entries of the `structures` type.')] = None class-attribute instance-attribute

check_illegal_relationships_fields()

Source code in optimade/models/jsonapi.py 
296
297
298
299
300
301
302
303
304
@model_validator(mode="after")
def check_illegal_relationships_fields(self) -> "Relationships":
    illegal_fields = ("id", "type")
    for field in illegal_fields:
        if hasattr(self, field):
            raise ValueError(
                f"{illegal_fields} MUST NOT be fields under Relationships"
            )
    return self

EntryResource

Bases: Resource

The base model for an entry resource.

Source code in optimade/models/entries.py 
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
class EntryResource(Resource):
    """The base model for an entry resource."""

    id: Annotated[
        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: Annotated[
        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: Annotated[
        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: Annotated[
        EntryRelationships | None,
        StrictField(
            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.""",
        ),
    ] = None

attributes: Annotated[EntryResourceAttributes, StrictField(description="A dictionary, containing key-value pairs representing the entry's properties, except for `type` and `id`.\nDatabase-provider-specific properties need to include the database-provider-specific prefix (see section on Database-Provider-Specific Namespace Prefixes).")] instance-attribute

id: Annotated[str, OptimadeField(description='An entry\'s ID as defined in section Definition of Terms.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n\n- **Examples**:\n - `"db/1234567"`\n - `"cod/2000000"`\n - `"cod/2000000@1234567"`\n - `"nomad/L1234567890"`\n - `"42"`', support=SupportLevel.MUST, queryable=SupportLevel.MUST)] instance-attribute

meta: Annotated[Meta | None, StrictField(description='a meta object containing non-standard meta-information about a resource that can not be represented as an attribute or relationship.')] = None class-attribute instance-attribute

model_config = ConfigDict(json_schema_extra=resource_json_schema_extra) class-attribute instance-attribute

relationships: Annotated[EntryRelationships | None, StrictField(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).\nThe 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.')] = None class-attribute instance-attribute

type: Annotated[str, OptimadeField(description='The name of the type of an entry.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - MUST be an existing entry type.\n - The entry of type `<type>` and ID `<id>` MUST be returned in response to a request for `/<type>/<id>` under the versioned base URL.\n\n- **Example**: `"structures"`', support=SupportLevel.MUST, queryable=SupportLevel.MUST)] instance-attribute

EntryResourceAttributes

Bases: Attributes

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

Source code in optimade/models/entries.py 
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
class EntryResourceAttributes(Attributes):
    """Contains key-value pairs representing the entry's properties."""

    immutable_id: Annotated[
        str | None,
        OptimadeField(
            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,
        ),
    ] = None

    last_modified: Annotated[
        datetime | None,
        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,
        ),
    ]

    @field_validator("immutable_id", mode="before")
    @classmethod
    def cast_immutable_id_to_str(cls, value: Any) -> str:
        """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: Annotated[str | None, OptimadeField(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.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: OPTIONAL support in implementations, i.e., MAY be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n\n- **Examples**:\n - `"8bd3e750-b477-41a0-9b11-3a799f21b44f"`\n - `"fjeiwoj,54;@=%<>#32"` (Strings that are not URL-safe are allowed.)', support=SupportLevel.OPTIONAL, queryable=SupportLevel.MUST)] = None class-attribute instance-attribute

last_modified: Annotated[datetime | None, OptimadeField(description='Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n - 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)] instance-attribute

model_config = ConfigDict(extra='allow') class-attribute instance-attribute

cast_immutable_id_to_str(value) classmethod

Convenience validator for casting immutable_id to a string.

Source code in optimade/models/entries.py 
110
111
112
113
114
115
116
117
@field_validator("immutable_id", mode="before")
@classmethod
def cast_immutable_id_to_str(cls, value: Any) -> str:
    """Convenience validator for casting `immutable_id` to a string."""
    if value is not None and not isinstance(value, str):
        value = str(value)

    return value

check_illegal_attributes_fields()

Source code in optimade/models/jsonapi.py 
330
331
332
333
334
335
336
337
338
@model_validator(mode="after")
def check_illegal_attributes_fields(self) -> "Attributes":
    illegal_fields = ("relationships", "links", "id", "type")
    for field in illegal_fields:
        if hasattr(self, field):
            raise ValueError(
                f"{illegal_fields} MUST NOT be fields under Attributes"
            )
    return self

ReferenceRelationship

Bases: TypedRelationship

Source code in optimade/models/entries.py 
43
44
class ReferenceRelationship(TypedRelationship):
    _req_type: ClassVar[Literal["references"]] = "references"

data: Annotated[BaseRelationshipResource | list[BaseRelationshipResource] | None, StrictField(description='Resource linkage', uniqueItems=True)] = None class-attribute instance-attribute

meta: Annotated[Meta | None, StrictField(description='a meta object that contains non-standard meta-information about the relationship.')] = None class-attribute instance-attribute

at_least_one_relationship_key_must_be_set()

Source code in optimade/models/jsonapi.py 
279
280
281
282
283
284
285
@model_validator(mode="after")
def at_least_one_relationship_key_must_be_set(self) -> "Relationship":
    if self.links is None and self.data is None and self.meta is None:
        raise ValueError(
            "Either 'links', 'data', or 'meta' MUST be specified for Relationship"
        )
    return self

check_rel_type(data) classmethod

Source code in optimade/models/entries.py 
27
28
29
30
31
32
33
34
35
36
37
38
39
40
@field_validator("data", mode="after")
@classmethod
def check_rel_type(
    cls, data: BaseRelationshipResource | list[BaseRelationshipResource]
) -> list[BaseRelationshipResource]:
    if not isinstance(data, list):
        # All relationships at this point are empty-to-many relationships in JSON:API:
        # https://jsonapi.org/format/1.0/#document-resource-object-linkage
        raise ValueError("`data` key in a relationship must always store a list.")

    if any(obj.type != cls._req_type for obj in data):
        raise ValueError("Object stored in relationship data has wrong type")

    return data

StructureRelationship

Bases: TypedRelationship

Source code in optimade/models/entries.py 
47
48
class StructureRelationship(TypedRelationship):
    _req_type: ClassVar[Literal["structures"]] = "structures"

data: Annotated[BaseRelationshipResource | list[BaseRelationshipResource] | None, StrictField(description='Resource linkage', uniqueItems=True)] = None class-attribute instance-attribute

meta: Annotated[Meta | None, StrictField(description='a meta object that contains non-standard meta-information about the relationship.')] = None class-attribute instance-attribute

at_least_one_relationship_key_must_be_set()

Source code in optimade/models/jsonapi.py 
279
280
281
282
283
284
285
@model_validator(mode="after")
def at_least_one_relationship_key_must_be_set(self) -> "Relationship":
    if self.links is None and self.data is None and self.meta is None:
        raise ValueError(
            "Either 'links', 'data', or 'meta' MUST be specified for Relationship"
        )
    return self

check_rel_type(data) classmethod

Source code in optimade/models/entries.py 
27
28
29
30
31
32
33
34
35
36
37
38
39
40
@field_validator("data", mode="after")
@classmethod
def check_rel_type(
    cls, data: BaseRelationshipResource | list[BaseRelationshipResource]
) -> list[BaseRelationshipResource]:
    if not isinstance(data, list):
        # All relationships at this point are empty-to-many relationships in JSON:API:
        # https://jsonapi.org/format/1.0/#document-resource-object-linkage
        raise ValueError("`data` key in a relationship must always store a list.")

    if any(obj.type != cls._req_type for obj in data):
        raise ValueError("Object stored in relationship data has wrong type")

    return data

TypedRelationship

Bases: Relationship

Source code in optimade/models/entries.py 
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
class TypedRelationship(Relationship):
    _req_type: ClassVar[str]

    @field_validator("data", mode="after")
    @classmethod
    def check_rel_type(
        cls, data: BaseRelationshipResource | list[BaseRelationshipResource]
    ) -> list[BaseRelationshipResource]:
        if not isinstance(data, list):
            # All relationships at this point are empty-to-many relationships in JSON:API:
            # https://jsonapi.org/format/1.0/#document-resource-object-linkage
            raise ValueError("`data` key in a relationship must always store a list.")

        if any(obj.type != cls._req_type for obj in data):
            raise ValueError("Object stored in relationship data has wrong type")

        return data

data: Annotated[BaseRelationshipResource | list[BaseRelationshipResource] | None, StrictField(description='Resource linkage', uniqueItems=True)] = None class-attribute instance-attribute

meta: Annotated[Meta | None, StrictField(description='a meta object that contains non-standard meta-information about the relationship.')] = None class-attribute instance-attribute

at_least_one_relationship_key_must_be_set()

Source code in optimade/models/jsonapi.py 
279
280
281
282
283
284
285
@model_validator(mode="after")
def at_least_one_relationship_key_must_be_set(self) -> "Relationship":
    if self.links is None and self.data is None and self.meta is None:
        raise ValueError(
            "Either 'links', 'data', or 'meta' MUST be specified for Relationship"
        )
    return self

check_rel_type(data) classmethod

Source code in optimade/models/entries.py 
27
28
29
30
31
32
33
34
35
36
37
38
39
40
@field_validator("data", mode="after")
@classmethod
def check_rel_type(
    cls, data: BaseRelationshipResource | list[BaseRelationshipResource]
) -> list[BaseRelationshipResource]:
    if not isinstance(data, list):
        # All relationships at this point are empty-to-many relationships in JSON:API:
        # https://jsonapi.org/format/1.0/#document-resource-object-linkage
        raise ValueError("`data` key in a relationship must always store a list.")

    if any(obj.type != cls._req_type for obj in data):
        raise ValueError("Object stored in relationship data has wrong type")

    return data