Skip to content
Registry StackDocsv0.46.0
Search

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

Section titled “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

Section titled “Start from the facility template”
Terminal window
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.

Terminal window
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

Section titled “Read the top of registry.yaml”
facility/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

Section titled “Declare Record types”
facility/registry.yaml
  - 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 scalar constraints from valueTypes, and apiName sets the public property name. In both projects and modules, declare reference, crs84-point, and structured types directly on each field or Action input instead of through valueTypes. mutationPolicy here means a facility changes only through a Proposal, even for a caller whose profile grants patch.

Grant access

Section titled “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

Section titled “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.

Schedule a Record-controlled Action

Section titled “Schedule a Record-controlled Action”

A Record timer schedules one bounded immediate Action from control fields on the Record. The Record type declares the timer, while the root project grants the exact Record type and timer pair. Read the canonical Record timers guide for the authoring contract, inspection commands, and milestone boundaries.

Next

Section titled “Next”