Skip to content

config

This submodule defines constant values and definitions from the OPTIMADE specification for use by the validator.

The VALIDATOR_CONFIG object can be imported and modified before calling the validator inside a Python script to customise the hardcoded values.

ENTRY_INFO_SCHEMAS: dict[str, type[EntryResource]] = {'structures': StructureResource, 'references': ReferenceResource} module-attribute

This dictionary is used to define the /info/<entry_type> endpoints.

VALIDATOR_CONFIG = ValidatorConfig() module-attribute

_ENTRY_ENDPOINTS = ('structures', 'references', 'calculations') module-attribute

_ENTRY_SCHEMAS = {endp: retrieve_queryable_properties(ENTRY_INFO_SCHEMAS[endp], ('id', 'type', 'attributes'))for endp in ENTRY_INFO_SCHEMAS} module-attribute

_ENUM_DUMMY_VALUES = {'structures': {'structure_features': [allowed.value for allowed in StructureFeatures]}} module-attribute

_EXCLUSIVE_OPERATORS = {DataType.STRING: exclusive_ops, DataType.TIMESTAMP: (), DataType.FLOAT: (), DataType.INTEGER: exclusive_ops, DataType.LIST: ()} module-attribute

_FIELD_SPECIFIC_OVERRIDES = {'chemical_formula_anonymous': {SupportLevel.OPTIONAL: substring_operators}, 'chemical_formula_reduced': {SupportLevel.OPTIONAL: substring_operators}, 'immutable_id': {SupportLevel.OPTIONAL: [op for op in substring_operators + inclusive_ops + exclusive_ops if op != '=']}, 'structure_features': {SupportLevel.OPTIONAL: 'LENGTH'}} module-attribute

_INCLUSIVE_OPERATORS = {DataType.STRING: inclusive_ops + substring_operators, DataType.TIMESTAMP: ('>='), DataType.INTEGER: inclusive_ops, DataType.FLOAT: (), DataType.LIST: ('HAS', 'HAS ALL', 'HAS ANY', 'LENGTH')} module-attribute

_NON_ENTRY_ENDPOINTS = ('info', 'links', 'versions') module-attribute

_RESPONSE_CLASSES = {'references': ValidatorReferenceResponseMany, 'references/': ValidatorReferenceResponseOne, 'structures': ValidatorStructureResponseMany, 'structures/': ValidatorStructureResponseOne, 'info': InfoResponse, 'links': ValidatorLinksResponse} module-attribute

_RESPONSE_CLASSES_INDEX = {'info': IndexInfoResponse, 'links': ValidatorLinksResponse} module-attribute

_UNIQUE_PROPERTIES = ('id', 'immutable_id') module-attribute

__all__ = ('ValidatorConfig', 'VALIDATOR_CONFIG') module-attribute

exclusive_ops = ('!=', '<', '>') module-attribute

inclusive_ops = ('=', '<=', '>=') module-attribute

substring_operators = ('CONTAINS', 'STARTS WITH', 'STARTS', 'ENDS WITH', 'ENDS') module-attribute

BaseResourceMapper

Generic Resource Mapper that defines and performs the mapping between objects in the database and the resource objects defined by the specification.

Attributes:

Name Type Description
ALIASES tuple[tuple[str, str], ...]

a tuple of aliases between OPTIMADE field names and the field names in the database , e.g. (("elements", "custom_elements_field")).
LENGTH_ALIASES tuple[tuple[str, str], ...]

a tuple of aliases between a field name and another field that defines its length, to be used when querying, e.g. (("elements", "nelements")). e.g. (("elements", "custom_elements_field")).
ENTRY_RESOURCE_CLASS type[EntryResource]

The entry type that this mapper corresponds to.
PROVIDER_FIELDS tuple[str, ...]

a tuple of extra field names that this mapper should support when querying with the database prefix.
TOP_LEVEL_NON_ATTRIBUTES_FIELDS set[str]

the set of top-level field names common to all endpoints.
SUPPORTED_PREFIXES set[str]

The set of prefixes registered by this mapper.
ALL_ATTRIBUTES set[str]

The set of attributes defined across the entry resource class and the server configuration.
ENTRY_RESOURCE_ATTRIBUTES dict[str, Any]

A dictionary of attributes and their definitions defined by the schema of the entry resource class.
ENDPOINT str

