Extend a registry with a module

In about fifteen minutes you will add an optional internal note to every contact without editing the contact Record type itself: the module written, pinned, checked for production, and visible in the generated schema.

Outcome: The contact Record type extended by a pinned module that passes the production check and appears in the generated schema.
Time: About 15 minutes
Level: Local evaluation only
Prerequisites: The project from Change a registry with an Action, with its registry runningAn editor

Write the module

A module is a separate file of additions to a project. In the project directory, create its folder:

mkdir -p modules/contact-notes

Create modules/contact-notes/module.yaml:

apiVersion: id.registrystack.org/formats/breg/module/v1alpha1
kind: BRegModule
id: contact-notes
version: 0.1.0
extendRecordTypes:
  - recordType: contact
    fields:
      - id: internal-note
        type: text
        required: false
        maximumLength: 2000
        classification: internal

Add the module to registry.yaml, before datasets:

datasets:
modules:
  - id: contact-notes
    version: 0.1.0

datasets:

Let the editor read and write the note

A new field is hidden from every caller until an access profile names it. Add it to the editor’s fields:

readableFields: [name, email, jurisdiction]
writableFields: [name, email, jurisdiction]
readableFields: [name, email, jurisdiction, internal-note]
writableFields: [name, email, jurisdiction, internal-note]

Who may read a contact is unchanged.

Pin the module and check

bregctl project lock .

Locked the project modules. 1 artifact written.
  revision  sha256:<digest>

  registry.yaml

{
  "changed": true,
  "modules": [
    {
      "digest": "sha256:<digest>",
      "id": "contact-notes",
      "status": "updated",
      "version": "0.1.0"
    }
  ]
}

The lock writes the digest of the module’s exact bytes into registry.yaml. If the module file changes later, the check fails until you lock again.

bregctl check . --production

Production check passed; registry revision sha256:<digest>.
0 errors, 0 warnings in 4 files

Generate the contact schema

bregctl generate schemas . --output ../contact-schemas

Generated 9 artifacts.
  revision  sha256:<digest>

  generated/action-schemas/register-contact.invoke.input.schema.json
  generated/action-schemas/register-contact.invoke.response.schema.json
  generated/action-schemas/update-contact-email.availability.input.schema.json
  generated/action-schemas/update-contact-email.availability.response.schema.json
  generated/action-schemas/update-contact-email.invoke.input.schema.json
  generated/action-schemas/update-contact-email.invoke.response.schema.json
  generated/action-schemas/update-contact-email.target-conditions.input.schema.json
  generated/action-schemas/update-contact-email.target-conditions.response.schema.json
  generated/schemas/contact.schema.json

These JSON Schemas describe what the API accepts and returns. In ../contact-schemas/generated/schemas/contact.schema.json, the note appears as internalNote: a string of at most 2000 characters, or null, and not in the required list.

{
  "internalNote": {
    "anyOf": [
      {
        "maxLength": 2000,
        "type": "string"
      },
      {
        "type": "null"
      }
    ]
  }
}

Stop the registry

The running registry was built from the project as it was, and its test data was written for that version. Stop it and discard that data:

bregctl dev stop --remove

bregctl dev succeeded.
  status          stopped

Keep the project: the next bregctl dev start in this directory runs it with the note.

Send registry events to a webhook