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>, stored_abspath=None, stored_relpath=None, storage_mode=None, 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.

• 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".

• 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.

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.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='files', 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) – Managed file 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>, 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.

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

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]