Skip to content

references

Person

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

Source code in optimade/models/references.py 
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
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: Optional[str] = OptimadeField(None, description='First name of the person.', support=SupportLevel.OPTIONAL, queryable=SupportLevel.OPTIONAL) class-attribute

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

name: str = OptimadeField(Ellipsis, description='Full name of the person, REQUIRED.', support=SupportLevel.MUST, queryable=SupportLevel.OPTIONAL) class-attribute

ReferenceResource

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

attributes: ReferenceResourceAttributes class-attribute

type: str = OptimadeField('references', 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"`', regex='^references$', support=SupportLevel.MUST, queryable=SupportLevel.MUST) class-attribute

validate_attributes(v)

Source code in optimade/models/references.py 
268
269
270
271
272
@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

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 
 41
 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
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: Optional[str] = OptimadeField(None, description='Meaning of property matches the BiBTeX specification.', support=SupportLevel.OPTIONAL, queryable=SupportLevel.OPTIONAL) class-attribute

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

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

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) class-attribute

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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