Element file frontmatter

YAML frontmatter of an element file (D-015, D-056). The Markdown text follows the closing ---. Only id, type and status are structural (status only for a type with statuses, #306); every other key is a property or relation kind key from the metamodel (D-043). Keys the metamodel does not know are kept unchanged and reported as hints (D-012, SR-016). See docs/adr/0004-element-file-format.md. File name: type prefix, dash, last 12 hex characters of the UUID, never changed (D-056). Value kinds are checked against the metamodel, not by this schema, so any value of an unknown key is kept (SR-016); $defs/value describes the values ReqSeq writes.

Fields

Field	Type	Required	Description
id	uuid	yes	Element ID: random UUID version 4, lower case, never changes (D-017, SR-002).
type	key	yes	Type key from the metamodel.
status	key	no	Status key from the metamodel, one of the statuses of the element’s type (#306). Left out for a type without status. Only ever set by a person (D-030, SR-017).
normal-form	any	no	Reserved. Never written; the normal-form version is part of every stored version string (D-027).

Definitions

scalar

Type: string or number or boolean.

inputValue

Property value as a caller gives it to element.create, element.update or element.bulkUpdate: like value, but relation targets need only id (and repository across repositories); the tool sets their version (SR-021). For a property of kind relation every item is an element reference: a string or { id }, with a UUID, short ID or identifier (#169, #196, #287).

Type: scalar or null or array of scalar or relationTargetInput or array of relationTargetInput.

value

Property value (text, number, date as YYYY-MM-DD, choice key, list) or relation targets. Which one is expected comes from the metamodel; a mismatch is a hint, not a parse error (SR-012 AK3).

Type: scalar or null or array of scalar or relationTarget or array of relationTarget.

Examples

N-42cdd0f51ca7.md

---
id: 878e339e-1f73-4746-abab-42cdd0f51ca7
type: need
status: approved
title: Wind speed visible at a glance
rationale: Users decide within seconds whether to go sailing.
---

As a sailor I need to see the current wind speed at a glance, from a distance of three metres.

SR-25696a7b5503.md

---
id: 323df4d5-8491-4f94-b18d-25696a7b5503
type: system-requirement
status: draft
title: Show wind speed in large digits and as a gauge
requirement-type: functional
acceptance-criteria:
  - Given the Pro variant, when wind is measured, then the display shows digits and a round gauge.
validity:
  - { id: ca0dd4a9-1365-45ce-8110-d62071160b58, version: n1:2c26b46b68ffc68f, title: Pro }
replaces:
  - { id: 102ee39b-773f-4cd0-b414-825b7146fb54, version: n1:fcde2b2edba56bf4, title: Show wind speed in large digits }
---

The Pro display shows the wind speed in digits and on a round gauge.

SR-825b7146fb54.md

---
id: 102ee39b-773f-4cd0-b414-825b7146fb54
type: system-requirement
status: draft
title: Show wind speed in large digits
requirement-type: functional
acceptance-criteria:
  - Given the station is running, when wind is measured, then the display shows the speed in digits at least 30 mm high.
  - Given no measurement for 10 s, when the display refreshes, then it shows "--".
packages:
  - { id: 19fd3f5e-9caf-4c94-9e30-c4eb8a40324a, version: n1:4be0643f1d98573b, title: Release 1.0 }
derives-from:
  - { id: 878e339e-1f73-4746-abab-42cdd0f51ca7, version: n1:7d865e959b2466f0, title: Wind speed visible at a glance }
  - { id: fe5fce30-087e-4bbd-82e4-0f03900e5af3, version: n1:e3b0c44298fc1c14, repository: subsystem-sensor }
customer-id: WS-0815
---

The display shows the wind speed in large digits, readable from three metres.

Unit and rounding follow [Wind speed visible at a glance](reqseq:878e339e-1f73-4746-abab-42cdd0f51ca7?version=n1:7d865e959b2466f0).

![Layout](SR-825b7146fb54/layout.png)