The expected endpoint name for this resource, as defined by the type in the schema of the entry resource class.
Source code in optimade/server/mappers/entries.py 
 36
 37
 38
 39
 40
 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
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
283
284
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
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
class BaseResourceMapper:
    """Generic Resource Mapper that defines and performs the mapping
    between objects in the database and the resource objects defined by
    the specification.

    Attributes:
        ALIASES: a tuple of aliases between
            OPTIMADE field names and the field names in the database ,
            e.g. `(("elements", "custom_elements_field"))`.
        LENGTH_ALIASES: a tuple of aliases between
            a field name and another field that defines its length, to be used
            when querying, e.g. `(("elements", "nelements"))`.
            e.g. `(("elements", "custom_elements_field"))`.
        ENTRY_RESOURCE_CLASS: The entry type that this mapper corresponds to.
        PROVIDER_FIELDS: a tuple of extra field names that this
            mapper should support when querying with the database prefix.
        TOP_LEVEL_NON_ATTRIBUTES_FIELDS: the set of top-level
            field names common to all endpoints.
        SUPPORTED_PREFIXES: The set of prefixes registered by this mapper.
        ALL_ATTRIBUTES: The set of attributes defined across the entry
            resource class and the server configuration.
        ENTRY_RESOURCE_ATTRIBUTES: A dictionary of attributes and their definitions
            defined by the schema of the entry resource class.
        ENDPOINT: The expected endpoint name for this resource, as defined by
            the `type` in the schema of the entry resource class.

    """

    try:
        from optimade.server.data import providers as PROVIDERS  # type: ignore
    except (ImportError, ModuleNotFoundError):
        PROVIDERS = {}

    KNOWN_PROVIDER_PREFIXES: set[str] = {
        prov["id"] for prov in PROVIDERS.get("data", [])
    }
    ALIASES: tuple[tuple[str, str], ...] = ()
    LENGTH_ALIASES: tuple[tuple[str, str], ...] = ()
    PROVIDER_FIELDS: tuple[str, ...] = ()
    ENTRY_RESOURCE_CLASS: type[EntryResource] = EntryResource
    RELATIONSHIP_ENTRY_TYPES: set[str] = {"references", "structures"}
    TOP_LEVEL_NON_ATTRIBUTES_FIELDS: set[str] = {"id", "type", "relationships", "links"}

    @classmethod
    @lru_cache(maxsize=NUM_ENTRY_TYPES)
    def all_aliases(cls) -> Iterable[tuple[str, str]]:
        """Returns all of the associated aliases for this entry type,
        including those defined by the server config. The first member
        of each tuple is the OPTIMADE-compliant field name, the second
        is the backend-specific field name.

        Returns:
            A tuple of alias tuples.

        """
        from optimade.server.config import CONFIG

        return (
            tuple(
                (f"_{CONFIG.provider.prefix}_{field}", field)
                if not field.startswith("_")
                else (field, field)
                for field in CONFIG.provider_fields.get(cls.ENDPOINT, [])
                if isinstance(field, str)
            )
            + tuple(
                (f"_{CONFIG.provider.prefix}_{field['name']}", field["name"])
                if not field["name"].startswith("_")
                else (field["name"], field["name"])
                for field in CONFIG.provider_fields.get(cls.ENDPOINT, [])
                if isinstance(field, dict)
            )
            + tuple(
                (f"_{CONFIG.provider.prefix}_{field}", field)
                if not field.startswith("_")
                else (field, field)
                for field in cls.PROVIDER_FIELDS
            )
            + tuple(CONFIG.aliases.get(cls.ENDPOINT, {}).items())
            + cls.ALIASES
        )

    @classproperty
    @lru_cache(maxsize=1)
    def SUPPORTED_PREFIXES(cls) -> set[str]:
        """A set of prefixes handled by this entry type.

        !!! note
            This implementation only includes the provider prefix,
            but in the future this property may be extended to include other
            namespaces (for serving fields from, e.g., other providers or
            domain-specific terms).

        """
        from optimade.server.config import CONFIG

        return {CONFIG.provider.prefix}

    @classproperty
    def ALL_ATTRIBUTES(cls) -> set[str]:
        """Returns all attributes served by this entry."""
        from optimade.server.config import CONFIG

        return (
            set(cls.ENTRY_RESOURCE_ATTRIBUTES)
            .union(
                cls.get_optimade_field(field)
                for field in CONFIG.provider_fields.get(cls.ENDPOINT, ())
                if isinstance(field, str)
            )
            .union(
                cls.get_optimade_field(field["name"])
                for field in CONFIG.provider_fields.get(cls.ENDPOINT, ())
                if isinstance(field, dict)
            )
            .union({cls.get_optimade_field(field) for field in cls.PROVIDER_FIELDS})
        )

    @classproperty
    def ENTRY_RESOURCE_ATTRIBUTES(cls) -> dict[str, Any]:
        """Returns the dictionary of attributes defined by the underlying entry resource class."""
        from optimade.server.schemas import retrieve_queryable_properties

        return retrieve_queryable_properties(cls.ENTRY_RESOURCE_CLASS)

    @classproperty
    @lru_cache(maxsize=NUM_ENTRY_TYPES)
    def ENDPOINT(cls) -> str:
        """Returns the expected endpoint for this mapper, corresponding
        to the `type` property of the resource class.

        """
        endpoint = cls.ENTRY_RESOURCE_CLASS.model_fields["type"].default
        if not endpoint and not isinstance(endpoint, str):
            raise ValueError("Type not set for this entry type!")
        return endpoint

    @classmethod
    @lru_cache(maxsize=NUM_ENTRY_TYPES)
    def all_length_aliases(cls) -> tuple[tuple[str, str], ...]:
        """Returns all of the associated length aliases for this class,
        including those defined by the server config.

        Returns:
            A tuple of length alias tuples.

        """
        from optimade.server.config import CONFIG

        return cls.LENGTH_ALIASES + tuple(
            CONFIG.length_aliases.get(cls.ENDPOINT, {}).items()
        )

    @classmethod
    @lru_cache(maxsize=128)
    def length_alias_for(cls, field: str) -> Optional[str]:
        """Returns the length alias for the particular field,
        or `None` if no such alias is found.

        Parameters:
            field: OPTIMADE field name.

        Returns:
            Aliased field as found in [`all_length_aliases()`][optimade.server.mappers.entries.BaseResourceMapper.all_length_aliases].

        """
        return dict(cls.all_length_aliases()).get(field, None)

    @classmethod
    @lru_cache(maxsize=128)
    def get_backend_field(cls, optimade_field: str) -> str:
        """Return the field name configured for the particular
        underlying database for the passed OPTIMADE field name, that would
        be used in an API filter.

        Aliases are read from
        [`all_aliases()`][optimade.server.mappers.entries.BaseResourceMapper.all_aliases].

        If a dot-separated OPTIMADE field is provided, e.g., `species.mass`, only the first part will be mapped.
        This means for an (OPTIMADE, DB) alias of (`species`, `kinds`), `get_backend_fields("species.mass")`
        will return `kinds.mass`.

        Arguments:
            optimade_field: The OPTIMADE field to attempt to map to the backend-specific field.

        Examples:
            >>> get_backend_field("chemical_formula_anonymous")
            'formula_anon'
            >>> get_backend_field("formula_anon")
            'formula_anon'
            >>> get_backend_field("_exmpl_custom_provider_field")
            'custom_provider_field'

        Returns:
            The mapped field name to be used in the query to the backend.

        """
        split = optimade_field.split(".")
        alias = dict(cls.all_aliases()).get(split[0], None)
        if alias is not None:
            return alias + ("." + ".".join(split[1:]) if len(split) > 1 else "")
        return optimade_field

    @classmethod
    @lru_cache(maxsize=128)
    def alias_for(cls, field: str) -> str:
        """Return aliased field name.

        !!! warning "Deprecated"
            This method is deprecated could be removed without further warning. Please use
            [`get_backend_field()`][optimade.server.mappers.entries.BaseResourceMapper.get_backend_field].

        Parameters:
            field: OPTIMADE field name.

        Returns:
            Aliased field as found in [`all_aliases()`][optimade.server.mappers.entries.BaseResourceMapper.all_aliases].

        """
        warnings.warn(
            "The `.alias_for(...)` method is deprecated, please use `.get_backend_field(...)`.",
            DeprecationWarning,
        )
        return cls.get_backend_field(field)

    @classmethod
    @lru_cache(maxsize=128)
    def get_optimade_field(cls, backend_field: str) -> str:
        """Return the corresponding OPTIMADE field name for the underlying database field,
        ready to be used to construct the OPTIMADE-compliant JSON response.

        Aliases are read from
        [`all_aliases()`][optimade.server.mappers.entries.BaseResourceMapper.all_aliases].

        Arguments:
            backend_field: The backend field to attempt to map to an OPTIMADE field.

        Examples:
            >>> get_optimade_field("chemical_formula_anonymous")
            'chemical_formula_anonymous'
            >>> get_optimade_field("formula_anon")
            'chemical_formula_anonymous'
            >>> get_optimade_field("custom_provider_field")
            '_exmpl_custom_provider_field'

        Returns:
            The mapped field name to be used in an OPTIMADE-compliant response.

        """
        return {alias: real for real, alias in cls.all_aliases()}.get(
            backend_field, backend_field
        )

    @classmethod
    @lru_cache(maxsize=128)
    def alias_of(cls, field: str) -> str:
        """Return de-aliased field name, if it exists,
        otherwise return the input field name.

        !!! warning "Deprecated"
            This method is deprecated could be removed without further warning. Please use
            [`get_optimade_field()`][optimade.server.mappers.entries.BaseResourceMapper.get_optimade_field].

        Parameters:
            field: Field name to be de-aliased.

        Returns:
            De-aliased field name, falling back to returning `field`.

        """
        warnings.warn(
            "The `.alias_of(...)` method is deprecated, please use `.get_optimade_field(...)`.",
            DeprecationWarning,
        )
        return cls.get_optimade_field(field)

    @classmethod
    @lru_cache(maxsize=NUM_ENTRY_TYPES)
    def get_required_fields(cls) -> set:
        """Get REQUIRED response fields.

        Returns:
            REQUIRED response fields.

        """
        return cls.TOP_LEVEL_NON_ATTRIBUTES_FIELDS

    @classmethod
    def map_back(cls, doc: dict) -> dict:
        """Map properties from MongoDB to OPTIMADE.

        Starting from a MongoDB document `doc`, map the DB fields to the corresponding OPTIMADE fields.
        Then, the fields are all added to the top-level field "attributes",
        with the exception of other top-level fields, defined in `cls.TOP_LEVEL_NON_ATTRIBUTES_FIELDS`.
        All fields not in `cls.TOP_LEVEL_NON_ATTRIBUTES_FIELDS` + "attributes" will be removed.
        Finally, the `type` is given the value of the specified `cls.ENDPOINT`.

        Parameters:
            doc: A resource object in MongoDB format.

        Returns:
            A resource object in OPTIMADE format.

        """
        mapping = ((real, alias) for alias, real in cls.all_aliases())
        newdoc = {}
        reals = {real for _, real in cls.all_aliases()}
        for key in doc:
            if key not in reals:
                newdoc[key] = doc[key]
        for real, alias in mapping:
            if real in doc:
                newdoc[alias] = doc[real]

        if "attributes" in newdoc:
            raise Exception("Will overwrite doc field!")
        attributes = newdoc.copy()

        for field in cls.TOP_LEVEL_NON_ATTRIBUTES_FIELDS:
            value = attributes.pop(field, None)
            if value is not None:
                newdoc[field] = value
        for field in list(newdoc.keys()):
            if field not in cls.TOP_LEVEL_NON_ATTRIBUTES_FIELDS:
                del newdoc[field]

        newdoc["type"] = cls.ENDPOINT
        newdoc["attributes"] = attributes

        return newdoc

    @classmethod
    def deserialize(
        cls, results: Union[dict, Iterable[dict]]
    ) -> Union[list[EntryResource], EntryResource]:
        """Converts the raw database entries for this class into serialized models,
        mapping the data along the way.

        """
        if isinstance(results, dict):
            return cls.ENTRY_RESOURCE_CLASS(**cls.map_back(results))

        return [cls.ENTRY_RESOURCE_CLASS(**cls.map_back(doc)) for doc in results]

