Models

`baseinfo` ¶

`AvailableApiVersion (BaseModel)` `pydantic-model` ¶

A JSON object containing information about an available API version

`url: AnyHttpUrl` `pydantic-field` `required` ¶

a string specifying a versioned base URL that MUST adhere to the rules in section Base URL

`version: ConstrainedStrValue` `pydantic-field` `required` ¶

a string containing the full version number of the API served at that versioned base URL. The version number string MUST NOT be prefixed by, e.g., 'v'.

`crosscheck_url_and_version(values)` `classmethod` ¶

Check that URL version and API version are compatible.

Source code in optimade/models/baseinfo.py

@root_validator(pre=False, skip_on_failure=True)
def crosscheck_url_and_version(cls, values):
    """ Check that URL version and API version are compatible. """
    url_version = (
        values["url"]
        .split("/")[-2 if values["url"].endswith("/") else -1]
        .replace("v", "")
    )
    url_version = tuple(int(val) for val in url_version.split("."))
    api_version = tuple(int(val) for val in values["version"].split("."))
    if any(a != b for a, b in zip(url_version, api_version)):
        raise ValueError(
            f"API version {api_version} is not compatible with url version {url_version}."
        )
    return values

`url_must_be_versioned_base_url(v)` `classmethod` ¶

The URL must be a valid versioned Base URL

Source code in optimade/models/baseinfo.py

@validator("url")
def url_must_be_versioned_base_url(cls, v):
    """The URL must be a valid versioned Base URL"""
    if not re.match(r".+/v[0-1](\.[0-9]+)*/?$", v):
        raise ValueError(f"url MUST be a versioned base URL. It is: {v}")
    return v

`BaseInfoAttributes (BaseModel)` `pydantic-model` ¶

Attributes for Base URL Info endpoint

`api_version: str` `pydantic-field` `required` ¶

Presently used version of the OPTIMADE API

`available_api_versions: List[optimade.models.baseinfo.AvailableApiVersion]` `pydantic-field` `required` ¶

A list of dictionaries of available API versions at other base URLs

`available_endpoints: List[str]` `pydantic-field` `required` ¶

List of available endpoints (i.e., the string to be appended to the versioned base URL).

`entry_types_by_format: Dict[str, List[str]]` `pydantic-field` `required` ¶

Available entry endpoints as a function of output formats.

`formats: List[str]` `pydantic-field` ¶

List of available output formats.

`is_index: bool` `pydantic-field` ¶

If true, this is an index meta-database base URL (see section Index Meta-Database). If this member is not provided, the client MUST assume this is not an index meta-database base URL (i.e., the default is for is_index to be false).

`entries` ¶

`EntryInfoProperty (BaseModel)` `pydantic-model` ¶

`description: str` `pydantic-field` `required` ¶

description of the entry property

`sortable: bool` `pydantic-field` ¶

defines whether the entry property can be used for sorting with the "sort" parameter. If the entry listing endpoint supports sorting, this key MUST be present for sortable properties with value true.

`unit: str` `pydantic-field` ¶

the physical unit of the entry property

`EntryInfoResource (BaseModel)` `pydantic-model` ¶

`description: str` `pydantic-field` `required` ¶

description of the entry

`formats: List[str]` `pydantic-field` `required` ¶

list of available output formats.

`output_fields_by_format: Dict[str, List[str]]` `pydantic-field` `required` ¶

a dictionary of available output fields for this entry type, where the keys are the values of the formats list and the values are the keys of the properties dictionary.

`properties: Dict[str, optimade.models.entries.EntryInfoProperty]` `pydantic-field` `required` ¶

a dictionary describing queryable properties for this entry type, where each key is a property ID.

`EntryRelationships (Relationships)` `pydantic-model` ¶

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

`references: ReferenceRelationship` `pydantic-field` ¶

Object containing links to relationships with entries of the references type.

