Step
PartDraftv1.0.0-rc.2
A step: one unit of work in a flow, such as a calculation, a question, a decision or a run of an algorithm. A sealed step names its inputs, its outputs and the algorithm it claims to follow, but not how it works.
https://opendevelopmentstandards.org/schema/1.0.0-rc.2/core/Step.json
Fields
idtextnot emptyThe record's id: unique within the document.
nametextThe name people use for the record.
descriptiontextWhat the record is, in words.
citationThe published work that the step follows, such as the section of a framework.
typeRequiredOne ofthe codes belowWhat the step does.
entrypoint- Where the flow starts.
question- Asks a person for an input.
group- Questions shown together; `repeat` can run it once for each item of a list.
repeatable- Questions a person can answer several times, one set of answers for each entry.
context- Adds data to the flow's context without a person, usually after a decision.
calculation- Works out its `expression`.
algorithm- Runs its `algorithm`.
model- Asks a machine-learning model or an agent.
decision- Chooses the next step; the flow's edges hold the choices.
control- Records a certification, an attestation or data that a control needs.
flow- Runs another flow, which `flow` names.
outcome- States an outcome of the flow.
custom- Any other step.
labeltextThe text a person sees for the step.
parentThe group step this step belongs to.
expressionFor a calculation: what it works out.
algorithmFor an algorithm step, and for any sealed step: the algorithm it runs or claims to follow.
flowFor a flow step: the flow it runs.
controlFor a control step: the control it records.
criterionFor a decision: the criterion it judges.
questioninputsList ofParameterWhat the step reads.
outputsList ofParameterWhat the step writes.
repeatprioritynumberIts order among steps that could run together: higher first.
sealedtrue or falseTrue when the step runs a closed engine. Its trace keeps its inputs and outputs; only the publisher can run it again.
- When
sealedistrue, it needsalgorithm,inputsandoutputs.
Parameter
One input or output of a step.
nameRequiredtextmatches ^[a-z][a-z0-9_]*$The name expressions use for it.
descriptiontextWhat it holds, in words.
quantityCode fromcore/quantities or acoustics/quantitiesWhat it measures, as a code from a quantities vocabulary.
unitIts unit.
valueTypeOne ofthe codes belowWhat sort of amount it holds.
number- A number.
string- Text.
boolean- True or false.
list- A list.
object- An object.
Question
For a question: what it asks for.
answerTypeRequiredOne ofthe codes belowWhat sort of answer it takes.
text- Free text.
number- A number.
boolean- Yes or no.
choice- One of `options`.
choices- Any of `options`.
date- A date.
date_time- A date and a time.
location- A point on a map.
file- A file, such as a photo.
signature- A signature.
unitThe unit of a number answer.
optionsList ofobject, fields belowThe answers a person can pick.
valueRequirednumberortextortrue or falseWhat the answer stores.
labeltextWhat a person sees.
requiredtrue or falseTrue when the question must be answered.
Repeat
Runs the step once for each item of a list.
overRequiredThe list to go through.
asRequiredtextmatches ^[a-z][a-z0-9_]*$The name each item has inside the step.
Links
Points at Records whose ids this record holds, with the field that holds each.
- AlgorithmEntityalgorithmA published or versioned computation, such as ISO 9613-2:2024, or a model trained on data. Sealed steps and runs refer to it by id, as the method they claim to follow.
- FlowEntityflowThe steps of an evaluation and the edges between them. A flow can run another flow as one of its steps.
- ControlPartcontrolA check on how an evaluation is done, which a framework sets, such as "a person approves each decision" or "measurements use a Class 1 meter". A mitigation is not a control: a barrier is a Structure, and a site's own limit is a criterion of its Permit.
- CriterionPartcriterionOne rule that must be checked. It compares a metric, summed up by a statistic over a period, with a limit, for the features it applies to.
Held by Records that embed this one, with their field that holds it.
Pointed at by Records that hold this one's id, with their field that holds it.
- EdgePartfromtoA link from one step of a flow to the next. Its
whensays when the flow takes it. - TraceEntityTraceStep.stepWhat one run of a flow or an algorithm did: what it used, each step, what it made, and the verdict. Its terms follow W3C PROV where they map: agents (prov:wasAssociatedWith), inputs (prov:used), outputs (prov:generated).
Examples
An id that another example defines opens that record.
Example 2
{
"id": "step-propagation",
"type": "algorithm",
"name": "Sound levels at receptors",
"algorithm": "algorithm-iso9613",
"sealed": true,
"inputs": [
{
"name": "sources",
"valueType": "list"
},
{
"name": "receptors",
"valueType": "list"
}
],
"outputs": [
{
"name": "receptor_levels",
"quantity": "a_weighted_sound_pressure_level",
"unit": "dB",
"valueType": "list"
}
]
}Show 2 more examplesHide the other examples
Example 1
{
"id": "step-1",
"type": "entrypoint"
}Example 3
{
"id": "step-ask-hours",
"type": "question",
"label": "How many hours a day does the compressor run?",
"question": {
"answerType": "number",
"unit": "h"
},
"outputs": [
{
"name": "hours_per_day",
"unit": "h",
"valueType": "number"
}
]
}Changes and file
Changes
- 0.1.0 First version.
Schema file
Show the JSON SchemaHide the JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://opendevelopmentstandards.org/schema/1.0.0-rc.2/core/Step.json",
"title": "Step",
"description": "A step: one unit of work in a flow, such as a calculation, a question, a decision or a run of an algorithm. A sealed step names its inputs, its outputs and the algorithm it claims to follow, but not how it works.",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"description": "The record's id: unique within the document."
},
"name": {
"type": "string",
"description": "The name people use for the record."
},
"description": {
"type": "string",
"description": "What the record is, in words."
},
"citation": {
"$ref": "Citation.json",
"description": "The published work that the step follows, such as the section of a framework."
},
"type": {
"type": "string",
"enum": [
"entrypoint",
"question",
"group",
"repeatable",
"context",
"calculation",
"algorithm",
"model",
"decision",
"control",
"flow",
"outcome",
"custom"
],
"description": "What the step does.",
"x-ods-options": [
{
"value": "entrypoint",
"title": "Entry point",
"description": "Where the flow starts."
},
{
"value": "question",
"title": "Question",
"description": "Asks a person for an input."
},
{
"value": "group",
"title": "Group",
"description": "Questions shown together; `repeat` can run it once for each item of a list."
},
{
"value": "repeatable",
"title": "Repeatable",
"description": "Questions a person can answer several times, one set of answers for each entry."
},
{
"value": "context",
"title": "Context",
"description": "Adds data to the flow's context without a person, usually after a decision."
},
{
"value": "calculation",
"title": "Calculation",
"description": "Works out its `expression`."
},
{
"value": "algorithm",
"title": "Algorithm",
"description": "Runs its `algorithm`."
},
{
"value": "model",
"title": "Model",
"description": "Asks a machine-learning model or an agent."
},
{
"value": "decision",
"title": "Decision",
"description": "Chooses the next step; the flow's edges hold the choices."
},
{
"value": "control",
"title": "Control",
"description": "Records a certification, an attestation or data that a control needs."
},
{
"value": "flow",
"title": "Flow",
"description": "Runs another flow, which `flow` names."
},
{
"value": "outcome",
"title": "Outcome",
"description": "States an outcome of the flow."
},
{
"value": "custom",
"title": "Custom",
"description": "Any other step."
}
]
},
"label": {
"type": "string",
"description": "The text a person sees for the step."
},
"parent": {
"type": "string",
"minLength": 1,
"x-ods-ref": "Step",
"description": "The group step this step belongs to."
},
"expression": {
"$ref": "Expression.json",
"description": "For a calculation: what it works out."
},
"algorithm": {
"type": "string",
"minLength": 1,
"x-ods-ref": "Algorithm",
"description": "For an algorithm step, and for any sealed step: the algorithm it runs or claims to follow."
},
"flow": {
"type": "string",
"minLength": 1,
"x-ods-ref": "Flow",
"description": "For a flow step: the flow it runs."
},
"control": {
"type": "string",
"minLength": 1,
"x-ods-ref": "Control",
"description": "For a control step: the control it records."
},
"criterion": {
"type": "string",
"minLength": 1,
"x-ods-ref": "Criterion",
"description": "For a decision: the criterion it judges."
},
"question": {
"$ref": "#/$defs/Question"
},
"inputs": {
"type": "array",
"items": {
"$ref": "#/$defs/Parameter"
},
"description": "What the step reads."
},
"outputs": {
"type": "array",
"items": {
"$ref": "#/$defs/Parameter"
},
"description": "What the step writes."
},
"repeat": {
"$ref": "#/$defs/Repeat"
},
"priority": {
"type": "number",
"description": "Its order among steps that could run together: higher first."
},
"sealed": {
"type": "boolean",
"description": "True when the step runs a closed engine. Its trace keeps its inputs and outputs; only the publisher can run it again."
}
},
"required": [
"type"
],
"allOf": [
{
"if": {
"properties": {
"sealed": {
"const": true
}
},
"required": [
"sealed"
]
},
"then": {
"properties": {
"algorithm": true,
"inputs": true,
"outputs": true
},
"required": [
"algorithm",
"inputs",
"outputs"
]
}
}
],
"patternProperties": {
"^x-": {}
},
"unevaluatedProperties": false,
"$defs": {
"Parameter": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name expressions use for it.",
"pattern": "^[a-z][a-z0-9_]*$"
},
"description": {
"type": "string",
"description": "What it holds, in words."
},
"quantity": {
"type": "string",
"pattern": "^[a-z0-9]+(_[a-z0-9]+)*(\\.[a-z0-9]+(_[a-z0-9]+)*)*$",
"x-ods-vocabulary": "*/quantities",
"description": "What it measures, as a code from a quantities vocabulary."
},
"unit": {
"type": "string",
"x-ods-vocabulary": "*/units",
"description": "Its unit."
},
"valueType": {
"type": "string",
"enum": [
"number",
"string",
"boolean",
"list",
"object"
],
"description": "What sort of amount it holds.",
"x-ods-options": [
{
"value": "number",
"title": "Number",
"description": "A number."
},
{
"value": "string",
"title": "Text",
"description": "Text."
},
{
"value": "boolean",
"title": "True or false",
"description": "True or false."
},
{
"value": "list",
"title": "List",
"description": "A list."
},
{
"value": "object",
"title": "Object",
"description": "An object."
}
]
}
},
"required": [
"name"
],
"description": "One input or output of a step.",
"patternProperties": {
"^x-": {}
},
"unevaluatedProperties": false
},
"Question": {
"type": "object",
"properties": {
"answerType": {
"type": "string",
"enum": [
"text",
"number",
"boolean",
"choice",
"choices",
"date",
"date_time",
"location",
"file",
"signature"
],
"description": "What sort of answer it takes.",
"x-ods-options": [
{
"value": "text",
"title": "Text",
"description": "Free text."
},
{
"value": "number",
"title": "Number",
"description": "A number."
},
{
"value": "boolean",
"title": "Yes or no",
"description": "Yes or no."
},
{
"value": "choice",
"title": "Choice",
"description": "One of `options`."
},
{
"value": "choices",
"title": "Choices",
"description": "Any of `options`."
},
{
"value": "date",
"title": "Date",
"description": "A date."
},
{
"value": "date_time",
"title": "Date and time",
"description": "A date and a time."
},
{
"value": "location",
"title": "Location",
"description": "A point on a map."
},
{
"value": "file",
"title": "File",
"description": "A file, such as a photo."
},
{
"value": "signature",
"title": "Signature",
"description": "A signature."
}
]
},
"unit": {
"type": "string",
"x-ods-vocabulary": "*/units",
"description": "The unit of a number answer."
},
"options": {
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"anyOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"type": "boolean"
}
],
"description": "What the answer stores."
},
"label": {
"type": "string",
"description": "What a person sees."
}
},
"required": [
"value"
],
"patternProperties": {
"^x-": {}
},
"unevaluatedProperties": false
},
"description": "The answers a person can pick."
},
"required": {
"type": "boolean",
"description": "True when the question must be answered."
}
},
"required": [
"answerType"
],
"description": "For a question: what it asks for.",
"patternProperties": {
"^x-": {}
},
"unevaluatedProperties": false
},
"Repeat": {
"type": "object",
"properties": {
"over": {
"$ref": "Expression.json",
"description": "The list to go through."
},
"as": {
"type": "string",
"description": "The name each item has inside the step.",
"pattern": "^[a-z][a-z0-9_]*$"
}
},
"required": [
"over",
"as"
],
"description": "Runs the step once for each item of a list.",
"patternProperties": {
"^x-": {}
},
"unevaluatedProperties": false
}
},
"examples": [
{
"id": "step-1",
"type": "entrypoint"
},
{
"id": "step-propagation",
"type": "algorithm",
"name": "Sound levels at receptors",
"algorithm": "algorithm-iso9613",
"sealed": true,
"inputs": [
{
"name": "sources",
"valueType": "list"
},
{
"name": "receptors",
"valueType": "list"
}
],
"outputs": [
{
"name": "receptor_levels",
"quantity": "a_weighted_sound_pressure_level",
"unit": "dB",
"valueType": "list"
}
]
},
{
"id": "step-ask-hours",
"type": "question",
"label": "How many hours a day does the compressor run?",
"question": {
"answerType": "number",
"unit": "h"
},
"outputs": [
{
"name": "hours_per_day",
"unit": "h",
"valueType": "number"
}
]
}
],
"x-ods-status": "draft",
"x-ods-kind": "part",
"x-ods-module": "core",
"x-ods-changes": {
"0.1.0": "First version."
}
}