ALL_ATTRIBUTES()

Returns all attributes served by this entry.

Source code in optimade/server/mappers/entries.py 
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
@classproperty
def ALL_ATTRIBUTES(cls) -> set[str]:
    """Returns all attributes served by this entry."""
    from optimade.server.config import CONFIG

    return (
        set(cls.ENTRY_RESOURCE_ATTRIBUTES)
        .union(
            cls.get_optimade_field(field)
            for field in CONFIG.provider_fields.get(cls.ENDPOINT, ())
            if isinstance(field, str)
        )
        .union(
            cls.get_optimade_field(field["name"])
            for field in CONFIG.provider_fields.get(cls.ENDPOINT, ())
            if isinstance(field, dict)
        )
        .union({cls.get_optimade_field(field) for field in cls.PROVIDER_FIELDS})
    )

ENDPOINT() cached

Returns the expected endpoint for this mapper, corresponding to the type property of the resource class.

Source code in optimade/server/mappers/entries.py 
161
162
163
164
165
166
167
168
169
170
171
@classproperty
@lru_cache(maxsize=NUM_ENTRY_TYPES)
def ENDPOINT(cls) -> str:
    """Returns the expected endpoint for this mapper, corresponding
    to the `type` property of the resource class.

    """
    endpoint = cls.ENTRY_RESOURCE_CLASS.model_fields["type"].default
    if not endpoint and not isinstance(endpoint, str):
        raise ValueError("Type not set for this entry type!")
    return endpoint