`structures: StructureRelationship` `pydantic-field` ¶

Object containing links to relationships with entries of the structures type.

`EntryResourceAttributes (Attributes)` `pydantic-model` ¶

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

`immutable_id: str` `pydantic-field` ¶

The entry's immutable ID (e.g., an UUID). This is important for databases having preferred IDs that point to "the latest version" of a record, but still offer access to older variants. This ID maps to the version-specific record, in case it changes in the future. - Type: string. - Requirements/Conventions:

Support: OPTIONAL, i.e., MAY be :val:null.
Query: MUST be a queryable property with support for all mandatory filter features.
Examples:
:val:"8bd3e750-b477-41a0-9b11-3a799f21b44f"
:val:"fjeiwoj,54;@=%<>#32" (Strings that are not URL-safe are allowed.)

`last_modified: datetime` `pydantic-field` `required` ¶

Date and time representing when the entry was last modified. - Type: timestamp. - Requirements/Conventions:

Support: SHOULD be supported, i.e., SHOULD NOT be :val:null. Is REQUIRED in this implementation, i.e., MUST NOT be :val:null.
Query: MUST be a queryable property with support for all mandatory filter features.
Response: REQUIRED in the response unless the query parameter :query-param:response_fields is present and does not include this property.
Example:
As part of JSON response format: :VAL:"2007-04-05T14:30Z" (i.e., encoded as an RFC 3339 Internet Date/Time Format <https://tools.ietf.org/html/rfc3339#section-5.6>__ string.)

`index_metadb` ¶

`IndexInfoAttributes (BaseInfoAttributes)` `pydantic-model` ¶

Attributes for Base URL Info endpoint for an Index Meta-Database

`IndexInfoResource (BaseInfoResource)` `pydantic-model` ¶

Index Meta-Database Base URL Info endpoint resource

`IndexRelationship (BaseModel)` `pydantic-model` ¶

Index Meta-Database relationship

`data: RelatedLinksResource` `pydantic-field` `required` ¶

JSON API resource linkage. It MUST be either null or contain a single Links identifier object with the fields 'id' and 'type'

`RelatedLinksResource (BaseResource)` `pydantic-model` ¶

A related Links resource object

`jsonapi` ¶

This module should reproduce JSON API v1.0 https://jsonapi.org/format/1.0/

`Attributes (BaseModel)` `pydantic-model` ¶

Members of the attributes object ("attributes") represent information about the resource object in which it's defined. The keys for Attributes MUST NOT be: relationships links id type

`BaseResource (BaseModel)` `pydantic-model` ¶

Minimum requirements to represent a Resource

`id: str` `pydantic-field` `required` ¶

Resource ID

`type: str` `pydantic-field` `required` ¶

Resource type

`Error (BaseModel)` `pydantic-model` ¶

An error response

`code: str` `pydantic-field` ¶

an application-specific error code, expressed as a string value.

`detail: str` `pydantic-field` ¶

A human-readable explanation specific to this occurrence of the problem.

`id: str` `pydantic-field` ¶

A unique identifier for this particular occurrence of the problem.

`links: ErrorLinks` `pydantic-field` ¶

A links object storing about

`meta: Meta` `pydantic-field` ¶

a meta object containing non-standard meta-information about the error.

`source: ErrorSource` `pydantic-field` ¶

An object containing references to the source of the error

`status: str` `pydantic-field` ¶

the HTTP status code applicable to this problem, expressed as a string value.

`title: str` `pydantic-field` ¶

A short, human-readable summary of the problem. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.

`hash(self)` `special` ¶

Return hash(self).

Source code in optimade/models/jsonapi.py

def __hash__(self):
    return hash(self.json())

`ErrorLinks (BaseModel)` `pydantic-model` ¶

A Links object specific to Error objects

`about: Union[pydantic.networks.AnyUrl, optimade.models.jsonapi.Link]` `pydantic-field` ¶

A link that leads to further details about this particular occurrence of the problem.

`ErrorSource (BaseModel)` `pydantic-model` ¶

an object containing references to the source of the error

`parameter: str` `pydantic-field` ¶

a string indicating which URI query parameter caused the error.

`pointer: str` `pydantic-field` ¶

a JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute].

