httk.core.property_definitions

First-class OPTIMADE property and entry-type definitions.

An OPTIMADE property definition is a self-describing JSON document giving a property’s canonical identifier, type, unit, requirements, and human-readable description. An entry-type definition bundles the property definitions of one entry type (structures, references, …) together with the entry type’s own description.

This module models both as immutable Python objects:

• PropertyDefinition wraps one full property-definition document. It can be built from a vendored OPTIMADE definition (PropertyDefinition.from_optimade()) or generated from a compact description (PropertyDefinition.from_simple()).

• EntryTypeDefinition wraps an entry type’s description and the ordered mapping of its property definitions, and can be extended() with database-specific custom properties.

The vendored OPTIMADE standard definitions shipped with httk-core (the references, files, and calculations entry types) are loaded through the IRI schema registry by standard_entry_type() and load_entry_type_definition().

On the “1.2” definition-format stamp: PropertyDefinition.from_simple() generates only property-definition features that already exist in format "1.2" of the OPTIMADE property-definition schema, so every generated definition is stamped x-optimade-definition.format == "1.2". The definition format is versioned in lockstep with the OPTIMADE specification and is only bumped when a definition actually uses features introduced by a newer format; custom generated definitions therefore keep the "1.2" stamp even for entry types (such as calculations) whose specification version is newer.

Attributes

PROPERTY_DEFINITION_META_SCHEMA

Classes

PropertyDefinition	An immutable wrapper around one full OPTIMADE property definition.
EntryTypeDefinition	An immutable OPTIMADE entry-type definition.

Functions

register_definition_prefix(prefix, id_base)	Register a database-specific OPTIMADE property-name prefix.
known_definition_prefixes()	Return the registered database-specific property-name prefixes.
standard_entry_type(name)	Return one of httk-core's vendored standard OPTIMADE entry types.

Module Contents

httk.core.property_definitions.PROPERTY_DEFINITION_META_SCHEMA = 'https://schemas.optimade.org/meta/v1.2/optimade/property_definition.json'

httk.core.property_definitions.register_definition_prefix(prefix, id_base)

Register a database-specific OPTIMADE property-name prefix.

A custom property served by a database MUST use such a prefix (see the OPTIMADE specification, “Database-Specific Properties”). Once registered, a property name carrying prefix gets its $id synthesized under id_base by PropertyDefinition.from_simple(), and EntryTypeDefinition.extended() accepts it as a custom property.

prefix must be a lower-case alphanumeric token wrapped in single underscores (matching _[a-z0-9]+_); anything else raises a clear ValueError. Re-registering an existing prefix overwrites its base.

Parameters:

• prefix (str) – The database-specific property-name prefix to register.

• id_base (str) – The IRI base used for synthesized property definition IDs.

Raises:

ValueError – If prefix does not match _[a-z0-9]+_.

httk.core.property_definitions.known_definition_prefixes()

Return the registered database-specific property-name prefixes.

The tuple reflects the current state of the prefix registry (see register_definition_prefix()); _httk_ is pre-registered.

Returns:

The registered prefixes in registration order.

Return type:

tuple[str, Ellipsis]

class httk.core.property_definitions.PropertyDefinition(name, payload)

An immutable wrapper around one full OPTIMADE property definition.

Instances are constructed from a vendored definition document (from_optimade()) or generated from a compact description (from_simple()). The wrapped document is always deep-copied on the way in and out, so an instance never shares mutable state with its inputs or its callers.

Parameters:

• name (str) – The canonical property name.

• payload (collections.abc.Mapping[str, Any]) – The complete property-definition document.

classmethod from_optimade(name, definition)

Wrap a full vendored OPTIMADE property definition.

definition must at least carry $id, description, x-optimade-type, and type; a clear ValueError is raised otherwise. The document is deep-copied.

Parameters:

• name (str) – The canonical property name.

• definition (collections.abc.Mapping[str, Any]) – The full property-definition document to wrap.

Returns:

A validated property definition.

Raises:

ValueError – If a required property-definition field is missing.

Return type:

Self

classmethod from_simple(name, *, description, fulltype='string', unit=None, dimensions=None, dict_properties=None, metadata_definition=None, required_response=False, definition_id=None)

Generate a property definition from a compact description.

This mirrors the OPTIMADE property-definition generator: it emits the $schema meta-schema reference, a synthesized $id (under the base registered for a matching prefix via register_definition_prefix() — e.g. httk.org for _httk_ — under schemas.optimade.org otherwise, unless definition_id overrides it), a title, the description, the OPTIMADE type derived from fulltype ("string", "integer", "float", "boolean", "timestamp", "dict", or "list of ..."), the x-optimade-unit (with an ångström unit definition when unit == "angstrom"), the x-optimade-definition stamp (format "1.2"; see the module docstring), the JSON type with nullability derived from required_response, items for lists, a date-time format for timestamps, inner properties for dicts (from dict_properties), x-optimade-dimensions from dimensions, and an x-optimade-metadata-definition (explicit, or a generated list_axes definition when dimensions is given).

The result is implementation-neutral: per-deployment sortable and response-default flags are layered on later via with_implementation().

Parameters:

• name (str) – The canonical property name.

• description (str) – The human-readable property description.

• fulltype (str) – The OPTIMADE property type description.

• unit (str | None) – The unit associated with numeric or list values.

• dimensions (collections.abc.Mapping[str, Any] | None) – Dimension names and sizes for list values.

