topmark.toml.machine.schemas

topmark / toml / machine / schemas

Schema dataclasses for TOML-domain machine-readable output.

This module defines strongly typed, JSON-friendly payload dataclasses used for machine-readable TOML provenance output.

Responsibilities

• Represent ordered TOML provenance layers for config inspection output.
• Serialize TOML provenance payloads using stable TOML-domain keys.

This module performs no I/O and does not build JSON envelopes or NDJSON records.

TomlKey

Bases: str, Enum

Stable keys for TOML provenance payload fragments.

These keys are owned by the TOML machine-readable output domain. They describe the inner schema of provenance-layer fragments and the outer config_layers container emitted for TOML provenance payloads.

Attributes:

Name	Type	Description
CONFIG_LAYERS		Container key for ordered provenance layers.
KIND		Key describing the resolved provenance-layer kind.
ORIGIN		Source label for the provenance layer.
PRECEDENCE		Numeric layer precedence.
TOML		Nested TopMark TOML fragment for the layer.
SCOPE_ROOT		Optional scope root attached to the layer.

TomlProvenanceLayerPayload dataclass

TomlProvenanceLayerPayload(
    *, origin, kind, precedence, toml, scope_root=None
)

One machine-readable TOML provenance layer.

Attributes:

Name	Type	Description
origin	str	Provenance origin label for the layer.
kind	str	Resolved config-layer kind value.
precedence	int	Layer precedence, where lower values apply earlier.
toml	dict[str, object]	Source-local TopMark TOML fragment for this layer.
scope_root	str | None	Optional scope root associated with the layer.

to_dict

to_dict()

Return the layer payload as a JSON-friendly mapping.

Returns:

Type	Description
dict[str, object]	A dict using stable TOML-domain machine keys.

Source code in src/topmark/toml/machine/schemas.py

def to_dict(self) -> dict[str, object]:
    """Return the layer payload as a JSON-friendly mapping.

    Returns:
        A dict using stable TOML-domain machine keys.
    """
    out: dict[str, object] = {
        TomlKey.ORIGIN.value: self.origin,
        TomlKey.KIND.value: self.kind,
        TomlKey.PRECEDENCE.value: self.precedence,
        TomlKey.TOML.value: self.toml,
    }
    if self.scope_root is not None:
        out[TomlKey.SCOPE_ROOT.value] = self.scope_root
    return out

TomlProvenancePayload dataclass

TomlProvenancePayload(*, layers)

Machine-readable layered TopMark TOML provenance export.

Attributes:

Name	Type	Description
layers	list[TomlProvenanceLayerPayload]	Ordered provenance layers, starting with the built-in defaults layer when present.

to_dict

to_dict()

Return the provenance payload as a JSON-friendly mapping.

Returns:

Type	Description
dict[str, object]	A dict containing the ordered config_layers export.

Source code in src/topmark/toml/machine/schemas.py

def to_dict(self) -> dict[str, object]:
    """Return the provenance payload as a JSON-friendly mapping.

    Returns:
        A dict containing the ordered `config_layers` export.
    """
    return {
        TomlKey.CONFIG_LAYERS.value: [layer.to_dict() for layer in self.layers],
    }