Models and specifications

ogcat.models.JsonValue

JSON-compatible scalar, list, or object value accepted in catalog metadata.

ogcat.models.MetadataDict

Mapping from metadata field names to JsonValue.

class ogcat.CatalogRecord(catalog, time_added, id=None, record_type='managed_file', locator=<factory>, artifacts=<factory>, stored_abspath=None, stored_relpath=None, storage_mode=None, status='active', lifecycle_metadata=<factory>, original_path=None, original_filename=None, suffixes=<factory>, user_metadata=<factory>, derived_metadata=<factory>, naming_metadata=<factory>)

Bases: object

A single catalogued artifact record.

Parameters:

• catalog (str) – Catalog name.

• time_added (str) – ISO 8601 record creation timestamp.

• id (str | None) – Repository-assigned record identifier.

• record_type (str) – Logical record type.

• locator (ArtifactLocator) – Artifact locator.

• artifacts (list[ArtifactDescriptor]) – Artifact descriptors owned by this record.

• stored_abspath (str | None) – Backwards-compatible absolute path for path records.

• stored_relpath (str | None) – Backwards-compatible catalog-relative path.

• storage_mode (str | None) – Storage mode such as "copy", "move", or "external".

• status (str) – Reserved record lifecycle status. "active" records are visible in normal searches; "deleted" records are tombstones.

• lifecycle_metadata (MetadataDict) – Reserved JSON-compatible lifecycle details such as delete/restore operation ids and incomplete purge attempt metadata.

• original_path (str | None) – Original source path or URI.

• original_filename (str | None) – Original source filename.

• suffixes (list[str]) – Source suffixes.

• user_metadata (MetadataDict) – User-supplied metadata.

• derived_metadata (MetadataDict) – Extracted or hook-supplied metadata.

• naming_metadata (MetadataDict) – Metadata used for storage template rendering.

status: str

lifecycle_metadata: dict[str, str | int | float | bool | None | list[str | int | float | bool | None | list[JsonValue] | dict[str, JsonValue]] | dict[str, str | int | float | bool | None | list[JsonValue] | dict[str, JsonValue]]]

path()

Return a local path for path-backed records.

Return type:

Path | None

to_dict()

Convert the record to a plain dictionary.

Return type:

MetadataDict

classmethod from_dict(data)

Build a record from a plain dictionary.

Return type:

CatalogRecord

class ogcat.ArtifactDescriptor(id, role, locator=None, state='available', relationship=<factory>, claims=<factory>, facets=<factory>)

Bases: object

Persistent descriptor for one artifact owned by a catalog record.

Parameters:

• id (str) – Record-local artifact identifier.

• role (str) – Artifact role, such as "data_artifact" or "view_link".

• locator (ArtifactLocator | None) – Optional locator for physical or resolvable artifacts.

• state (str) – Lightweight lifecycle or availability state.

• relationship (MetadataDict) – JSON-compatible relationship metadata.

• claims (list[ArtifactClaim | Mapping[str, object]]) – Artifact claims normalized to explicit JSON-compatible dictionaries.

• facets (list[ArtifactFacet | Mapping[str, object]]) – Artifact facets normalized to explicit JSON-compatible dictionaries.

to_dict()

Convert the artifact descriptor to a plain dictionary.

Return type:

MetadataDict

classmethod from_dict(data)

Build an artifact descriptor from a plain dictionary.

Return type:

ArtifactDescriptor

class ogcat.ArtifactClaim(kind, name, namespace='ogcat.core', version='1', evidence='declared', confidence=None, metadata=<factory>)

Bases: object

Namespaced claim about an artifact’s data type, representation, or interface.

Parameters:

• kind (str) – Claim category. Core recognizes "data_type", "representation", and "interface", but stores other non-empty strings for plugin-owned claim categories.

• name (str) – Namespaced claim name, such as "bytes", "netcdf", or "xarray-dataset".

• namespace (str) – Stable namespace that owns the claim name.

• version (str) – Version of the namespace-local claim schema.

• evidence (str) – How the claim was produced.

• confidence (str | None) – Confidence/status term for the claim. Defaults to evidence.

• metadata (MetadataDict) – JSON-compatible structured details for this claim.

to_dict()

Convert the claim to its JSON-compatible dictionary shape.

Return type:

MetadataDict

classmethod from_dict(data, *, field_name='claim')

Build an artifact claim from a plain dictionary.

Return type:

ArtifactClaim

class ogcat.DataTypeClaim(name, *, namespace='ogcat.core', version='1', evidence='declared', confidence=None, metadata=None)

