Skip to content

references

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 
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