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 load_entry_type_definition() / standard_entry_type(). The authoritative, supported copies are the JSON files checked in under httk/core/optimade_defs/ (see the README there).

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(→ None)	Register a database-specific OPTIMADE property-name prefix.
known_definition_prefixes(→ tuple[str, Ellipsis])	Return the registered database-specific property-name prefixes.
load_entry_type_definition(→ EntryTypeDefinition)	Load a vendored OPTIMADE entry-type definition JSON from a package.
standard_entry_type(→ EntryTypeDefinition)	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: str, id_base: str) → None

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.

httk.core.property_definitions.known_definition_prefixes() → tuple[str, Ellipsis]

Return the registered database-specific property-name prefixes.

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

class httk.core.property_definitions.PropertyDefinition(name: str, payload: collections.abc.Mapping[str, Any])

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.

classmethod from_optimade(name: str, definition: collections.abc.Mapping[str, Any]) → Self

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.

classmethod from_simple(name: str, *, description: str, fulltype: str = 'string', unit: str | None = None, dimensions: collections.abc.Mapping[str, Any] | None = None, dict_properties: collections.abc.Mapping[str, str] | None = None, metadata_definition: collections.abc.Mapping[str, Any] | None = None, required_response: bool = False, definition_id: str | None = None) → Self

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_ / _omdb_ — 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().

property name: str

property definition_id: str

property title: str | None

property description: str

property optimade_type: str

property json_type: Any

property nullable: bool

property unit: str | None

property format_version: str | None

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

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

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

with_implementation(*, sortable: bool | None = None, response_default: bool | None = None) → Self

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.

as_optimade() → dict[str, Any]

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

class httk.core.property_definitions.EntryTypeDefinition(name: str, description: str, properties: collections.abc.Mapping[str, PropertyDefinition])

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 columns()).

classmethod from_optimade(name: str, entrytype: collections.abc.Mapping[str, Any]) → Self

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

entrytype is the vendored document shape: a description string and a properties mapping of property name to full property definition. A clear ValueError is raised when either is missing.

property name: str

property description: str

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

extended(extra: collections.abc.Mapping[str, PropertyDefinition], *, allow_unprefixed: bool = False) → Self

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.

as_optimade() → dict[str, Any]

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

httk.core.property_definitions.load_entry_type_definition(package: str, name: str) → EntryTypeDefinition

Load a vendored OPTIMADE entry-type definition JSON from a package.

Reads optimade_defs/<name>.json from package (via importlib.resources) and models it as an EntryTypeDefinition. Results are cached per (package, name).

httk.core.property_definitions.standard_entry_type(name: str) → EntryTypeDefinition

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.