Skip to content

references

__all__ = ('Person', 'ReferenceResourceAttributes', 'ReferenceResource') module-attribute

EntryResource

Bases: Resource

The base model for an entry resource.

Source code in optimade/models/entries.py 
119
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
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[
        Optional[EntryRelationships],
        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[Optional[Meta], 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[Optional[EntryRelationships], 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 
 68
 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
class EntryResourceAttributes(Attributes):
    """Contains key-value pairs representing the entry's properties."""

    immutable_id: Annotated[
        Optional[str],
        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[
        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,
        ),
    ]

    @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[Optional[str], 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[Optional[datetime], 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 
109
110
111
112
113
114
115
116
@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 
329
330
331
332
333
334
335
336
337
@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

Person

Bases: BaseModel

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

Source code in optimade/models/references.py 
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
class Person(BaseModel):
    """A person, i.e., an author, editor or other."""

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

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

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

firstname: Annotated[Optional[str], OptimadeField(description='First name of the person.', support=SupportLevel.OPTIONAL, queryable=SupportLevel.OPTIONAL)] = None class-attribute instance-attribute

lastname: Annotated[Optional[str], OptimadeField(description='Last name of the person.', support=SupportLevel.OPTIONAL, queryable=SupportLevel.OPTIONAL)] = None class-attribute instance-attribute

name: Annotated[str, OptimadeField(description='Full name of the person, REQUIRED.', support=SupportLevel.MUST, queryable=SupportLevel.OPTIONAL)] instance-attribute

ReferenceResource

Bases: 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, 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 
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
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: Annotated[
        Literal["references"],
        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"`""",
            pattern="^references$",
            support=SupportLevel.MUST,
            queryable=SupportLevel.MUST,
        ),
    ] = "references"
    attributes: ReferenceResourceAttributes

    @field_validator("attributes", mode="before")
    @classmethod
    def validate_attributes(cls, value: Any) -> dict[str, Any]:
        if not isinstance(value, dict):
            if isinstance(value, BaseModel):
                value = value.model_dump()
            else:
                raise TypeError("attributes field must be a mapping")
        if not any(prop[1] is not None for prop in value):
            raise ValueError("reference object must have at least one field defined")
        return value

attributes: ReferenceResourceAttributes 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[Optional[Meta], 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[Optional[EntryRelationships], 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[Literal['references'], OptimadeField(description='The name of the type of an entry.\n- **Type**: string.\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- **Example**: `"structures"`', pattern='^references$', support=SupportLevel.MUST, queryable=SupportLevel.MUST)] = 'references' class-attribute instance-attribute

validate_attributes(value) classmethod

Source code in optimade/models/references.py 
323
324
325
326
327
328
329
330
331
332
333
@field_validator("attributes", mode="before")
@classmethod
def validate_attributes(cls, value: Any) -> dict[str, Any]:
    if not isinstance(value, dict):
        if isinstance(value, BaseModel):
            value = value.model_dump()
        else:
            raise TypeError("attributes field must be a mapping")
    if not any(prop[1] is not None for prop in value):
        raise ValueError("reference object must have at least one field defined")
    return value

ReferenceResourceAttributes

Bases: EntryResourceAttributes

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 
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 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
118
119
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
181
182
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
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
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: Annotated[
        Optional[list[Person]],
        OptimadeField(
            description="List of person objects containing the authors of the reference.",
            support=SupportLevel.OPTIONAL,
            queryable=SupportLevel.OPTIONAL,
        ),
    ] = None

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

address: Annotated[Optional[str], OptimadeField(description='Meaning of property matches the BiBTeX specification.', support=SupportLevel.OPTIONAL, queryable=SupportLevel.OPTIONAL)] = None class-attribute instance-attribute

annote: Annotated[Optional[str], OptimadeField(description='Meaning of property matches the BiBTeX specification.', support=SupportLevel.OPTIONAL, queryable=SupportLevel.OPTIONAL)] = None class-attribute instance-attribute

authors: Annotated[Optional[list[Person]], OptimadeField(description='List of person objects containing the authors of the reference.', support=SupportLevel.OPTIONAL, queryable=SupportLevel.OPTIONAL)] = None class-attribute instance-attribute

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

booktitle: Annotated[Optional[str], OptimadeField(description='Meaning of property matches the BiBTeX specification.', support=SupportLevel.OPTIONAL, queryable=SupportLevel.OPTIONAL)] = None class-attribute instance-attribute

chapter: Annotated[Optional[str], OptimadeField(description='Meaning of property matches the BiBTeX specification.', support=SupportLevel.OPTIONAL, queryable=SupportLevel.OPTIONAL)] = None class-attribute instance-attribute

crossref: Annotated[Optional[str], OptimadeField(description='Meaning of property matches the BiBTeX specification.', support=SupportLevel.OPTIONAL, queryable=SupportLevel.OPTIONAL)] = None class-attribute instance-attribute

doi: Annotated[Optional[str], OptimadeField(description='The digital object identifier of the reference.', support=SupportLevel.OPTIONAL, queryable=SupportLevel.OPTIONAL)] = None class-attribute instance-attribute

edition: Annotated[Optional[str], OptimadeField(description='Meaning of property matches the BiBTeX specification.', support=SupportLevel.OPTIONAL, queryable=SupportLevel.OPTIONAL)] = None class-attribute instance-attribute

editors: Annotated[Optional[list[Person]], OptimadeField(description='List of person objects containing the editors of the reference.', support=SupportLevel.OPTIONAL, queryable=SupportLevel.OPTIONAL)] = None class-attribute instance-attribute

howpublished: Annotated[Optional[str], OptimadeField(description='Meaning of property matches the BiBTeX specification.', support=SupportLevel.OPTIONAL, queryable=SupportLevel.OPTIONAL)] = None class-attribute instance-attribute

immutable_id: Annotated[Optional[str], 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

institution: Annotated[Optional[str], OptimadeField(description='Meaning of property matches the BiBTeX specification.', support=SupportLevel.OPTIONAL, queryable=SupportLevel.OPTIONAL)] = None class-attribute instance-attribute

journal: Annotated[Optional[str], OptimadeField(description='Meaning of property matches the BiBTeX specification.', support=SupportLevel.OPTIONAL, queryable=SupportLevel.OPTIONAL)] = None class-attribute instance-attribute

key: Annotated[Optional[str], OptimadeField(description='Meaning of property matches the BiBTeX specification.', support=SupportLevel.OPTIONAL, queryable=SupportLevel.OPTIONAL)] = None class-attribute instance-attribute

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

month: Annotated[Optional[str], OptimadeField(description='Meaning of property matches the BiBTeX specification.', support=SupportLevel.OPTIONAL, queryable=SupportLevel.OPTIONAL)] = None class-attribute instance-attribute

note: Annotated[Optional[str], OptimadeField(description='Meaning of property matches the BiBTeX specification.', support=SupportLevel.OPTIONAL, queryable=SupportLevel.OPTIONAL)] = None class-attribute instance-attribute

number: Annotated[Optional[str], OptimadeField(description='Meaning of property matches the BiBTeX specification.', support=SupportLevel.OPTIONAL, queryable=SupportLevel.OPTIONAL)] = None class-attribute instance-attribute

organization: Annotated[Optional[str], OptimadeField(description='Meaning of property matches the BiBTeX specification.', support=SupportLevel.OPTIONAL, queryable=SupportLevel.OPTIONAL)] = None class-attribute instance-attribute

pages: Annotated[Optional[str], OptimadeField(description='Meaning of property matches the BiBTeX specification.', support=SupportLevel.OPTIONAL, queryable=SupportLevel.OPTIONAL)] = None class-attribute instance-attribute

publisher: Annotated[Optional[str], OptimadeField(description='Meaning of property matches the BiBTeX specification.', support=SupportLevel.OPTIONAL, queryable=SupportLevel.OPTIONAL)] = None class-attribute instance-attribute

school: Annotated[Optional[str], OptimadeField(description='Meaning of property matches the BiBTeX specification.', support=SupportLevel.OPTIONAL, queryable=SupportLevel.OPTIONAL)] = None class-attribute instance-attribute

series: Annotated[Optional[str], OptimadeField(description='Meaning of property matches the BiBTeX specification.', support=SupportLevel.OPTIONAL, queryable=SupportLevel.OPTIONAL)] = None class-attribute instance-attribute

title: Annotated[Optional[str], OptimadeField(description='Meaning of property matches the BiBTeX specification.', support=SupportLevel.OPTIONAL, queryable=SupportLevel.OPTIONAL)] = None class-attribute instance-attribute

url: Annotated[Optional[AnyUrl], OptimadeField(description='The URL of the reference.', support=SupportLevel.OPTIONAL, queryable=SupportLevel.OPTIONAL)] = None class-attribute instance-attribute

volume: Annotated[Optional[str], OptimadeField(description='Meaning of property matches the BiBTeX specification.', support=SupportLevel.OPTIONAL, queryable=SupportLevel.OPTIONAL)] = None class-attribute instance-attribute

year: Annotated[Optional[str], OptimadeField(description='Meaning of property matches the BiBTeX specification.', support=SupportLevel.OPTIONAL, queryable=SupportLevel.OPTIONAL)] = None 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 
109
110
111
112
113
114
115
116
@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 
329
330
331
332
333
334
335
336
337
@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

SupportLevel

Bases: Enum

OPTIMADE property/field support levels

Source code in optimade/models/utils.py 
31
32
33
34
35
36
class SupportLevel(Enum):
    """OPTIMADE property/field support levels"""

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

MUST = 'must' class-attribute instance-attribute

OPTIONAL = 'optional' class-attribute instance-attribute

SHOULD = 'should' class-attribute instance-attribute

OptimadeField(default=PydanticUndefined, *, 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 Optional[Union[str, SupportLevel]]

The support level of the field itself, i.e. whether the field can be null or omitted by an implementation.

 None
queryable Optional[Union[str, 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
Any

The pydantic field with extra validation provided by StrictField.
Source code in optimade/models/utils.py 
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
def OptimadeField(
    default: "Any" = PydanticUndefined,
    *,
    support: Optional[Union[str, SupportLevel]] = None,
    queryable: Optional[Union[str, SupportLevel]] = None,
    unit: Optional[str] = None,
    **kwargs,
) -> Any:
    """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(default, **kwargs)