Skip to content

livery.workshop._schema

livery.workshop._schema

Each contract's JSON Schema, composed from its owners' keys, and its judge.

Every key a contract may have is declared as a record (livery.workshop._contract_keys.Declared): the base's own, and each installed extension's from its declaration file. The records compose into one JSON Schema per contract, for the base and the extensions the root contract lists. The contract judge validates a contract against that schema, in its own words, and fm sync writes it under .workshop/schema/, where the composed .taplo.toml points Taplo, the language server behind an editor's TOML support: the judge and the editor read one statement of each contract's shape.

A key's types become JSON Schema types, its values an enum and its doc the description; a list of strings with values takes each of them at most once. A table whose keys the author names (* in a declared path) takes additionalProperties with the entry's schema, and a key the table declares by name wins over that entry; every other table refuses a key it does not declare. A key of an installed extension the root does not list stays in the schema as a key that takes no value, carrying its owner, so the judge and the editor both name the extension to list.

Functions:

Name Description
compose

The JSON Schema of contract for the base and the listed extensions.

composed

compose, once per set of declarations: what the judge validates against.

contract_of

Which contract the file at relative is; None for a file that is no contract.

judged_by

The line naming the schema the file at relative is judged by; empty for none.

schema_files

Each contract's composed schema for root, by its path under the root.

problems

Each refusal data earns against schema, in the contract's order.

Attributes:

Name Type Description
DIRECTORY
FILES dict[ContractKind, str]
DRAFT
OWNER
UNLISTED_BY

DIRECTORY module-attribute

DIRECTORY = '.workshop/schema'

FILES module-attribute

FILES: dict[ContractKind, str] = {'root': 'workshop.json', 'package': 'package.json', 'extension': 'extension.json'}

DRAFT module-attribute

DRAFT = 'http://json-schema.org/draft-07/schema#'

OWNER module-attribute

OWNER = 'x-owner'

UNLISTED_BY module-attribute

UNLISTED_BY = 'x-unlisted-by'

compose

compose(contract: ContractKind, listed: frozenset[str] | None) -> dict[str, Any]

The JSON Schema of contract for the base and the listed extensions.

listed holds the names the contract's lists name the extensions by, the base among them; None takes every installed owner as listed. A key of an owner they leave out says which lists would take it. The owners in livery.workshop._contract_keys.ALWAYS, the base and the tool store, count as listed in every workspace. The extension contract is the base's and the tool store's alone, since an extension declares keys in a workspace's contracts and never in another extension's file: composing it reads no other owner's declarations, which a mount would otherwise read for every installed extension.

Source code in packages/workshop/src/livery/workshop/_schema.py
def compose(contract: ContractKind, listed: frozenset[str] | None) -> dict[str, Any]:
    """The JSON Schema of *contract* for the base and the *listed* extensions.

    *listed* holds the names the contract's lists name the extensions by,
    the base among them; None takes every installed owner as listed. A
    key of an owner they leave out says which lists would take it.
    The owners in [livery.workshop._contract_keys.ALWAYS][], the base
    and the tool store, count as listed in every workspace. The
    ``extension`` contract is the base's and the tool store's alone,
    since an extension declares keys in a workspace's contracts and
    never in another extension's file: composing it reads no other
    owner's declarations, which a mount would otherwise read for every
    installed extension.
    """
    from livery.workshop._contract_keys import ALWAYS, declarations, extension_keys

    if contract == "extension":
        keys = [(declared, "", "") for declared in extension_keys()]
    else:
        keys = []
        for (kind, _path), owned in sorted(declarations().items()):
            if kind != contract:
                continue
            if listed is None or owned.owner in ALWAYS or owned.owner in listed:
                keys.append((owned.declared, "", ""))
            else:
                keys.append((owned.declared, owned.owner, _unlisted_by(contract)))
    return {
        "$schema": DRAFT,
        "$comment": (
            "Composed by the workshop's sync from the keys the base, the tool"
            " store and the listed extensions declare; written again by every"
            " sync, never edited."
        ),
        "title": _TITLES[contract],
        **_object(_tree(keys)),
    }

composed

composed(contract: ContractKind, listed: frozenset[str] | None) -> dict[str, Any]

compose, once per set of declarations: what the judge validates against.

The judge reads the composition the schema files are written from, never the files, so a file written before an extension was installed or listed cannot misjudge a key until the next sync.