• dict_properties (collections.abc.Mapping[str, str] | None) – Inner property names and type descriptions for dictionaries.

• metadata_definition (collections.abc.Mapping[str, Any] | None) – An explicit metadata definition for the property.

• required_response (bool) – Whether responses must contain a non-null value.

• definition_id (str | None) – An explicit property-definition IRI.

Returns:

A generated property definition.

Return type:

Self

property name: str

Return the canonical property name.

property definition_id: str

Return the property’s definition IRI.

property title: str | None

Return the property’s title, if declared.

property description: str

Return the property’s human-readable description.

property optimade_type: str

Return the property’s OPTIMADE type name.

property json_type: Any

Return the property’s JSON Schema type declaration.

property nullable: bool

Return whether the property’s JSON type permits null.

property unit: str | None

Return the property’s declared unit, if any.

property format_version: str | None

Return the property’s definition-format version, if declared.

property requirements: collections.abc.Mapping[str, Any]

Return the property’s OPTIMADE requirements mapping.

property dimensions: collections.abc.Mapping[str, Any] | None

Return the property’s dimensions declaration, if any.

property metadata_definition: collections.abc.Mapping[str, Any] | None

Return the property’s metadata definition, if any.

with_implementation(*, sortable=None, response_default=None)

Return a copy carrying this deployment’s implementation flags.

Adds an x-optimade-implementation object with the sortable and response-default keys that are provided (a None argument leaves that key unset), and — when sortable is given — mirrors it in a top-level sortable field. The original instance is untouched. The original $id and x-optimade-definition are retained because the vendored v1.2 Property Definitions meta-schema says definitions “SHOULD be regarded as the same if they only differ by” changes to x-optimade-implementation; the specification says a redefinition “MUST change the $id”. Top-level sortable is the additional field required by the Entry Listing Info Endpoints section.

Parameters:

• sortable (bool | None) – Whether the property can be sorted by the deployment.

• response_default (bool | None) – Whether the property is included by default in responses.

Returns:

A copy with the requested implementation flags.

Return type:

Self

as_optimade()

Return a deep copy of the wrapped property-definition document.

Returns:

The wrapped document, independent of the instance’s state.

Return type:

dict[str, Any]

class httk.core.property_definitions.EntryTypeDefinition(name, description, properties, definition_id=None, extends_id=None)

An immutable OPTIMADE entry-type definition.

Bundles the entry type’s name and description with an insertion-ordered mapping of PropertyDefinition objects (one per described property). A standard definition typically describes more properties than any given deployment serves; the served subset is chosen separately (an EntryProvider names it through its property_keys()).

definition_id identifies the source document when present. An extended definition is a new document, so it clears that identity and retains the original standard IRI in extends_id instead.

Parameters:

• name (str) – The entry type name.

• description (str) – The human-readable entry type description.

• properties (collections.abc.Mapping[str, PropertyDefinition]) – Property definitions keyed by property name.

• definition_id (str | None) – The source document IRI, if one exists.

• extends_id (str | None) – The standard document IRI extended by this definition, if any.

classmethod from_optimade(name, entrytype)

Build an entry-type definition from a vendored OPTIMADE entry type.

entrytype is the vendored document shape: a description string, an optional top-level $id, and a properties mapping of property name to full property definition. A clear ValueError is raised when either required field is missing. The optional ID identifies the source document; ad-hoc definitions remain valid without one.

Parameters:

• name (str) – The entry type name.

• entrytype (collections.abc.Mapping[str, Any]) – The vendored entry-type definition document.

Returns:

An entry-type definition built from the document.

Raises:

ValueError – If description or properties is missing.

Return type:

Self

property name: str

Return the entry type name.

property description: str

Return the entry type description.

property definition_id: str | None

Return this definition’s document IRI, if it has a standard one.

property extends_id: str | None

Return the original standard IRI extended to make this definition, if any.

property properties: collections.abc.Mapping[str, PropertyDefinition]

Return a copy of the property definitions keyed by name.

extended(extra, *, allow_unprefixed=False)

Return a copy with extra custom property definitions merged in.

Each name in extra MUST be new (a collision with an existing property raises ValueError naming it) and, unless allow_unprefixed is set, MUST carry a registered database-specific prefix (see register_definition_prefix() / known_definition_prefixes()); a custom property that does not is rejected with a ValueError explaining the OPTIMADE prefix rule. The result deliberately has no definition_id: it is a new document, not the standard resource. Its extends_id records the original standard ID so repeated extensions retain that provenance.

Parameters:

• extra (collections.abc.Mapping[str, PropertyDefinition]) – New custom property definitions to add.

• allow_unprefixed (bool) – Whether to allow custom names without a registered prefix.

Returns:

A new definition containing the original and extra properties.

Raises:

ValueError – If a property collides or violates the prefix rule.

Return type:

Self

as_optimade()

Return the entry type as a vendored-shape OPTIMADE document.

Returns:

The entry-type document with independent property payloads.

Return type:

dict[str, Any]

httk.core.property_definitions.standard_entry_type(name)

Return one of httk-core’s vendored standard OPTIMADE entry types.

Supported names are "references", "files", and "calculations"; an unknown name raises a ValueError listing the known ones. The structures standard is vendored by httk-atomistic, not httk-core.

Parameters:

name (str) – The standard entry type name to load.

Returns:

The vendored entry-type definition.

Raises:

ValueError – If name is not vendored by httk-core.

Return type:

EntryTypeDefinition