Metamodel file

One YAML file of the metamodel (D-021, D-056, SR-011). A metamodel is all *.yaml files in the metamodel folder named in the workspace file; their lists are merged, and every key must be unique across all files. Keys never change; names may (D-043, SR-015). Built-in meanings (D-012) are attached with meaning. A type or property meaning is assigned to at most one key, counting only the meaning a definition sets itself and would not inherit anyway; a second key is a metamodel error (SR-013, SR-014 AK3); several relation kinds may share a relation meaning, e.g. Refines and Derives from are both derivation (D-012). A type inherits the meaning of the type it extends unless it sets its own.

Fields

Field	Type	Required	Description
reqseq-metamodel	1	yes	Format version of this file.
types	array of type	no
properties	array of property	no
relations	array of relationKind	no
statuses	array of status	no

Definitions

key

Type: key.

named

Type: object.

Field	Type	Required	Description
key	key	yes
name	string	yes	Display name. English in the standard model (D-019).
description	string	no

type

Element type (SR-012 AK1, AK2).

Type: named.

Field	Type	Required	Description
key	any	no
name	any	no
description	any	no
prefix	string	yes	Prefix of the short ID, e.g. SR (D-017). UNKNOWN is reserved for elements of an unknown type and is a metamodel error (#154).
extends	key	no	Parent type; its properties and required properties are inherited, over any number of levels (SR-012 AK2). A parent that is not defined, or a cycle, is a metamodel error.
abstract	boolean	no	No elements of this type can be created; only for inheritance. Default: false.
meaning	typeMeaning	no	Built-in meaning of the type (D-012): requirement (target of verification), need (may be validated), variant (D-020), package (D-040).
properties	array of key	no	Property keys this type has, in addition to inherited ones, which come first. Each should be a defined property; an undefined key is a metamodel warning and the type is treated as not having it (#141 c).
required	array of key	no	Mandatory property keys (Pflichtfelder), in addition to inherited ones; each is also a property of the type and should be a defined property; an undefined key is a metamodel warning and the type is treated as not having it (#141 c). Empty values are allowed but give a hint (SR-064).
statuses	array of key	no	Status keys elements of this type may have, in addition to inherited ones (#306): the top-level statuses stay the vocabulary (names, invalid, initial), a type only restricts it. Left out on the type and on every ancestor: every status. Once the type or any ancestor has a list, only the listed statuses count: a type with a list below a parent without one has only its own statuses (an unrestricted parent does not add every status). An empty list on a type whose ancestors have none: the type has no status, and its element files have no status. Each should be a defined status; an undefined key is a metamodel warning and left out (when no key is left, the type has no status). A type whose statuses are all marked invalid (e.g. [retired]) has an optional status (#344): its elements without status are current, element.create gives them none, and element.supersede retires them. A status outside the list gives a hint on the element (element.status-not-allowed).

typeMeaning

Built-in meaning of the type (D-012): requirement (target of verification), need (may be validated), variant (D-020), package (D-040).

Type: one of "requirement", "need", "variant", "package".

effectiveType

A type with its inheritance resolved (SR-012), as metamodel.get returns it; never written in a file. Key, name, description, prefix and extends are as written in the type’s definition.

Type: object.

Field	Type	Required	Description
key	key	yes
name	string	yes
description	string	no
prefix	string	yes
extends	key	no
abstract	boolean	yes	Not inherited: a type is abstract only when its own definition says so.
ancestors	array of key	yes	The parent, its parent and so on, up to the root type.
properties	array of key	yes	All property keys of the type, each once: those of the root type first, then down to the type itself (the key order of new keys in element files, ADR-0004). Required keys count as properties. Keys that no property definition has are left out (#141 c).
required	array of key	yes	All required property keys, own and inherited, in the same order. Keys that no property definition has are left out (#141 c).
statuses	array of key	yes	The status keys elements of the type may have, own and inherited, in the order of the metamodel’s statuses (#306): every status when neither the type nor an ancestor has statuses; empty when the type has no status. Keys that no status definition has are left out.
meaning	typeMeaning	no	Own meaning, else the meaning of the closest ancestor that has one.

property

Property definition (SR-012 AK3).

Type: named.

Field	Type	Required	Description
key	any	no
name	any	no
description	any	no
kind	one of "text", "number", "date", "choice", "relation"	yes	Value kind (Wertart).
many	boolean	no	List of values. Default: false.
choices	array of named	no	Allowed choice keys, for kind choice.
target-types	array of key	no	Allowed target types, for kind relation: absent: every type; empty: none; a type also allows its subtypes (types that extend it, SR-086).
content	boolean	no	Part of the content and therefore of the version (D-013). Title and status are never content. Default: false.
markdown	boolean	no	Values are Markdown like the text: emphasis, code and inline references [label](reqseq:<uuid>?version=...), which are followed, checked and confirmed like those in the text (SR-127). Only for kind text, and never with the meaning title or identifier. It does not change the version of an element (ADR-0005); images in such a value are no embedded images. Default: false.
meaning	propertyMeaning	no	Built-in meaning (D-012, D-059): title; validity (list of variants, D-020); packages (D-040); emergent (emergent behaviour, N-010; a choice without many whose key yes is the mark, SR-035; otherwise a warning and nothing is marked); verification-method; statement (Stellungnahme for ReqIF, SR-058); source, source-identifier, import-date, delivery, import-version (origin of imported elements, written only by ReqIF import, SR-057; import-version is the Importfassung, D-059: the version of what the import wrote, right after the last import, kind text without many and never content); identifier (an ID from another source, such as the spec ID SR-036 or a customer ID, D-017; unique per type; element references accept it besides the UUID and short ID, and outputs show it next to the short ID, #305). A property with the meaning identifier is of kind text without many.

propertyMeaning

Built-in meaning (D-012, D-059): title; validity (list of variants, D-020); packages (D-040); emergent (emergent behaviour, N-010; a choice without many whose key yes is the mark, SR-035; otherwise a warning and nothing is marked); verification-method; statement (Stellungnahme for ReqIF, SR-058); source, source-identifier, import-date, delivery, import-version (origin of imported elements, written only by ReqIF import, SR-057; import-version is the Importfassung, D-059: the version of what the import wrote, right after the last import, kind text without many and never content); identifier (an ID from another source, such as the spec ID SR-036 or a customer ID, D-017; unique per type; element references accept it besides the UUID and short ID, and outputs show it next to the short ID, #305). A property with the meaning identifier is of kind text without many.

Type: one of "title", "validity", "packages", "emergent", "verification-method", "statement", "source", "source-identifier", "import-date", "delivery", "import-version", "identifier".

relationKind

Relation kind (Beziehungsart). Stored under its key in the source file. source-types/target-types restrict where it may be set (SR-012 AK4, SR-067).

Type: named.

Field	Type	Required	Description
key	any	no
name	any	no
description	any	no
inverse-name	string	no	Name shown at the target, e.g. Derived by.
source-types	array of key	no	Allowed source types: absent: every type; empty: none; a type also allows its subtypes (types that extend it, SR-086).
target-types	array of key	no	Allowed target types: absent: every type; empty: none; a type also allows its subtypes (types that extend it, SR-086).
meaning	relationMeaning	no	Built-in meaning (D-012, D-059). derivation: source is child, target is parent (chain, coverage, indirect verification). replacement: source replaces target core requirement for the variants in the source’s validity (D-020). succession: source is the successor that supersedes target (D-045, SR-072). exclusion: source variant excludes target core requirement, written in the variant file (SR-042, D-059). Without meaning a relation has no traceability semantics.

relationMeaning

Built-in meaning (D-012, D-059). derivation: source is child, target is parent (chain, coverage, indirect verification). replacement: source replaces target core requirement for the variants in the source’s validity (D-020). succession: source is the successor that supersedes target (D-045, SR-072). exclusion: source variant excludes target core requirement, written in the variant file (SR-042, D-059). Without meaning a relation has no traceability semantics.

Type: one of "derivation", "replacement", "succession", "exclusion".

status

Status value (D-030).

Type: named.

Field	Type	Required	Description
key	any	no
name	any	no
description	any	no
invalid	boolean	no	Elements with this status do not count for coverage, verification degree and indirect verification, but stay visible in chains (D-044). Default: false.
initial	boolean	no	Status of new elements. Exactly one status is initial. A type whose statuses do not include it gives its new elements its first status that is not marked invalid, in metamodel order, and so does every type when the initial status is marked invalid (a metamodel warning, #350); a type without status or with only invalid statuses gives them none (#306, #344). Default: false.

Examples

standard-model.yaml

# Standard model (D-037, extended by D-059 and D-060), shipped with ReqSeq and written by workspace.init (SR-014).
# Keys never change (D-043); names are English (D-019). Every built-in meaning has a key (SR-014 AK3):
# each type and property meaning exactly one, derivation two relation kinds
# (open question #150).
# Marked "assumption": not yet covered by a decision.
reqseq-metamodel: 1

types:
  - key: need
    name: Need
    description: "What a stakeholder needs, in their own words. System requirements derive from needs."
    prefix: N
    meaning: need
    properties: [title, rationale, topic, source, source-identifier, import-date, delivery, import-version]
    required: [title]
  - key: use-case
    name: Use Case
    description: "A goal a user reaches with the system, step by step. Requirements can refine it."
    prefix: UC
    properties: [title, rationale, source, source-identifier, import-date, delivery, import-version]
    required: [title]
  - key: system-requirement
    name: System Requirement
    description: "What the system must do or be, verified against its acceptance criteria."
    prefix: SR
    meaning: requirement
    properties:
      [
        title,
        rationale,
        requirement-type,
        acceptance-criteria,
        validity,
        packages,
        emergent,
        verification-method,
        statement,
        source,
        source-identifier,
        import-date,
        delivery,
        import-version,
        topic,
      ]
    required: [title, requirement-type, acceptance-criteria]
  - key: decision
    name: Decision
    description: "A decision with its rationale; requirements are based on it."
    prefix: D
    properties: [title, rationale, source, source-identifier, import-date, delivery, import-version]
    required: [title]
  - key: variant
    name: Variant
    description: "A variant of the product. Its requirements replace requirements of the core only through Replaces; Excludes names the core requirements that do not apply in it."
    prefix: VAR
    meaning: variant
    properties: [title, source, source-identifier, import-date, delivery, import-version]
    required: [title]
  - key: package
    name: Package
    description: "A group of elements. System requirements name it in their property Package."
    prefix: PKG
    meaning: package
    properties: [title, source, source-identifier, import-date, delivery, import-version]
    required: [title]

properties:
  - key: title
    name: Title
    description: "Short name of the element, shown with its short ID."
    kind: text
    meaning: title
  - key: rationale
    name: Rationale
    description: "Why the element exists or is as it is."
    kind: text
    markdown: true
  - key: requirement-type
    name: Requirement Type
    description: "The kind of requirement."
    kind: choice
    content: true
    choices:
      - { key: functional, name: Functional }
      - { key: quality, name: Quality }
      - { key: performance, name: Performance }
      - { key: interface, name: Interface }
      - { key: constraint, name: Constraint }
  - key: acceptance-criteria
    name: Acceptance Criteria
    description: "The conditions under which the requirement is met, one per entry."
    kind: text
    many: true
    content: true
    markdown: true
  - key: validity
    name: Validity
    description: "The variants the requirement applies to; without validity it belongs to the core and applies to every variant."
    kind: relation
    many: true
    target-types: [variant]
    content: true
    meaning: validity
  - key: packages
    name: Package
    description: "The packages the element belongs to."
    kind: relation
    many: true
    target-types: [package]
    meaning: packages
  - key: emergent
    name: Emergent
    description: "Whether the requirement has emergent behaviour: behaviour that does not follow from its children alone. Such a requirement needs evidence of its own."
    kind: choice
    meaning: emergent
    choices:
      - { key: "yes", name: "Yes" }
      - { key: "no", name: "No" }
  - key: verification-method
    name: Verification Method
    description: "How the requirement is verified."
    kind: choice
    meaning: verification-method
    choices:
      - { key: test, name: Test }
      - { key: analysis, name: Analysis }
      - { key: inspection, name: Inspection }
      - { key: demonstration, name: Demonstration }
  - {
      key: statement,
      name: Statement,
      kind: text,
      meaning: statement,
      description: "The supplier's statement on an imported requirement, exported to the source with `reqif export --statements`. It does not count to the version; the requirement itself is the element text.",
    }
  - {
      key: source,
      name: Source,
      kind: text,
      meaning: source,
      description: "The source the element was imported from.",
    }
  - {
      key: source-identifier,
      name: Source Identifier,
      kind: text,
      meaning: source-identifier,
      description: "The identifier of the element in its source.",
    }
  - {
      key: import-date,
      name: Import Date,
      kind: date,
      meaning: import-date,
      description: "The date of the import.",
    }
  - {
      key: delivery,
      name: Delivery,
      kind: text,
      meaning: delivery,
      description: "The name of the delivery the element was imported from.",
    }
  # D-059: Import Version has the meaning import-version (Importfassung), written only by the
  # import and never counted to the version. Every type carries the origin, so that a ReqIF
  # export of any selection can be imported again (assumption, #511).
  - {
      key: import-version,
      name: Import Version,
      kind: text,
      meaning: import-version,
      description: "The import version: the version of what the import wrote, right after the last import.",
    }
  # D-060 names only the property. Marked "assumption": kind text (the topics belong to the
  # project, D-019), on need and system-requirement as this spec uses "thema", not content
  # (like rationale and packages, D-057), not required.
  - {
      key: topic,
      name: Topic,
      kind: text,
      description: "The topic the element belongs to, as the project names its topics.",
    }

relations:
  - key: refines
    name: Refines
    description: "The source details the target, for example a requirement a need. A chain follows it from need to requirement."
    inverse-name: Refined by
    meaning: derivation
  - key: derives-from
    name: Derives from
    description: "A system requirement derives from a need, a use case or another system requirement. A chain follows it."
    inverse-name: Derived by
    source-types: [system-requirement]
    target-types: [need, use-case, system-requirement]
    meaning: derivation
  - key: based-on
    name: Based on
    description: "The source is based on a decision."
    inverse-name: Basis for
    target-types: [decision]
  - key: supersedes # a successor supersedes the target, D-045 / SR-072
    name: Supersedes
    description: "The source says that it supersedes the target. Superseding an element (element.supersede) also sets the target to an invalid status; the relation alone does not."
    inverse-name: Superseded by
    meaning: succession
  - key: replaces
    name: Replaces
    description: "A system requirement of a variant replaces one of the core in that variant."
    inverse-name: Replaced by
    source-types: [system-requirement]
    target-types: [system-requirement]
    meaning: replacement
  - key: excludes # D-059, SR-042
    name: Excludes
    description: "A variant excludes a system requirement of the core: it does not apply in that variant."
    inverse-name: Excluded by
    source-types: [variant]
    target-types: [system-requirement]
    meaning: exclusion

statuses:
  - { key: draft, name: Draft, initial: true, description: "Being written or changed." }
  - { key: approved, name: Approved, description: "Agreed and valid." }
  - {
      key: obsolete,
      name: Obsolete,
      invalid: true,
      description: "No longer valid. The element stays visible in the chain.",
    }