Source code in packages/workshop/src/livery/workshop/_schema.py
def composed(contract: ContractKind, listed: frozenset[str] | None) -> dict[str, Any]:
    """`compose`, once per set of declarations: what the judge validates against.

    The judge reads the composition the schema files are written from,
    never the files, so a file written before an extension was
    installed or listed cannot misjudge a key until the next sync.
    """
    from livery.workshop._contract_keys import declarations, extension_keys

    known: object = extension_keys() if contract == "extension" else declarations()
    held = _COMPOSED.get((contract, listed))
    if held is None or held[0] is not known:
        held = (known, compose(contract, listed))
        _COMPOSED[(contract, listed)] = held
    return cast("dict[str, Any]", held[1])

contract_of

contract_of(root: Path, relative: Path) -> ContractKind | None

Which contract the file at relative is; None for a file that is no contract.

The root's workshop.toml, a package's beneath packages/, or any extension.toml.

Source code in packages/workshop/src/livery/workshop/_schema.py
def contract_of(root: Path, relative: Path) -> ContractKind | None:
    """Which contract the file at *relative* is; None for a file that is no contract.

    The root's ``workshop.toml``, a package's beneath ``packages/``, or
    any ``extension.toml``.
    """
    from livery.workshop._contract import _package_workspace

    if relative.name == "extension.toml":
        return "extension"
    if relative.name != "workshop.toml":
        return None
    if relative == Path("workshop.toml"):
        return "root"
    return "package" if _package_workspace(root / relative) == root else None

judged_by

judged_by(root: Path, relative: Path) -> str

The line naming the schema the file at relative is judged by; empty for none.

The file under .workshop/schema/, and the owners whose keys it holds: the base and the tool store, then the installed set, in composition order. An extension.toml is judged by the base's and the tool store's keys alone.

Source code in packages/workshop/src/livery/workshop/_schema.py
def judged_by(root: Path, relative: Path) -> str:
    """The line naming the schema the file at *relative* is judged by; empty for none.

    The file under ``.workshop/schema/``, and the owners whose keys it
    holds: the base and the tool store, then the installed set, in
    composition order. An ``extension.toml`` is judged by the base's
    and the tool store's keys alone.
    """
    from livery.workshop._contract_keys import ALWAYS

    contract = contract_of(root, relative)
    if contract is None:
        return ""
    owners = list(ALWAYS)
    if contract != "extension":
        from livery.workshop._extensions import extension_names

        owners += extension_names(root)
    return f"schema: {DIRECTORY}/{FILES[contract]} ({', '.join(owners)})"

schema_files

schema_files(root: Path) -> dict[str, bytes]

Each contract's composed schema for root, by its path under the root.

Source code in packages/workshop/src/livery/workshop/_schema.py
def schema_files(root: Path) -> dict[str, bytes]:
    """Each contract's composed schema for *root*, by its path under the root."""
    from livery.workshop._contract import _root_tables
    from livery.workshop._contract_keys import listed_extensions
    from livery.workshop._extensions import installed_set

    listed = listed_extensions(_root_tables(root / "workshop.toml")) | set(
        installed_set(root)
    )
    return {
        f"{DIRECTORY}/{name}": (
            json.dumps(composed(contract, listed), indent=2) + "\n"
        ).encode("utf-8")
        for contract, name in FILES.items()
    }

problems

problems(schema: dict[str, Any], data: dict[str, Any]) -> list[str]

Each refusal data earns against schema, in the contract's order.

An unknown key names its table, the keys the table takes and the nearest spelling; a key of an extension the contract's lists leave out names the extension and the list that would take it; a value of the wrong type names what the key takes; a value outside its set names the set and the nearest. A key that takes any value is judged by its reader, and nothing beneath it here.

Source code in packages/workshop/src/livery/workshop/_schema.py
def problems(schema: dict[str, Any], data: dict[str, Any]) -> list[str]:
    """Each refusal *data* earns against *schema*, in the contract's order.

    An unknown key names its table, the keys the table takes and the
    nearest spelling; a key of an extension the contract's lists leave
    out names the extension and the list that would take it; a value of
    the wrong type names what the key takes; a value outside its set
    names the set and the nearest. A key that takes any value is judged
    by its reader, and nothing beneath it here.
    """
    found: list[str] = []
    _table(schema, data, (), found)
    return found