PublicSchema wizard prompts
bregctl init <DEST> --from publicschema, given neither --starter nor --selection, asks nine
questions at a terminal. Your answers become the same BRegModelSelection document a starter ships
or --selection reads, and the derivation treats all three alike.
The questions need standard input and standard error to be terminals. Prompts go to standard error; standard output carries only the final report. The selection is resolved before the review, so a refusal comes before you confirm, and nothing is written until you do. The wording is pre-1.0 tooling text and can change.
Registry identifier
Section titled “Registry identifier”Registry identifier, with the help line lowercase letters, digits, and hyphens; it names the registry in its IRIs, scopes, and the catalogue. There is no default.
An answer must be 1 to 64 characters, start with a lowercase letter, and use only a-z, 0-9, -,
and _. The project appends -authority, -api, -service, -operator, and -reader to name
what it derives, and each result must fit too, so the identifier can be at most 54 characters.
Registry title
Section titled “Registry title”Registry title, with the help line the name a reader sees; enter to keep the default. The default
is the identifier read back in words: household-registry offers Household Registry. An empty
title is refused.
Which concepts become entities?
Section titled “Which concepts become entities?”A multi-select with the help line space to toggle, type to filter, enter to confirm. Each chosen
concept becomes a Record type. Choose at least one; nothing starts ticked.
The list holds every concept that is not abstract and has a property the derivation can keep, by
schema file, then name. An option shows the label, schema file, and first sentence of the
description cut to 60 characters: Person (publicschema-identity): The unique individual human being who is a subject of record….
Which concepts connect what you chose?
Section titled “Which concepts connect what you chose?”A multi-select with the help line space to toggle, type to filter, enter to confirm; enter alone adds none. Nothing starts ticked, and none is a legitimate answer.
It lists the unchosen concepts with at least two single-valued properties pointing at your choices,
reaching two of them when you chose several: Group Membership (publicschema-misc): group is a Household, person is a Person. Concepts whose every link fits one chosen concept come first.
The prompt is skipped when no concept qualifies. When some of two or more chosen concepts have nothing to connect them, one line naming them is printed first.
Which properties of <Title> become fields?
Section titled “Which properties of <Title> become fields?”One multi-select per chosen concept, connectors last, with the help line space to toggle, type to filter, enter to confirm. Choose at least one property.
An option names the property, the shape its field takes, sensitive or restricted where the
model rates it so, and how many tracked systems record it: date_of_birth: date (6 of 6 systems).
It starts ticked when the model requires it, when at least 60% of those systems record it, or when
it is a single-valued reference to a chosen concept.
Properties the derivation cannot carry are not offered. One line before the prompt, opening Not offered for <Title>:, names each with the derivation’s reason.
How a property becomes a field
Section titled “How a property becomes a field”A property becomes a field of the same name in kebab case, prefixed declared- when it would shadow
a system column such as id or revision. No derived field is required. Each Record type also
gains a required, unique identifier field of 1 to 64 characters.
| The prompt shows | Field |
|---|---|
text | string, at most 255 characters |
URI | string, at most 2048 characters |
whole number | int64 |
decimal number | decimal, precision 18, scale 6 |
date | date |
date and time | timestamp |
yes or no | boolean |
reference | reference to the chosen Record type |
code from a code list | vocabulary-code when the list is kept in full, otherwise string sized to the longest code, 64 to 128 characters |
The remaining shapes become structured fields:
| The prompt shows | Holds | Bounds |
|---|---|---|
structured value carried inline | An unchosen concept’s scalar and enumerated properties | 16384 bytes |
structured value | A GeoJSON geometry | 65536 bytes |
list of a scalar or code | { "values": [...] } | 50 items, 4096 bytes |
list of structured values carried inline | { "values": [...] } of flat objects of an inline_only: true class, required members kept | 50 items, 16384 bytes |
Every structured schema is closed. A property rated sensitive or restricted becomes a restricted
field, a structured field takes the highest rating it carries, and every other field is internal.
The wizard leaves every Record type internal.
Which entity does <Concept>.<property> point at?
Section titled “Which entity does <Concept>.<property> point at?”A single select with the help line type to filter, arrows to move, enter to select, listing the
default identifiers of the chosen concepts that fit, in the order chosen.
It is asked only where several chosen concepts fit a single-valued reference, after every concept’s properties are settled, because a property may point at a concept chosen later.
Keep the default identifiers and routes?
Section titled “Keep the default identifiers and routes?”A yes-or-no question defaulting to yes, with the help line they name the collection routes, the record identifiers, and the fields a client reads. One line per Record type precedes it: person: route persons, identifier field person-code.
No asks three questions per Record type, each with the help line enter to keep the default:
| Question | Default |
|---|---|
Entity identifier for <Concept> | The concept in kebab case |
Collection route for <Concept> | The plural of that identifier |
Identifier field for <Concept> | That identifier with -code appended |
Each answer is held to the identifier grammar. An identifier or route an earlier Record type already
carries is refused with `<value>` is already taken by another entity. A default answer is left
out of the written selection.
Which code lists should the project list in full?
Section titled “Which code lists should the project list in full?”A multi-select with the help line space to toggle, enter to confirm; an unticked list is carried as a bounded code instead, listing each enumeration a chosen property draws on: Marital Status (6 values). It is skipped when there is none.
An enumeration of at most 300 values starts ticked, the derivation’s own default. Only an answer
that differs is written into the selection’s vocabularies list. Ticking one of more than 1024
values is refused.
Derive the project from this selection?
Section titled “Derive the project from this selection?”The selection is printed as YAML, then one line naming any Record type no field connects to another,
then a yes-or-no question defaulting to yes, with the help line the document above is written into the project beside what it derives. No writes nothing and reports init.selection.cancelled.
What the derivation refuses
Section titled “What the derivation refuses”These properties are withheld from the property question, and refused in a selection file:
- Many values of a concept whose class is not marked
inline_only: true. Model the relationship as its own Record type with a reference back. - An
inline_onlyclass that a chosen concept fits or atargetnames. - An
inline_onlyclass that is abstract, has concrete descendants, carries an identifier, or has a member that is not a scalar or enumeration. Author that field in the derived project instead. - One value of an unchosen concept with no scalar property to carry. Choose that concept.
- A value type with no field type.
A selection file is also refused when it repeats or misnames a concept, property, identifier,
route, field, target, classification, or enumeration, or was written against another snapshot
version or revision. Each refusal
names the entry it concerns.
Cancelling, and running without a terminal
Section titled “Cancelling, and running without a terminal”| Situation | Report |
|---|---|
Esc or Ctrl+C at any prompt, or no at the review | init.selection.cancelled: cancelled at a prompt; nothing was written |
| A prompt cannot be raised for any other reason | init.selection.prompt: a question could not be asked, followed by the library’s own message |
| No terminal on standard input or standard error | init.selection.missing: `init --from publicschema` asks its questions at a terminal; without one, pass `--selection <FILE>` or `--starter <NAME>` (one of `household`) |
Nothing is written in any of the three cases. Pass --starter or --selection to derive without a
terminal.
- Derive a registry from PublicSchema to run the same derivation from a shipped starter.
- Author a registry project to change what the derivation wrote.
- Base Registry Engine configuration reference for the keys of the written
project and
model/selection.yaml.