Bases: ArtifactClaim

Artifact claim describing the external or source data type.

kind: str

name: str

namespace: str

version: str

evidence: str

confidence: str | None

metadata: dict[str, str | int | float | bool | None | list[str | int | float | bool | None | list[JsonValue] | dict[str, JsonValue]] | dict[str, str | int | float | bool | None | list[JsonValue] | dict[str, JsonValue]]]

class ogcat.RepresentationClaim(name, *, namespace='ogcat.core', version='1', evidence='declared', confidence=None, metadata=None)

Bases: ArtifactClaim

Artifact claim describing a storage or encoding representation.

kind: str

name: str

namespace: str

version: str

evidence: str

confidence: str | None

metadata: dict[str, str | int | float | bool | None | list[str | int | float | bool | None | list[JsonValue] | dict[str, JsonValue]] | dict[str, str | int | float | bool | None | list[JsonValue] | dict[str, JsonValue]]]

class ogcat.InterfaceClaim(name, *, namespace='ogcat.core', version='1', evidence='declared', confidence=None, metadata=None)

Bases: ArtifactClaim

Artifact claim describing an access interface exposed by an artifact.

kind: str

name: str

namespace: str

version: str

evidence: str

confidence: str | None

metadata: dict[str, str | int | float | bool | None | list[str | int | float | bool | None | list[JsonValue] | dict[str, JsonValue]] | dict[str, str | int | float | bool | None | list[JsonValue] | dict[str, JsonValue]]]

class ogcat.ArtifactFacet(kind, name, namespace='ogcat.core', version='1', evidence='declared', confidence=None, metadata=<factory>)

Bases: object

Namespaced structured fact about an artifact or claim.

Parameters:

• kind (str) – Facet category, such as "stat", "suffix", or a plugin-owned category.

• name (str) – Namespace-local facet name.

• namespace (str) – Stable namespace that owns the facet name.

• version (str) – Version of the namespace-local facet schema.

• evidence (str) – How the facet was produced.

• confidence (str | None) – Confidence/status term for the facet. Defaults to evidence.

• metadata (MetadataDict) – JSON-compatible structured fact payload.

to_dict()

Convert the facet to its JSON-compatible dictionary shape.

Return type:

MetadataDict

classmethod from_dict(data, *, field_name='facet')

Build an artifact facet from a plain dictionary.

Return type:

ArtifactFacet

ogcat.iter_claims(descriptor, *, kind=None, name=None, namespace=None, version=None)

Yield normalized claims from a descriptor that match optional filters.

Parameters:

• descriptor (ArtifactDescriptor) – Artifact descriptor to inspect.

• kind (str | None) – Optional claim kind filter.

• name (str | None) – Optional claim name filter.

• namespace (str | None) – Optional claim namespace filter.

• version (str | None) – Optional claim version filter.

Yields:

Normalized JSON-compatible claim dictionaries.

Return type:

Iterator[MetadataDict]

ogcat.has_claim(descriptor, *, kind=None, name=None, namespace=None, version=None)

Return whether a descriptor has at least one matching claim.

Return type:

bool

ogcat.claim_key(claim)

Return the stable lookup key for a claim.

The key order is (namespace, kind, name, version) so registry lookup can group by owner namespace before interpreting the namespace-local name.

Return type:

tuple[str, str, str, str]

ogcat.iter_facets(descriptor, *, kind=None, name=None, namespace=None, version=None)

Yield normalized facets from a descriptor that match optional filters.

Parameters:

• descriptor (ArtifactDescriptor) – Artifact descriptor to inspect.

• kind (str | None) – Optional facet kind filter.

• name (str | None) – Optional facet name filter.

• namespace (str | None) – Optional facet namespace filter.

• version (str | None) – Optional facet version filter.

Yields:

Normalized JSON-compatible facet dictionaries.

Return type:

Iterator[MetadataDict]

ogcat.has_facet(descriptor, *, kind=None, name=None, namespace=None, version=None)

Return whether a descriptor has at least one matching facet.

Return type:

bool

ogcat.facet_key(facet)

Return the stable lookup key for a facet.

The key order is (namespace, kind, name, version) so callers can group facts by owner namespace before interpreting namespace-local names.

Return type:

tuple[str, str, str, str]

class ogcat.ArtifactLocator(kind, value, relative_path=None)

Bases: object

Minimal locator for a catalogued artifact.

Parameters:

• kind (str) – Locator kind, such as "path", "uri", or "opaque".

• value (str) – Locator value, usually a path or URI string.

