Skip to content

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.

DataType (Enum)

Optimade Data Types

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

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: SemanticVersion pydantic-field required

A string containing the version of the API implementation.

data_available: int pydantic-field

An integer containing the total number of data resource objects available in the database for the endpoint.

data_returned: ConstrainedIntValue pydantic-field required

An integer containing the total number of data resource objects returned for the current filter query, independent of pagination.

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 resource objects for this filter query have been returned in the response or if it is the last page of a paginated response, and true otherwise.

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 timestamp containing the date and time at which the query was executed.

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

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