ENTRY_RESOURCE_ATTRIBUTES()

Returns the dictionary of attributes defined by the underlying entry resource class.

Source code in optimade/server/mappers/entries.py 
154
155
156
157
158
159
@classproperty
def ENTRY_RESOURCE_ATTRIBUTES(cls) -> dict[str, Any]:
    """Returns the dictionary of attributes defined by the underlying entry resource class."""
    from optimade.server.schemas import retrieve_queryable_properties

    return retrieve_queryable_properties(cls.ENTRY_RESOURCE_CLASS)

SUPPORTED_PREFIXES() cached

A set of prefixes handled by this entry type.

Note

This implementation only includes the provider prefix, but in the future this property may be extended to include other namespaces (for serving fields from, e.g., other providers or domain-specific terms).

Source code in optimade/server/mappers/entries.py 
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
@classproperty
@lru_cache(maxsize=1)
def SUPPORTED_PREFIXES(cls) -> set[str]:
    """A set of prefixes handled by this entry type.

    !!! note
        This implementation only includes the provider prefix,
        but in the future this property may be extended to include other
        namespaces (for serving fields from, e.g., other providers or
        domain-specific terms).

    """
    from optimade.server.config import CONFIG

    return {CONFIG.provider.prefix}

alias_for(field) cached classmethod

Return aliased field name.

Deprecated

This method is deprecated could be removed without further warning. Please use get_backend_field().

Parameters:

Name Type Description Default
field str

OPTIMADE field name.

 required

Returns:

Type Description
str

Aliased field as found in all_aliases().
Source code in optimade/server/mappers/entries.py 
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
@classmethod
@lru_cache(maxsize=128)
def alias_for(cls, field: str) -> str:
    """Return aliased field name.

    !!! warning "Deprecated"
        This method is deprecated could be removed without further warning. Please use
        [`get_backend_field()`][optimade.server.mappers.entries.BaseResourceMapper.get_backend_field].

    Parameters:
        field: OPTIMADE field name.

    Returns:
        Aliased field as found in [`all_aliases()`][optimade.server.mappers.entries.BaseResourceMapper.all_aliases].

    """
    warnings.warn(
        "The `.alias_for(...)` method is deprecated, please use `.get_backend_field(...)`.",
        DeprecationWarning,
    )
    return cls.get_backend_field(field)

alias_of(field) cached classmethod

Return de-aliased field name, if it exists, otherwise return the input field name.

Deprecated

This method is deprecated could be removed without further warning. Please use get_optimade_field().

Parameters:

Name Type Description Default
field str

Field name to be de-aliased.

 required

Returns:

Type Description
str

De-aliased field name, falling back to returning field.
Source code in optimade/server/mappers/entries.py 
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
@classmethod
@lru_cache(maxsize=128)
def alias_of(cls, field: str) -> str:
    """Return de-aliased field name, if it exists,
    otherwise return the input field name.

    !!! warning "Deprecated"
        This method is deprecated could be removed without further warning. Please use
        [`get_optimade_field()`][optimade.server.mappers.entries.BaseResourceMapper.get_optimade_field].

    Parameters:
        field: Field name to be de-aliased.

    Returns:
        De-aliased field name, falling back to returning `field`.

    """
    warnings.warn(
        "The `.alias_of(...)` method is deprecated, please use `.get_optimade_field(...)`.",
        DeprecationWarning,
    )
    return cls.get_optimade_field(field)

all_aliases() cached classmethod

Returns all of the associated aliases for this entry type, including those defined by the server config. The first member of each tuple is the OPTIMADE-compliant field name, the second is the backend-specific field name.

Returns:

Type Description
Iterable[tuple[str, str]]

A tuple of alias tuples.
Source code in optimade/server/mappers/entries.py 
 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
@classmethod
@lru_cache(maxsize=NUM_ENTRY_TYPES)
def all_aliases(cls) -> Iterable[tuple[str, str]]:
    """Returns all of the associated aliases for this entry type,
    including those defined by the server config. The first member
    of each tuple is the OPTIMADE-compliant field name, the second
    is the backend-specific field name.

    Returns:
        A tuple of alias tuples.

    """
    from optimade.server.config import CONFIG

    return (
        tuple(
            (f"_{CONFIG.provider.prefix}_{field}", field)
            if not field.startswith("_")
            else (field, field)
            for field in CONFIG.provider_fields.get(cls.ENDPOINT, [])
            if isinstance(field, str)
        )
        + tuple(
            (f"_{CONFIG.provider.prefix}_{field['name']}", field["name"])
            if not field["name"].startswith("_")
            else (field["name"], field["name"])
            for field in CONFIG.provider_fields.get(cls.ENDPOINT, [])
            if isinstance(field, dict)
        )
        + tuple(
            (f"_{CONFIG.provider.prefix}_{field}", field)
            if not field.startswith("_")
            else (field, field)
            for field in cls.PROVIDER_FIELDS
        )
        + tuple(CONFIG.aliases.get(cls.ENDPOINT, {}).items())
        + cls.ALIASES
    )

all_length_aliases() cached classmethod

Returns all of the associated length aliases for this class, including those defined by the server config.

Returns:

Type Description
tuple[tuple[str, str], ...]

A tuple of length alias tuples.
Source code in optimade/server/mappers/entries.py 
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
@classmethod
@lru_cache(maxsize=NUM_ENTRY_TYPES)
def all_length_aliases(cls) -> tuple[tuple[str, str], ...]:
    """Returns all of the associated length aliases for this class,
    including those defined by the server config.

    Returns:
        A tuple of length alias tuples.

    """
    from optimade.server.config import CONFIG

    return cls.LENGTH_ALIASES + tuple(
        CONFIG.length_aliases.get(cls.ENDPOINT, {}).items()
    )

deserialize(results) classmethod

Converts the raw database entries for this class into serialized models, mapping the data along the way.