`JsonApi (BaseModel)` `pydantic-model` ¶

An object describing the server's implementation

`meta: Meta` `pydantic-field` ¶

Non-standard meta information

`version: str` `pydantic-field` ¶

Version of the json API used

`Link (BaseModel)` `pydantic-model` ¶

A link MUST be represented as either: a string containing the link's URL or a link object.

`href: AnyUrl` `pydantic-field` `required` ¶

a string containing the link’s URL.

`meta: Meta` `pydantic-field` ¶

a meta object containing non-standard meta-information about the link.

`Meta (BaseModel)` `pydantic-model` ¶

Non-standard meta-information that can not be represented as an attribute or relationship.

`Relationship (BaseModel)` `pydantic-model` ¶

Representation references from the resource object in which it’s defined to other resource objects.

`data: Union[optimade.models.jsonapi.BaseResource, List[optimade.models.jsonapi.BaseResource]]` `pydantic-field` ¶

Resource linkage

`links: RelationshipLinks` `pydantic-field` ¶

a links object containing at least one of the following: self, related

`meta: Meta` `pydantic-field` ¶

a meta object that contains non-standard meta-information about the relationship.

`RelationshipLinks (BaseModel)` `pydantic-model` ¶

A resource object MAY contain references to other resource objects ("relationships"). Relationships may be to-one or to-many. Relationships can be specified by including a member in a resource's links object.

`related: Union[pydantic.networks.AnyUrl, optimade.models.jsonapi.Link]` `pydantic-field` ¶

A related resource link

`self: Union[pydantic.networks.AnyUrl, optimade.models.jsonapi.Link]` `pydantic-field` ¶

A link to itself

`Relationships (BaseModel)` `pydantic-model` ¶

Members of the relationships object ("relationships") represent references from the resource object in which it's defined to other resource objects. Keys MUST NOT be: type id

`Resource (BaseResource)` `pydantic-model` ¶

Resource objects appear in a JSON:API document to represent resources.

`attributes: Attributes` `pydantic-field` ¶

an attributes object representing some of the resource’s data.

`links: ResourceLinks` `pydantic-field` ¶

a links object containing links related to the resource.

`meta: Meta` `pydantic-field` ¶

a meta object containing non-standard meta-information about a resource that can not be represented as an attribute or relationship.

`relationships: Relationships` `pydantic-field` ¶

a relationships object describing relationships between the resource and other JSON:API resources.

`ResourceLinks (BaseModel)` `pydantic-model` ¶

A Resource Links object

`self: Union[pydantic.networks.AnyUrl, optimade.models.jsonapi.Link]` `pydantic-field` ¶

A link that identifies the resource represented by the resource object.

`Response (BaseModel)` `pydantic-model` ¶

A top-level response

`data: Union[NoneType, optimade.models.jsonapi.Resource, List[optimade.models.jsonapi.Resource]]` `pydantic-field` ¶

Outputted Data

`errors: List[optimade.models.jsonapi.Error]` `pydantic-field` ¶

A list of unique errors

`included: List[optimade.models.jsonapi.Resource]` `pydantic-field` ¶

A list of unique included resources

`jsonapi: JsonApi` `pydantic-field` ¶

Information about the JSON API used

`links: ToplevelLinks` `pydantic-field` ¶

Links associated with the primary data or errors

`meta: Meta` `pydantic-field` ¶

A meta object containing non-standard information related to the Success

`__json_encoder__(obj)` `special` `staticmethod` ¶

partial(func, args, *keywords) - new function with partial application of the given arguments and keywords.

`ToplevelLinks (BaseModel)` `pydantic-model` ¶

