topmark.registry.machine.schemas

topmark / registry / machine / schemas

Registry machine-readable output schema types.

This module defines the typing surface for machine-readable output emitted by registry-related commands (currently topmark registry filetypes, topmark registry processors and topmark registry bindings).

These are schema-only types: - They describe the JSON/NDJSON payload shapes. - They help keep payload builders and shape builders consistent. - They do not perform serialization or printing.

Why TypedDict: - Registry payloads are composed from runtime objects and emitted as plain dict/list structures. - The payloads are small, shallow, and naturally expressed as JSON objects.

Serialization conventions: - JSON mode wraps a payload in a top-level envelope with meta plus stable top-level collection keys. - NDJSON mode emits one record per entity, using the canonical record envelope (kind + meta + payload container).

Payload construction lives in topmark.registry.machine.payloads. Envelope/record shaping lives in topmark.registry.machine.envelopes.

FileTypeEntry module-attribute

FileTypeEntry = FileTypeBriefEntry | FileTypeDetailEntry

Single file type entry (brief or detailed).

FileTypesPayload module-attribute

FileTypesPayload = (
    list[FileTypeBriefEntry] | list[FileTypeDetailEntry]
)

Payload for topmark registry filetypes: a list of entries sorted by file type key.

FileTypeRef module-attribute

FileTypeRef = str | FileTypeRefEntry

Reference to a file type.

• In brief mode: a string containing the qualified file type identifier.
• In detail mode: an object containing identity and description fields.

ProcessorEntry module-attribute

ProcessorEntry = ProcessorBriefEntry | ProcessorDetailEntry

Single processor entry (brief or detailed).

ProcessorsPayload module-attribute

ProcessorsPayload = (
    list[ProcessorBriefEntry] | list[ProcessorDetailEntry]
)

Payload for topmark registry processors: a list of entries sorted by processor key.

BindingEntry module-attribute

BindingEntry = BindingBriefEntry | BindingDetailEntry

Single binding entry (brief or detailed).

BindingEntriesPayload module-attribute

BindingEntriesPayload = (
    list[BindingBriefEntry] | list[BindingDetailEntry]
)

List of binding entries in either brief or detailed form, but never mixed.

ProcessorRef module-attribute

ProcessorRef = str | ProcessorRefEntry

Reference to a processor.

• In brief mode: a string containing the qualified processor identifier.
• In detail mode: an object containing identity and description fields.

RegistryKey

Bases: str, Enum

Stable registry-domain keys for machine-readable payloads.

These keys describe the JSON payload containers used by registry-related commands.

Attributes:

Name	Type	Description
BINDINGS		Container key for effective registry bindings.
FILETYPES		Container key for file-type listings.
PROCESSORS		Container key for processor listings.
UNBOUND_FILETYPES		Container key for file types without an effective processor binding.
UNUSED_PROCESSORS		Container key for processors not participating in an effective binding.

RegistryKind

Bases: str, Enum

Stable NDJSON kinds emitted by the registry machine-readable output domain.

Attributes:

Name	Type	Description
BINDING		One effective binding record.
FILETYPE		One file-type record.
PROCESSOR		One processor record.
UNBOUND_FILETYPE		One record for an unbound file type.
UNUSED_PROCESSOR		One record for an unused processor.

FileTypePolicyEntry

Bases: TypedDict

Structured file type policy entry for machine-readable output.

This mirrors the public API policy shape and keeps machine-readable output stable and self-describing.

FileTypeBriefEntry

Bases: TypedDict

Brief file type entry used when --long is not requested.

FileTypeDetailEntry

Bases: TypedDict

Detailed file type entry used when --long is enabled.

FileTypeRefEntry

Bases: TypedDict

Expanded file type reference used in auxiliary registry listings.

ProcessorBriefEntry

Bases: TypedDict

Brief header-processor entry used when --long is not requested.

ProcessorDetailEntry

Bases: TypedDict

Detailed header-processor entry used when --long is enabled.

BindingBriefEntry

Bases: TypedDict

Brief binding entry used when --long is not requested.

BindingDetailEntry

Bases: TypedDict

Detailed binding entry used when --long is enabled.

ProcessorRefEntry

Bases: TypedDict

Expanded processor reference used for unused processor listings.

BindingsPayload

Bases: TypedDict

Payload for topmark registry bindings.

Attributes:

Name	Type	Description
bindings	BindingEntriesPayload	Effective file-type-to-processor bindings.
unbound_filetypes	list[FileTypeRef]	File types that have no effective processor binding.
unused_processors	list[ProcessorRef]	Registered processors that do not currently participate in an effective binding.