Contracts

Understanding Contracts

Contracts in BeDoc define the expected structure of input and output data for parsers and formatters. They ensure that actions are compatible with each other, preventing mismatches and inconsistencies.

Where contracts live

A contract is a separate Terms file (YAML or JSON5) that an action points at through its meta.terms field using a ref:// path, resolved relative to the action file:

static meta = Object.freeze({
  kind: "parser",
  input: "lua",
  terms: "ref://./bedoc-lua-parser.yaml",
})

Each Terms file should declare the BeDoc action $schema so editors can validate it:

# yaml-language-server: $schema=https://schema.gesslar.dev/bedoc/v1/bedoc-action.json
$schema: https://schema.gesslar.dev/bedoc/v1/bedoc-action.json
provides:
  type: object
  # …

Getting Meta with It

When you create a contract, you’re defining a schema that describes the shape of the data the action will accept or provide. This schema follows the BeDoc schema (which, yes, follows the JSON schema schema… it’s schemas all the way down).

The Lifecycle of a Contract

1. Negotiation Phase → A contract starts as a declaration of intent, outlining what an action claims it will accept or provide.
2. Validation Phase → BeDoc validates the contract to ensure it follows the contract schema and that a parser-formatter pair agrees on expectations.
3. Enforcement Phase → Once validated, the contract becomes a schema. BeDoc ensures that:
   • A parser’s output matches its contract before proceeding.
   • A formatter receives data that aligns with its contract.
   • The contract remains binding for the entire data processing cycle.

How Contracts Are Used

BeDoc actively enforces contracts at runtime, ensuring that data remains consistent throughout processing. If a parser’s output does not match its contract, the process will halt before passing data to the formatter. Similarly, the formatter must confirm the input matches its agreed structure before execution.

Key Contract Elements

• accepts → Defines what structure an action can process.
• provides → Defines what structure an action outputs.
• A contract must specify either accepts or provides, but never both.

Minimal Parser Contract Example

YAML

provides:
  type: object

JSON5

{
  "provides": {
    "type": "object"
  }
}

Minimal Formatter Contract Example

YAML

accepts:
  type: object

JSON5

{
  "accepts": {
    "type": "object"
  }
}

For complete contract examples, see the Examples section.