A set of Links objects, possibly including pagination

`first: AnyUrl` `pydantic-field` ¶

The first page of data

`last: AnyUrl` `pydantic-field` ¶

The last page of data

`next: AnyUrl` `pydantic-field` ¶

The next page of data

`prev: AnyUrl` `pydantic-field` ¶

The previous page of data

`related: Union[pydantic.networks.AnyUrl, optimade.models.jsonapi.Link]` `pydantic-field` ¶

A related resource link

`self: Union[pydantic.networks.AnyUrl, optimade.models.jsonapi.Link]` `pydantic-field` ¶

A link to itself

`links` ¶

`LinksResource (EntryResource)` `pydantic-model` ¶

A Links endpoint resource object

`LinksResourceAttributes (Attributes)` `pydantic-model` ¶

Links endpoint resource object attributes

`base_url: Union[pydantic.networks.AnyUrl, optimade.models.jsonapi.Link]` `pydantic-field` `required` ¶

JSON API links object, pointing to the base URL for this implementation

`description: str` `pydantic-field` `required` ¶

Human-readable description for the OPTIMADE API implementation a client may provide in a list to an end-user.

`homepage: Union[pydantic.networks.AnyUrl, optimade.models.jsonapi.Link]` `pydantic-field` `required` ¶

JSON API links object, pointing to a homepage URL for this implementation

`link_type: str` `pydantic-field` `required` ¶

The link type of the represented resource in relation to this implementation. MUST be one of these values: 'child', 'root', 'external', 'providers'.

`name: str` `pydantic-field` `required` ¶

Human-readable name for the OPTIMADE API implementation a client may provide in a list to an end-user.

`optimade_json` ¶

Modified JSON API v1.0 for OPTIMADE API

`BaseRelationshipMeta (Meta)` `pydantic-model` ¶

Specific meta field for base relationship resource

`description: str` `pydantic-field` `required` ¶

OPTIONAL human-readable description of the relationship

`BaseRelationshipResource (BaseResource)` `pydantic-model` ¶

Minimum requirements to represent a relationship resource

`meta: BaseRelationshipMeta` `pydantic-field` ¶

Relationship meta field. MUST contain 'description' if supplied.

`Implementation (BaseModel)` `pydantic-model` ¶

Information on the server implementation

`maintainer: ImplementationMaintainer` `pydantic-field` ¶

A dictionary providing details about the maintainer of the implementation.

`name: str` `pydantic-field` ¶

name of the implementation

`source_url: AnyUrl` `pydantic-field` ¶

URL of the implementation source, either downloadable archive or version control system

`version: str` `pydantic-field` ¶

version string of the current implementation

`ImplementationMaintainer (BaseModel)` `pydantic-model` ¶

Details about the maintainer of the implementation

`email: EmailStr` `pydantic-field` `required` ¶

the maintainer's email address

`OptimadeError (Error)` `pydantic-model` ¶

detail MUST be present

`Provider (BaseModel)` `pydantic-model` ¶

Information on the database provider of the implementation.

`description: str` `pydantic-field` `required` ¶

a longer description of the database provider

`homepage: Union[pydantic.networks.AnyHttpUrl, optimade.models.jsonapi.Link]` `pydantic-field` ¶

a JSON API links object pointing to homepage of the database provider, either directly as a string, or as a link object.

`index_base_url: Union[pydantic.networks.AnyHttpUrl, optimade.models.jsonapi.Link]` `pydantic-field` ¶

a JSON API links object pointing to the base URL for the index meta-database as specified in Appendix 1, either directly as a string, or as a link object.

`name: str` `pydantic-field` `required` ¶

a short name for the database provider

`prefix: str` `pydantic-field` `required` ¶

database-provider-specific prefix as found in Appendix 1.

`Relationship (Relationship)` `pydantic-model` ¶

Similar to normal JSON API relationship, but with addition of OPTIONAL meta field for a resource

