Author a registry project

View as Markdown

If you are describing your own registry to the Base Registry Engine (BReg), you write a project: a directory of files that declares what the registry stores, who may read and change it, and how it changes. You can start a project three ways, then check it offline, with no database.

Choose a starting point

bregctl init <directory> writes the default minimal-directory starter: one contact Record type, the project the tutorials use.
bregctl init --template facility-registry <directory> writes facilities, operators, assignments, and a directory, with immediate and Proposal Actions and a Rhai plan.
bregctl init --from publicschema <directory> derives a project from the PublicSchema concepts you select. Derive a registry from PublicSchema walks through it.

Each writes into a new directory and refuses one that exists.

Start from the facility template

bregctl init --template facility-registry facility

Initialized a registry project. 10 artifacts written.
  revision  sha256:<digest>

  README.md
  dev-clients.yaml
  examples/inputs/correction.json
  examples/inputs/deactivation.json
  examples/inputs/empty.json
  examples/inputs/facility.json
  examples/scenarios.json
  plans/correct-address.rhai
  registry.yaml
  tests/journeys.yaml

registry.yaml is the registry itself. dev-clients.yaml names the local test callers and the access profile each one requests. tests/journeys.yaml holds the permitted and refused requests the project must keep passing. examples/ holds ready-made requests for a local run, and plans/correct-address.rhai is the plan code one Action calls.

bregctl check facility

Authoring check passed; registry revision sha256:<digest>.

Check compiles all three YAML files together. It also prints one warning about a related-records read, which Control access and reads explains.

Read the top of registry.yaml

apiVersion: id.registrystack.org/formats/breg/project/v1alpha1
kind: BRegProject
project:
  id: facility-registry
  canonicalBaseIri: https://facility-registry.example.gov
  version: 0.1.0
  defaultLanguage: en
  display:
    label: Facility Registry
    description: Facilities, operators, assignments, and an administrative directory.

project gives the registry its identity. The rest of the file follows in this order: package (the source revision a production package records), datasets, reviewAuthorities, recordTypes, valueTypes, functions, actions, accessProfiles, and vocabularies. A project may also declare modules, statisticalDatasets, recipients, and evidenceProviders. The configuration reference lists every key with its type and bounds.

Declare Record types

  - id: facility
    route: facilities
    primaryDataset: facility-registry
    mutationMode: mutable
    readPaths:
      - {id: operators, through: facility-assignment, to: operator, route: operators}
    mutationPolicy:
      patch: proposal-required

Each Record type names its route, its dataset, and its fields. Every field declares its type, bounds, requiredness, and classification; typeRef reuses a type from valueTypes, and apiName sets the public property name. mutationPolicy here means a facility changes only through a Proposal, even for a caller whose profile grants patch.

Grant access

An access profile binds required scopes, purposes, and row boundaries to four separate kinds of grant: permissions.records, permissions.actions, permissions.proposals, and permissions.datasets for statistical datasets. A local client in dev-clients.yaml only requests a profile; declaring it grants nothing.

Declare Actions and plan code

An Action is a named change with typed inputs. A Function declares its runtime, source, entrypoint, ABI, capabilities, and limits, and the Action that calls it fixes what it may write. Record hooks announce committed changes; Bind webhook receivers covers delivery.