Source code in optimade/server/mappers/entries.py 
367
368
369
370
371
372
373
374
375
376
377
378
@classmethod
def deserialize(
    cls, results: Union[dict, Iterable[dict]]
) -> Union[list[EntryResource], EntryResource]:
    """Converts the raw database entries for this class into serialized models,
    mapping the data along the way.

    """
    if isinstance(results, dict):
        return cls.ENTRY_RESOURCE_CLASS(**cls.map_back(results))

    return [cls.ENTRY_RESOURCE_CLASS(**cls.map_back(doc)) for doc in results]

get_backend_field(optimade_field) cached classmethod

Return the field name configured for the particular underlying database for the passed OPTIMADE field name, that would be used in an API filter.

Aliases are read from all_aliases().

If a dot-separated OPTIMADE field is provided, e.g., species.mass, only the first part will be mapped. This means for an (OPTIMADE, DB) alias of (species, kinds), get_backend_fields("species.mass") will return kinds.mass.

Parameters:

Name Type Description Default
optimade_field str

The OPTIMADE field to attempt to map to the backend-specific field.

 required

Examples:

>>> get_backend_field("chemical_formula_anonymous")
'formula_anon'
>>> get_backend_field("formula_anon")
'formula_anon'
>>> get_backend_field("_exmpl_custom_provider_field")
'custom_provider_field'

Returns:

Type Description
str

The mapped field name to be used in the query to the backend.
Source code in optimade/server/mappers/entries.py 
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
@classmethod
@lru_cache(maxsize=128)
def get_backend_field(cls, optimade_field: str) -> str:
    """Return the field name configured for the particular
    underlying database for the passed OPTIMADE field name, that would
    be used in an API filter.

    Aliases are read from
    [`all_aliases()`][optimade.server.mappers.entries.BaseResourceMapper.all_aliases].

    If a dot-separated OPTIMADE field is provided, e.g., `species.mass`, only the first part will be mapped.
    This means for an (OPTIMADE, DB) alias of (`species`, `kinds`), `get_backend_fields("species.mass")`
    will return `kinds.mass`.

    Arguments:
        optimade_field: The OPTIMADE field to attempt to map to the backend-specific field.

    Examples:
        >>> get_backend_field("chemical_formula_anonymous")
        'formula_anon'
        >>> get_backend_field("formula_anon")
        'formula_anon'
        >>> get_backend_field("_exmpl_custom_provider_field")
        'custom_provider_field'

    Returns:
        The mapped field name to be used in the query to the backend.

    """
    split = optimade_field.split(".")
    alias = dict(cls.all_aliases()).get(split[0], None)
    if alias is not None:
        return alias + ("." + ".".join(split[1:]) if len(split) > 1 else "")
    return optimade_field

get_optimade_field(backend_field) cached classmethod

Return the corresponding OPTIMADE field name for the underlying database field, ready to be used to construct the OPTIMADE-compliant JSON response.

Aliases are read from all_aliases().

Parameters:

Name Type Description Default
backend_field str

The backend field to attempt to map to an OPTIMADE field.

 required

Examples:

>>> get_optimade_field("chemical_formula_anonymous")
'chemical_formula_anonymous'
>>> get_optimade_field("formula_anon")
'chemical_formula_anonymous'
>>> get_optimade_field("custom_provider_field")
'_exmpl_custom_provider_field'

Returns:

Type Description
str

The mapped field name to be used in an OPTIMADE-compliant response.
Source code in optimade/server/mappers/entries.py 
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
@classmethod
@lru_cache(maxsize=128)
def get_optimade_field(cls, backend_field: str) -> str:
    """Return the corresponding OPTIMADE field name for the underlying database field,
    ready to be used to construct the OPTIMADE-compliant JSON response.

    Aliases are read from
    [`all_aliases()`][optimade.server.mappers.entries.BaseResourceMapper.all_aliases].

    Arguments:
        backend_field: The backend field to attempt to map to an OPTIMADE field.

    Examples:
        >>> get_optimade_field("chemical_formula_anonymous")
        'chemical_formula_anonymous'
        >>> get_optimade_field("formula_anon")
        'chemical_formula_anonymous'
        >>> get_optimade_field("custom_provider_field")
        '_exmpl_custom_provider_field'

    Returns:
        The mapped field name to be used in an OPTIMADE-compliant response.

    """
    return {alias: real for real, alias in cls.all_aliases()}.get(
        backend_field, backend_field
    )

get_required_fields() cached classmethod

Get REQUIRED response fields.

Returns:

Type Description
set

REQUIRED response fields.
Source code in optimade/server/mappers/entries.py 
312
313
314
315
316
317
318
319
320
321
@classmethod
@lru_cache(maxsize=NUM_ENTRY_TYPES)
def get_required_fields(cls) -> set:
    """Get REQUIRED response fields.

    Returns:
        REQUIRED response fields.

    """
    return cls.TOP_LEVEL_NON_ATTRIBUTES_FIELDS

length_alias_for(field) cached classmethod

Returns the length alias for the particular field, or None if no such alias is found.

Parameters:

Name Type Description Default
field str

OPTIMADE field name.

 required

Returns:

Type Description
Optional[str]

Aliased field as found in all_length_aliases().
Source code in optimade/server/mappers/entries.py 
189
190
191
192
193
194
195
196
197
198
199
200
201
202
@classmethod
@lru_cache(maxsize=128)
def length_alias_for(cls, field: str) -> Optional[str]:
    """Returns the length alias for the particular field,
    or `None` if no such alias is found.

    Parameters:
        field: OPTIMADE field name.

    Returns:
        Aliased field as found in [`all_length_aliases()`][optimade.server.mappers.entries.BaseResourceMapper.all_length_aliases].

    """
    return dict(cls.all_length_aliases()).get(field, None)

map_back(doc) classmethod

Map properties from MongoDB to OPTIMADE.

Starting from a MongoDB document doc, map the DB fields to the corresponding OPTIMADE fields. Then, the fields are all added to the top-level field "attributes", with the exception of other top-level fields, defined in cls.TOP_LEVEL_NON_ATTRIBUTES_FIELDS. All fields not in cls.TOP_LEVEL_NON_ATTRIBUTES_FIELDS + "attributes" will be removed. Finally, the type is given the value of the specified cls.ENDPOINT.