`ResponseMeta (Meta)` `pydantic-model` ¶

A JSON API meta member that contains JSON API meta objects of non-standard meta-information.

OPTIONAL additional information global to the query that is not specified in this document, MUST start with a database-provider-specific prefix.

`api_version: str` `pydantic-field` `required` ¶

a string containing the version of the API implementation, e.g. v0.9.5

`data_available: int` `pydantic-field` ¶

an integer containing the total number of data objects available in the database

`data_returned: ConstrainedIntValue` `pydantic-field` `required` ¶

an integer containing the number of data objects returned for the query.

`implementation: Implementation` `pydantic-field` ¶

a dictionary describing the server implementation

`last_id: str` `pydantic-field` ¶

a string containing the last ID returned

`more_data_available: bool` `pydantic-field` `required` ¶

false if all data has been returned, and true if not.

`provider: Provider` `pydantic-field` `required` ¶

information on the database provider of the implementation.

`query: ResponseMetaQuery` `pydantic-field` `required` ¶

information on the query that was requested

`response_message: str` `pydantic-field` ¶

response string from the server

`time_stamp: datetime` `pydantic-field` `required` ¶

a string containing the date and time at which the query was exexcuted

`warnings: List[optimade.models.optimade_json.Warnings]` `pydantic-field` ¶

List of warning resource objects representing non-critical errors or warnings. A warning resource object is defined similarly to a JSON API error object, but MUST also include the field type, which MUST have the value "warning". The field detail MUST be present and SHOULD contain a non-critical message, e.g., reporting unrecognized search attributes or deprecated features. The field status, representing a HTTP response status code, MUST NOT be present for a warning resource object. This is an exclusive field for error resource objects.

`ResponseMetaQuery (BaseModel)` `pydantic-model` ¶

Information on the query that was requested.

`representation: str` `pydantic-field` `required` ¶

a string with the part of the URL that follows the base URL. Example: '/structures?'

`Success (Response)` `pydantic-model` ¶

errors are not allowed

`__json_encoder__(obj)` `special` `staticmethod` ¶

partial(func, args, *keywords) - new function with partial application of the given arguments and keywords.

`either_data_meta_or_errors_must_be_set(values)` `classmethod` ¶

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

Source code in optimade/models/optimade_json.py

@root_validator(pre=True)
def either_data_meta_or_errors_must_be_set(cls, values):
    """Overwriting the existing validation function, since 'errors' MUST NOT be set"""
    required_fields = ("data", "meta")
    if not any(values.get(field) 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 values.get("errors", None) is not None:
        raise ValueError("'errors' MUST be skipped for a successful response")

    return values

`Warnings (OptimadeError)` `pydantic-model` ¶

OPTIMADE-specific warning class based on OPTIMADE-specific JSON API Error. From the specification:

A warning resource object is defined similarly to a JSON API
error object, but MUST also include the field type, which MUST
have the value "warning". The field detail MUST be present and
SHOULD contain a non-critical message, e.g., reporting
unrecognized search attributes or deprecated features.

Note: Must be named "Warnings", since "Warning" is a built-in Python class.

`type: str` `pydantic-field` ¶

Warnings must be of type "warning"

`references` ¶

`Person (BaseModel)` `pydantic-model` ¶

`firstname: str` `pydantic-field` ¶

First name of the person.

`lastname: str` `pydantic-field` ¶

Last name of the person.

`ReferenceResource (EntryResource)` `pydantic-model` ¶

The :entry: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, type, volume, year: Meanings of these properties match the BibTeX specification <http://bibtexml.sourceforge.net/btxdoc.pdf>__, values are strings;
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, i.e., any of the properties MAY be :val: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.

`ReferenceResourceAttributes (EntryResourceAttributes)` `pydantic-model` ¶

Model that stores the attributes of a reference. Many properties match the meaning described in the BibTeX specification.