• relative_path (str | None) – Optional path relative to a catalog-managed root.

classmethod from_path(path, *, relative_path=None)

Build a locator for a local path-backed artifact.

Parameters:

• path (str | Path) – Local filesystem path.

• relative_path (str | None) – Optional catalog-relative path.

Return type:

ArtifactLocator

Returns:

Path-backed artifact locator.

classmethod path(path, *, relative_path=None)

Build a local path locator.

This compatibility alias is kept for existing code. Prefer from_path() in new code.

Return type:

ArtifactLocator

classmethod from_urlpath(urlpath, *, relative_path=None)

Build a locator for an fsspec-addressable URL path.

Parameters:

• urlpath (str) – URL path understood by fsspec, such as s3://....

• relative_path (str | None) – Optional storage-root-relative path.

Return type:

ArtifactLocator

Returns:

URL-path-backed artifact locator.

to_dict()

Convert the locator to a plain dictionary.

Return type:

MetadataDict

classmethod from_dict(data)

Build a locator from a plain dictionary.

Return type:

ArtifactLocator

as_path()

Return the locator as a path when the locator is path-backed.

Return type:

Path | None

class ogcat.MetadataFieldDescription(name, description, example=None, required=False, value_types=<factory>)

Bases: object

Lightweight description of an important metadata field.

Parameters:

• name (str) – Metadata key.

• description (str) – Human-readable description for docs and CLI output.

• example (JsonValue) – Optional JSON-compatible example value.

• required (bool) – Whether the field must be present during ingest.

• value_types (list[str]) – Optional type labels used by validation.

to_dict()

Convert the field description to a plain dictionary.

Return type:

MetadataDict

classmethod from_dict(data)

Build a field description from a plain dictionary.

Return type:

MetadataFieldDescription

class ogcat.CatalogSpec(catalog_name, db_backend='tinydb', db_path='db.json', files_root='data/files', objects_root='', default_operation='copy', field_resolution_order=<factory>, default_record_schema='default', default_schema=None, record_schemas=<factory>)

Bases: object

Self-describing configuration for a catalog.

Parameters:

• catalog_name (str) – Human-readable catalog name.

• db_backend (str) – Repository backend identifier. Only "tinydb" is supported today.

• db_path (str) – Database path relative to the catalog root.

• files_root (str) – Human-readable managed file view root relative to the catalog root.

• objects_root (str) – UUID primary object storage root relative to the catalog root.

• default_operation (Literal['copy', 'move']) – Default managed-file operation.

• field_resolution_order (list[str]) – Namespace order for flattened search fields.

• default_record_schema (str) – Name of the fallback schema in record_schemas.

• default_schema (RecordSchema | dict[str, object] | None) – Optional constructor convenience for the fallback schema.

• record_schemas (dict[str, RecordSchema]) – Named schemas for record types.

default_record_schema: str

to_dict()

Convert the spec to a serialisable dictionary.

Return type:

dict[str, object]

classmethod from_dict(data)

Build a spec from a dictionary.

Return type:

CatalogSpec

get_schema(record_type=None)

Return the effective schema for a record type.

Parameters:

record_type (str | None) – Optional record type. When omitted, the broad default schema is returned.

Raises:

ValueError – If a non-default record type has no schema.

Return type:

RecordSchema

list_record_schemas()

Return available named record schema names.

Return type:

list[str]

write(path)

Write the spec JSON to disk.

Return type:

None

classmethod read(path)

Read a spec JSON file from disk.

Return type:

CatalogSpec

class ogcat.RecordSchema(description='', directory_template=None, filename_template=None, metadata_fields=<factory>, display_fields=<factory>, allow_unknown_metadata=True)

Bases: object

Lightweight metadata and naming schema for one record type.

Parameters:

• description (str) – Human-readable schema description.

• directory_template (str | None) – Optional storage directory template.

• filename_template (str | None) – Optional storage filename template.

• metadata_fields (list[MetadataFieldDescription]) – Described metadata fields.

• display_fields (list[str]) – Preferred fields for compact search/result display.

• allow_unknown_metadata (bool) – Whether fields outside metadata_fields are allowed during strict validation.

display_fields: list[str]

to_dict()

Convert the schema to a serialisable dictionary.

Return type:

dict[str, object]

classmethod from_dict(data)

Build a record schema from a dictionary.

Return type:

RecordSchema

with_fallbacks(fallback)

Return this schema with missing naming templates filled from a fallback schema.

Return type:

RecordSchema

required_field_names()

Return required metadata field names for this schema.

Return type:

list[str]