Parameters:

Name Type Description Default
doc dict

A resource object in MongoDB format.

 required

Returns:

Type Description
dict

A resource object in OPTIMADE format.
Source code in optimade/server/mappers/entries.py 
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
@classmethod
def map_back(cls, doc: dict) -> dict:
    """Map properties from MongoDB to OPTIMADE.

    Starting from a MongoDB document `doc`, map the DB fields to the corresponding OPTIMADE fields.
    Then, the fields are all added to the top-level field "attributes",
    with the exception of other top-level fields, defined in `cls.TOP_LEVEL_NON_ATTRIBUTES_FIELDS`.
    All fields not in `cls.TOP_LEVEL_NON_ATTRIBUTES_FIELDS` + "attributes" will be removed.
    Finally, the `type` is given the value of the specified `cls.ENDPOINT`.

    Parameters:
        doc: A resource object in MongoDB format.

    Returns:
        A resource object in OPTIMADE format.

    """
    mapping = ((real, alias) for alias, real in cls.all_aliases())
    newdoc = {}
    reals = {real for _, real in cls.all_aliases()}
    for key in doc:
        if key not in reals:
            newdoc[key] = doc[key]
    for real, alias in mapping:
        if real in doc:
            newdoc[alias] = doc[real]

    if "attributes" in newdoc:
        raise Exception("Will overwrite doc field!")
    attributes = newdoc.copy()

    for field in cls.TOP_LEVEL_NON_ATTRIBUTES_FIELDS:
        value = attributes.pop(field, None)
        if value is not None:
            newdoc[field] = value
    for field in list(newdoc.keys()):
        if field not in cls.TOP_LEVEL_NON_ATTRIBUTES_FIELDS:
            del newdoc[field]

    newdoc["type"] = cls.ENDPOINT
    newdoc["attributes"] = attributes

    return newdoc

DataType

Bases: Enum

Optimade Data types

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

