This page was generated by bootstrap-tools —
scripts/subgraph-readmes.ts, from theschemasentry ofbootstrap.jsonand the files in this directory. Do not edit it here; change that entry or the files, and regenerate.
The schemas bootstrap is checked against: graph.schema.json, the shape of a declaration and the definition of every term bootstrap uses; and the input and output of the discussion Process. Their published $ids do not change when a file moves.
Part of Bootstrap 0.1.0, declared as schemas, holding schemas.
| file | what it is | used by |
|---|---|---|
discussion.input.schema.json | Discussion Input | |
discussion.output.schema.json | Discussion Output | |
graph.schema.json | Knowledge Graph declaration | |
model-registry.schema.json | Model Registry | |
requirement-set.schema.json | Requirement Set | |
requirement.schema.json | Requirement |
This section was generated by bootstrap-tools —
scripts/gen-bootstrap-schemas.ts, from the schemas in this directory. Do not edit it here; change a schema.
Every JSON file bootstrap defines has a schema in this directory. This page draws each one, so you can read it without reading JSON Schema.
How to read a drawing:
* marks a field that must be present.[1] means exactly one, [0..1] means optional, [1..*] means a list
with at least one item, and [0..*] means a list that may be empty.[src] opens the schema itself.Each defined term, in the words of
graph.schema.json, in order: each definition uses only terms
above it, and never itself. Uses lists them. Defined by is the
schema that defines the term: src is its entry in this directory, anything
else is the published standard bootstrap builds on. A term whose shape is
drawn below links to its drawing.
| # | Term | Definition | Uses | Defined by |
|---|---|---|---|---|
| 1 | Node | One file, or one part of a file addressable by an IRI fragment, named by an IRI. | — | JSON-LD 1.1 node object |
| 2 | Reference | A Node's naming of another Node by its IRI. | Node | IRI (RFC 3987) |
| 3 | Node Schema | A schema a Node can be checked against: a JSON Schema, or a published external schema such as BPMN's. | Node | JSON Schema draft-07 |
| 4 | Node Kind | A name paired with a Node Schema. | Node Schema | src |
| 5 | Subkind | A Node Kind whose Node Schema requires everything another Node Kind's does, so every Node that satisfies it satisfies the other too. | Node Kind, Node Schema, Node | src |
| 6 | Node Instance | A Node that names its Node Kind, in $schema or front matter, and satisfies that kind's Node Schema. | Node, Node Kind, Node Schema | src |
| 7 | Graph Typology | A named set of Node Kinds. | Node Kind | src |
| 8 | Declaration | A JSON document, <name>.json, that gives a name and lists directory entries and file entries. | — | src |
| 9 | Extension | A field of a Declaration, or of one of its entries, that is not defined here. A reader that does not recognise the field ignores it, and the rest of the Declaration keeps its meaning. | Declaration | src |
| 10 | Subgraph | A directory entry of a Declaration: an id, a directory, and the Graph Typologies its Node Instances' kinds belong to. Drawn in Knowledge Graph declaration. | Declaration, Graph Typology, Node Instance | src |
| 11 | Asset | A file entry of a Declaration: one file about the repository itself, whose role field says what it is for. Drawn in Knowledge Graph declaration. | Declaration | src |
| 12 | Knowledge Graph | The Node Schemas, Node Instances and Assets one Declaration lists, as of one version of the repository. Published as JSON-LD, the statements of each Subgraph's Node Instances form one named graph. Drawn in Knowledge Graph declaration. | Node Schema, Node Instance, Asset, Declaration, Subgraph | src |
| 13 | Dependency | A Declaration's needs entry naming another Knowledge Graph. References may point from this graph's Node Instances into the named one, never back. | Declaration, Knowledge Graph, Reference, Node Instance | src |
| 14 | Content | Node Instances that describe the subject matter of a Knowledge Graph, such as records, documents, catalogues and their terms, rather than how to work with it. | Node Instance, Knowledge Graph | src |
| 15 | Task | A unit of work, stated by what it needs to begin and what it produces. | — | BPMN 2.0 task |
| 16 | Actor | A person, an agent or a program that can carry out Tasks. | Task | PROV-O Agent |
| 17 | Skill | A Node Instance stating a responsibility an Actor carries out to complete a Task: as natural-language instructions to follow, as a contract to be tested against, or both. | Node Instance, Actor, Task | src |
| 18 | Role | A Node Instance naming a part an Actor takes on to carry out Tasks, and listing the Skills that part needs. | Node Instance, Actor, Task, Skill | src |
| 19 | Process Node | A BPMN flow node: an activity (a task or call activity), a gateway, or an event. | — | BPMN 2.0 flowNode |
| 20 | Sequence Flow | A directed connection in a BPMN process from one Process Node to the next. | Process Node | BPMN 2.0 sequenceFlow |
| 21 | Process | A Node Instance holding a BPMN process that coordinates Tasks: its Process Nodes, joined by Sequence Flows, sit in lanes that each name a Role. | Node Instance, Task, Process Node, Sequence Flow, Role | BPMN 2.0 process |
| 22 | Harness | A Knowledge Graph whose Subgraphs hold Skills, Roles or Processes: what an Actor uses to work with a Knowledge Graph, including itself. | Knowledge Graph, Subgraph, Skill, Role, Process, Actor | src |
The occasion for asking: what the agent already knows, and which unknown is still open. Deliberately small — a Bootstrapping Agent has read one README and can look nothing up, so an input it cannot populate is an input that stops the process.
+-----------------------------------------------------------------+
| Discussion Input |
+-----------------------------------------------------------------+
| * open [1..*] list of "harness" | "repositories" |
| * askedOf [1] Asked Of |
| candidates [0..*] list of string |
| knownRepositories [0..*] Known Repository list |
| context [0..1] string |
+-----------------------------------------------------------------+
|
+-- askedOf --> +------------------------------------+
| | Asked Of |
| +------------------------------------+
| | * kind [1] "person" | "agent" |
| | id [0..1] string |
| +------------------------------------+
|
+-- knownRepositories (each item) --> +--------------------------------------------+
| Known Repository |
+--------------------------------------------+
| * url [1] string |
| * role [1] "read-from" | "written-to" |
| note [0..1] string |
+--------------------------------------------+
What the exchange determined: which harness, which repositories, on whose word, and by what means. This document existing and conforming is what finishes the task — not that a conversation took place.
+------------------------------------------------------------+
| Discussion Output |
+------------------------------------------------------------+
| * outcome [1] "settled" | "unsettled" |
| harness [0..1] string |
| repositories [0..*] Repository list |
| determinedBy [0..1] "asked" | "assumed" |
| assumption [0..1] string |
| * answeredBy [1] Answered By |
| * exchange [1..*] Exchange list |
| stillOpen [0..*] list of "harness" | "repositories" |
+------------------------------------------------------------+
|
+-- repositories (each item) --> +--------------------------------------------+
| | Repository |
| +--------------------------------------------+
| | * url [1] string |
| | * role [1] "read-from" | "written-to" |
| | note [0..1] string |
| +--------------------------------------------+
|
+-- answeredBy --> +------------------------------------+
| | Answered By |
| +------------------------------------+
| | * kind [1] "person" | "agent" |
| | id [0..1] string |
| +------------------------------------+
|
+-- exchange (each item) --> +----------------------------+
| Exchange |
+----------------------------+
| * asked [1] string |
| answered [0..1] string |
| at [0..1] string |
+----------------------------+
Rules the drawing cannot show:
determinedBy is "assumed", assumption must be present.outcome is "unsettled", stillOpen must be present.src · describes <name>.json
A Declaration. Any field not listed here is an Extension: A field of a Declaration, or of one of its entries, that is not defined here. A reader that does not recognise the field ignores it, and the rest of the Declaration keeps its meaning.
+---------------------------------------------+
| Knowledge Graph declaration |
+---------------------------------------------+
| * name [1] string |
| version [0..1] string |
| iriBase [0..1] string |
| title [0..1] string |
| description [0..1] string |
| directories [0..*] Subgraph list |
| needs [0..*] list of string |
| nodeSchemas [0..1] map of key to string |
| assets [0..*] Asset list |
+---------------------------------------------+
|
+-- directories (each item) --> +-------------------------------------------------------------------------------------------------------------------+
| | Subgraph |
| +-------------------------------------------------------------------------------------------------------------------+
| | * id [1] string |
| | * path [1] string |
| | * graphTypologies [1..*] list of = "skills" | = "schemas" | = "scenarios" | = "processes" | = "models" | string |
| | title [0..1] string |
| | description [0..1] string |
| +-------------------------------------------------------------------------------------------------------------------+
|
+-- assets (each item) --> +---------------------+
| Asset |
+---------------------+
| * id [1] string |
| * src [1] string |
| * role [1] string |
+---------------------+
src · describes models/models.json
Which languages a model is good at, and whether a person checked. Only human-validated is ever acted on, and only a person can grant it.
+---------------------------------------------+
| Model Registry |
+---------------------------------------------+
| * $schema [1] = "model-registry/1.0.0" |
| * models [0..*] Model list |
+---------------------------------------------+
|
+-- models (each item) --> +----------------------------------------------------------------------------------+
| Model |
+----------------------------------------------------------------------------------+
| * id [1] string |
| * title [1] string |
| preferredLanguages [0..*] list of string |
| * validation [1] "unverified" | "self-reported" | "human-validated" |
| validatedBy [0..1] string |
| validatedOn [0..1] string |
| note [0..1] string |
+----------------------------------------------------------------------------------+
What a harness, or something built with one, must do, said so it can be checked: a titled set of numbered statements, each with a level (SHALL, SHOULD, MAY, SHALL NOT), one sentence, and — optional for now, required once existing statements are migrated — at least one success criterion saying how it is judged met (test, inspection, review or analysis). A test run points at a statement as req:<slug>#<key>, or at one criterion as req:<slug>#<key>/<criterion>; the requirement does not list its tests. Statement keys are unique within a requirement, criterion keys within a statement.
+----------------------------------------------------------------------------+
| Requirement |
+----------------------------------------------------------------------------+
| * id [1] string |
| * title [1] string |
| * description [1] string |
| status [0..1] "proposed" | "in-force" | "superseded" | "retired" |
| derivedFrom [0..*] list of string |
| * actors [0..*] list of string |
| * statements [1..*] Statement list |
| tags [0..*] list of string |
| proposedIn [0..1] string |
| supersededBy [0..1] string |
+----------------------------------------------------------------------------+
|
+-- statements (each item) --> +---------------------------------------------------------------------+
| Statement |
+---------------------------------------------------------------------+
| * key [1] string |
| * label [1] string |
| * conformance [1] "SHALL" | "SHOULD" | "MAY" | "SHALL NOT" |
| * requirement [1] string |
| kind [0..1] "functional" | "non-functional" |
| activity [0..1] string |
| capability [0..1] string |
| benefit [0..1] string |
| category [0..1] string |
| actors [0..*] list of string |
| dependsOn [0..*] list of string |
| successCriteria [0..*] Success Criteria list |
+---------------------------------------------------------------------+
|
+-- successCriteria (each item) --> +--------------------------------------------------------------------+
| Success Criteria |
+--------------------------------------------------------------------+
| * key [1] string |
| * criterion [1] string |
| * verification [1] "test" | "inspection" | "review" | "analysis" |
+--------------------------------------------------------------------+
Rules the drawing cannot show:
status is "superseded", supersededBy must be present.statements: if kind is "functional", category must be absent.statements: if kind is "non-functional", activity, capability and benefit must be absent.A requirements document: a set of requirement statements (by req: reference, each with its own decision) at one stage of its life — draft, proposed, approved, planned, in-progress, delivered, accepted, or rejected, cancelled, superseded — with its work plan and the sign-offs that moved it there. A sign-off is a recorded decision: who (kind, id, actor), when, about what, the outcome (approve, amend, reject, defer, cancel), the stage it moves the set to, why, and a link to where it was made. approved and accepted need a human sign-off; from planned on, the set names its work plan; cancelled needs a reason. The set's stage and each member's own status are independent.
+------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Requirement Set |
+------------------------------------------------------------------------------------------------------------------------------------------------------------+
| * id [1] string |
| * title [1] string |
| * methodology [1] string |
| issue [0..1] string |
| * stage [1] "draft" | "proposed" | "approved" | "planned" | "in-progress" | "delivered" | "accepted" | "rejected" | "cancelled" | "superseded" |
| * members [1..*] Member list |
| workPlan [0..*] list of string |
| signOffs [0..*] Sign Off list |
| document [0..1] string |
| supersededBy [0..1] string |
+------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
+-- members (each item) --> +----------------------------------------------------------------------+
| | Member |
| +----------------------------------------------------------------------+
| | * ref [1] string |
| | decision [0..1] "approved" | "amended" | "rejected" | "deferred" |
| +----------------------------------------------------------------------+
|
+-- signOffs (each item) --> +--------------------------------------------------------------------------------------------------------------------------------------------------------+
| Sign Off |
+--------------------------------------------------------------------------------------------------------------------------------------------------------+
| * kind [1] "script" | "agent" | "human" |
| * id [1] string |
| actor [0..1] string |
| * at [1] string |
| * scope [1] string |
| * outcome [1] "approve" | "amend" | "reject" | "defer" | "cancel" |
| stage [0..1] "draft" | "proposed" | "approved" | "planned" | "in-progress" | "delivered" | "accepted" | "rejected" | "cancelled" | "superseded" |
| reason [0..1] string |
| * evidence [1] string |
+--------------------------------------------------------------------------------------------------------------------------------------------------------+
Rules the drawing cannot show:
stage is "superseded", supersededBy must be present.stage is one of "planned", "in-progress", "delivered", "accepted", workPlan must be present — workPlan with at least 1 item(s).stage is "approved", signOffs must be present — signOffs including one item with stage "approved", outcome one of "approve", "amend", kind "human".stage is "accepted", signOffs must be present — signOffs including one item with stage "accepted", outcome one of "approve", kind "human".stage is "rejected", signOffs must be present — signOffs including one item with stage "rejected", outcome one of "reject".stage is "cancelled", signOffs must be present — signOffs including one item with stage "cancelled", outcome one of "cancel", a reason.