Source code in optimade/models/optimade_json.py 
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 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
class DataType(Enum):
    """Optimade Data types

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

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

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

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

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

        return mapping.get(python_type, None)

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

        return mapping.get(json_type, None)

from_json_type(json_type) classmethod

Get OPTIMADE data type from a named JSON type

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

    return mapping.get(json_type, None)

from_python_type(python_type) classmethod

Get OPTIMADE data type from a Python type

Source code in optimade/models/optimade_json.py 
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
@classmethod
def from_python_type(
    cls, python_type: Union[type, str, object]
) -> Optional["DataType"]:
    """Get OPTIMADE data type from a Python type"""
    mapping = {
        "bool": cls.BOOLEAN,
        "int": cls.INTEGER,
        "float": cls.FLOAT,
        "complex": None,
        "generator": cls.LIST,
        "list": cls.LIST,
        "tuple": cls.LIST,
        "range": cls.LIST,
        "hash": cls.INTEGER,
        "str": cls.STRING,
        "bytes": cls.STRING,
        "bytearray": None,
        "memoryview": None,
        "set": cls.LIST,
        "frozenset": cls.LIST,
        "dict": cls.DICTIONARY,
        "dict_keys": cls.LIST,
        "dict_values": cls.LIST,
        "dict_items": cls.LIST,
        "Nonetype": cls.UNKNOWN,
        "None": cls.UNKNOWN,
        "datetime": cls.TIMESTAMP,
        "date": cls.TIMESTAMP,
        "time": cls.TIMESTAMP,
        "datetime.datetime": cls.TIMESTAMP,
        "datetime.date": cls.TIMESTAMP,
        "datetime.time": cls.TIMESTAMP,
    }

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

    return mapping.get(python_type, None)

get_values() classmethod

Get OPTIMADE data types (enum values) as a (sorted) list

Source code in optimade/models/optimade_json.py 
43
44
45
46
@classmethod
def get_values(cls) -> list[str]:
    """Get OPTIMADE data types (enum values) as a (sorted) list"""
    return sorted(_.value for _ in cls)

IndexInfoResponse

Bases: Success

Source code in optimade/models/responses.py 
53
54
55
56
class IndexInfoResponse(Success):
    data: Annotated[
        IndexInfoResource, StrictField(description="Index meta-database /info data.")
    ]

model_config = ConfigDict(json_encoders={datetime: lambda : v.astimezone(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ')}) class-attribute instance-attribute

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

either_data_meta_or_errors_must_be_set()

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

Source code in optimade/models/optimade_json.py 
387
388
389
390
391
392
393
394
395
396
397
398
399
400
@model_validator(mode="after")
def either_data_meta_or_errors_must_be_set(self) -> "Success":
    """Overwriting the existing validation function, since 'errors' MUST NOT be set."""
    required_fields = ("data", "meta")
    if not any(field in self.model_fields_set for field in required_fields):
        raise ValueError(
            f"At least one of {required_fields} MUST be specified in the top-level response."
        )

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

    return self

InfoResponse

Bases: Success

Source code in optimade/models/responses.py 
66
67
68
69
class InfoResponse(Success):
    data: Annotated[
        BaseInfoResource, StrictField(description="The implementations /info data.")
    ]

model_config = ConfigDict(json_encoders={datetime: lambda : v.astimezone(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ')}) class-attribute instance-attribute

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

either_data_meta_or_errors_must_be_set()

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

Source code in optimade/models/optimade_json.py 
387
388
389
390
391
392
393
394
395
396
397
398
399
400
@model_validator(mode="after")
def either_data_meta_or_errors_must_be_set(self) -> "Success":
    """Overwriting the existing validation function, since 'errors' MUST NOT be set."""
    required_fields = ("data", "meta")
    if not any(field in self.model_fields_set for field in required_fields):
        raise ValueError(
            f"At least one of {required_fields} MUST be specified in the top-level response."
        )

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

    return self

StructureFeatures

Bases: Enum

Enumeration of structure_features values

Source code in optimade/models/structures.py 
55
56
57
58
59
60
61
class StructureFeatures(Enum):
    """Enumeration of structure_features values"""

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

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"

ValidatorConfig

Bases: BaseSettings

This class stores validator config parameters in a way that can be easily modified for testing niche implementations. Many of these fields are determined by the specification directly, but it may be desirable to modify them in certain cases.

Source code in optimade/validator/config.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
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
class ValidatorConfig(BaseSettings):
    """This class stores validator config parameters in a way that
    can be easily modified for testing niche implementations. Many
    of these fields are determined by the specification directly,
    but it may be desirable to modify them in certain cases.

    """

    response_classes: dict[str, Any] = Field(
        _RESPONSE_CLASSES,
        description="Dictionary containing the mapping between endpoints and response classes for the main database",
    )

    response_classes_index: dict[str, Any] = Field(
        _RESPONSE_CLASSES_INDEX,
        description="Dictionary containing the mapping between endpoints and response classes for the index meta-database",
    )

    entry_schemas: dict[str, Any] = Field(
        _ENTRY_SCHEMAS, description="The entry listing endpoint schemas"
    )

    entry_endpoints: set[str] = Field(
        _ENTRY_ENDPOINTS,
        description="The entry endpoints to validate, if present in the API's `/info` response `entry_types_by_format['json']`",
    )

    unique_properties: set[str] = Field(
        _UNIQUE_PROPERTIES,
        description=(
            "Fields that should be treated as unique indexes for all endpoints, "
            "i.e. fields on which filters should return at most one entry."
        ),
    )

    inclusive_operators: dict[DataType, set[str]] = Field(
        _INCLUSIVE_OPERATORS,
        description=(
            "Dictionary mapping OPTIMADE `DataType`s to a list of operators that are 'inclusive', "
            "i.e. those that should return entries with the matching value from the filter."
        ),
    )

    exclusive_operators: dict[DataType, set[str]] = Field(
        _EXCLUSIVE_OPERATORS,
        description=(
            "Dictionary mapping OPTIMADE `DataType`s to a list of operators that are 'exclusive', "
            "i.e. those that should not return entries with the matching value from the filter."
        ),
    )

    field_specific_overrides: dict[str, dict[SupportLevel, Container[str]]] = Field(
        _FIELD_SPECIFIC_OVERRIDES,
        description=(
            "Some fields do not require all type comparison operators to be supported. "
            "This dictionary allows overriding the list of supported operators for a field, using "
            "the field name as a key, and the support level of different operators with a subkey. "
            "Queries on fields listed in this way will pass the validator provided the server returns a 501 status."
        ),
    )

    links_endpoint: str = Field("links", description="The name of the links endpoint")
    versions_endpoint: str = Field(
        "versions", description="The name of the versions endpoint"
    )

    info_endpoint: str = Field("info", description="The name of the info endpoint")
    non_entry_endpoints: set[str] = Field(
        _NON_ENTRY_ENDPOINTS,
        description="The list specification-mandated endpoint names that do not contain entries",
    )
    top_level_non_attribute_fields: set[str] = Field(
        BaseResourceMapper.TOP_LEVEL_NON_ATTRIBUTES_FIELDS,
        description="Field names to treat as top-level",
    )

    enum_fallback_values: dict[str, dict[str, list[str]]] = Field(
        _ENUM_DUMMY_VALUES,
        description="Provide fallback values for enum fields to use when validating filters.",
    )

ValidatorLinksResponse

Bases: Success

Source code in optimade/validator/utils.py 
404
405
406
class ValidatorLinksResponse(Success):
    meta: ResponseMeta = Field(...)
    data: list[LinksResource] = Field(...)

model_config = ConfigDict(json_encoders={datetime: lambda : v.astimezone(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ')}) class-attribute instance-attribute

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

either_data_meta_or_errors_must_be_set()

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

Source code in optimade/models/optimade_json.py 
387
388
389
390
391
392
393
394
395
396
397
398
399
400
@model_validator(mode="after")
def either_data_meta_or_errors_must_be_set(self) -> "Success":
    """Overwriting the existing validation function, since 'errors' MUST NOT be set."""
    required_fields = ("data", "meta")
    if not any(field in self.model_fields_set for field in required_fields):
        raise ValueError(
            f"At least one of {required_fields} MUST be specified in the top-level response."
        )

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

    return self

ValidatorReferenceResponseMany

Bases: ValidatorEntryResponseMany

Source code in optimade/validator/utils.py 
425
426
class ValidatorReferenceResponseMany(ValidatorEntryResponseMany):
    data: list[ReferenceResource] = Field(...)

model_config = ConfigDict(json_encoders={datetime: lambda : v.astimezone(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ')}) class-attribute instance-attribute

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

either_data_meta_or_errors_must_be_set()

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

Source code in optimade/models/optimade_json.py 
387
388
389
390
391
392
393
394
395
396
397
398
399
400
@model_validator(mode="after")
def either_data_meta_or_errors_must_be_set(self) -> "Success":
    """Overwriting the existing validation function, since 'errors' MUST NOT be set."""
    required_fields = ("data", "meta")
    if not any(field in self.model_fields_set for field in required_fields):
        raise ValueError(
            f"At least one of {required_fields} MUST be specified in the top-level response."
        )

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

    return self

ValidatorReferenceResponseOne

Bases: ValidatorEntryResponseOne

Source code in optimade/validator/utils.py 
421
422
class ValidatorReferenceResponseOne(ValidatorEntryResponseOne):
    data: ReferenceResource = Field(...)

model_config = ConfigDict(json_encoders={datetime: lambda : v.astimezone(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ')}) class-attribute instance-attribute

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

either_data_meta_or_errors_must_be_set()

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

Source code in optimade/models/optimade_json.py 
387
388
389
390
391
392
393
394
395
396
397
398
399
400
@model_validator(mode="after")
def either_data_meta_or_errors_must_be_set(self) -> "Success":
    """Overwriting the existing validation function, since 'errors' MUST NOT be set."""
    required_fields = ("data", "meta")
    if not any(field in self.model_fields_set for field in required_fields):
        raise ValueError(
            f"At least one of {required_fields} MUST be specified in the top-level response."
        )

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

    return self

ValidatorStructureResponseMany

Bases: ValidatorEntryResponseMany

Source code in optimade/validator/utils.py 
433
434
class ValidatorStructureResponseMany(ValidatorEntryResponseMany):
    data: list[StructureResource] = Field(...)

model_config = ConfigDict(json_encoders={datetime: lambda : v.astimezone(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ')}) class-attribute instance-attribute

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

either_data_meta_or_errors_must_be_set()

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

Source code in optimade/models/optimade_json.py 
387
388
389
390
391
392
393
394
395
396
397
398
399
400
@model_validator(mode="after")
def either_data_meta_or_errors_must_be_set(self) -> "Success":
    """Overwriting the existing validation function, since 'errors' MUST NOT be set."""
    required_fields = ("data", "meta")
    if not any(field in self.model_fields_set for field in required_fields):
        raise ValueError(
            f"At least one of {required_fields} MUST be specified in the top-level response."
        )

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

    return self

ValidatorStructureResponseOne

Bases: ValidatorEntryResponseOne

Source code in optimade/validator/utils.py 
429
430
class ValidatorStructureResponseOne(ValidatorEntryResponseOne):
    data: StructureResource = Field(...)

model_config = ConfigDict(json_encoders={datetime: lambda : v.astimezone(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ')}) class-attribute instance-attribute

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

either_data_meta_or_errors_must_be_set()

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

Source code in optimade/models/optimade_json.py 
387
388
389
390
391
392
393
394
395
396
397
398
399
400
@model_validator(mode="after")
def either_data_meta_or_errors_must_be_set(self) -> "Success":
    """Overwriting the existing validation function, since 'errors' MUST NOT be set."""
    required_fields = ("data", "meta")
    if not any(field in self.model_fields_set for field in required_fields):
        raise ValueError(
            f"At least one of {required_fields} MUST be specified in the top-level response."
        )

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

    return self

retrieve_queryable_properties(schema, queryable_properties=None, entry_type=None)

Recursively loops through a pydantic model, returning a dictionary of all the OPTIMADE-queryable properties of that model.

Parameters:

Name Type Description Default
schema type[EntryResource]

The pydantic model.

 required
queryable_properties Optional[Iterable[str]]

The list of properties to find in the schema.

 None
entry_type Optional[str]

An optional entry type for the model. Will be used to lookup schemas for any config-defined fields.

 None

Returns:

Type Description
QueryableProperties

A flat dictionary with properties as keys, containing the field
QueryableProperties

description, unit, sortability, support level, queryability
QueryableProperties

and type, where provided.
Source code in optimade/server/schemas.py 
 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
def retrieve_queryable_properties(
    schema: type[EntryResource],
    queryable_properties: Optional[Iterable[str]] = None,
    entry_type: Optional[str] = None,
) -> "QueryableProperties":
    """Recursively loops through a pydantic model, returning a dictionary of all the
    OPTIMADE-queryable properties of that model.

    Parameters:
        schema: The pydantic model.
        queryable_properties: The list of properties to find in the schema.
        entry_type: An optional entry type for the model. Will be used to
            lookup schemas for any config-defined fields.

    Returns:
        A flat dictionary with properties as keys, containing the field
        description, unit, sortability, support level, queryability
        and type, where provided.

    """
    properties: "QueryableProperties" = {}
    for name, value in schema.model_fields.items():
        # Proceed if the field (name) is given explicitly in the queryable_properties
        # list or if the queryable_properties list is empty (i.e., all properties are
        # requested)
        if not queryable_properties or name in queryable_properties:
            if name in properties:
                continue

            # If the field is another data model, "unpack" it by recursively calling
            # this function.
            # But first, we need to "unpack" the annotation, getting in behind any
            # Optional, Union, or Annotated types.
            annotation = _get_origin_type(value.annotation)

            if annotation not in (None, NoneType) and issubclass(annotation, BaseModel):
                sub_queryable_properties = list(annotation.model_fields)  # type: ignore[attr-defined]
                properties.update(
                    retrieve_queryable_properties(annotation, sub_queryable_properties)
                )

            properties[name] = {"description": value.description or ""}

            # Update schema with extension keys, provided they are not None
            for key in (
                "x-optimade-unit",
                "x-optimade-queryable",
                "x-optimade-support",
            ):
                if (
                    value.json_schema_extra
                    and value.json_schema_extra.get(key) is not None
                ):
                    properties[name][
                        key.replace("x-optimade-", "")  # type: ignore[index]
                    ] = value.json_schema_extra[key]

            # All properties are sortable with the MongoDB backend.
            # While the result for sorting lists may not be as expected, they are still sorted.
            properties[name]["sortable"] = (
                value.json_schema_extra.get("x-optimade-sortable", True)
                if value.json_schema_extra
                else True
            )

            # Try to get OpenAPI-specific "format" if possible, else get "type"; a mandatory OpenAPI key.
            json_schema = TypeAdapter(annotation).json_schema(mode="validation")

            properties[name]["type"] = DataType.from_json_type(
                json_schema.get("format", json_schema.get("type"))
            )

    # If specified, check the config for any additional well-described provider fields
    if entry_type:
        from optimade.server.config import CONFIG

        described_provider_fields = [
            field
            for field in CONFIG.provider_fields.get(entry_type, {})  # type: ignore[call-overload]
            if isinstance(field, dict)
        ]
        for field in described_provider_fields:
            name = (
                f"_{CONFIG.provider.prefix}_{field['name']}"
                if not field["name"].startswith("_")
                else field["name"]
            )
            properties[name] = {k: field[k] for k in field if k != "name"}
            properties[name]["sortable"] = field.get("sortable", True)

    # Remove JSON fields mistaken as properties
    non_property_fields = ["attributes", "relationships"]
    for non_property_field in non_property_fields:
        if non_property_field in properties:
            del properties[non_property_field]

    return properties