Skip to content

Metamodel#

The metamodel describes what a project can contain before anyone models anything: which kinds of nodes exist, where they sit on the canvas, how they look, which fields they carry, and which states they move through. The nodes you create on the canvas are instances of this model.

Each project has its own metamodel. You edit it under Settings → Project → Metamodel, which has four sections that follow the same idea from top to bottom:

Section Answers
Types & layers Which node types does the project use, and on which architecture layer?
Appearance How does each type look on the canvas?
Attributes Which extra fields does a type carry?
Status & lifecycle Which states can a node be in, and which steps between them are allowed?

Only project editors can change the metamodel. Everyone else sees it read-only.

Types and layers#

Every node type is based on a template: Requirement, Test, or Risk. The template is the fixed core. It decides the built-in fields (a requirement has a statement, a test has CI fields), what the type can do (be verified, mitigate a risk), and which lifecycle applies. A project can have several types on the same template, for example Customer Requirement and SW-Requirement, both built on Requirement.

Each type has a name and a key prefix. The prefix starts every generated node key, so CUST_REQ turns a node titled "Payment timeout" into CUST_REQ_PAYMENT_TIMEOUT. Changing the prefix later renames the keys of all existing nodes of that type; OakCore shows you the affected keys before it applies the change.

Requirement types also have a layer. Layers follow the usual refinement from customer needs down to implementation:

Customer › System › Software · Hardware · Mechanics

Software, hardware, and mechanics are peers on the same level. The layer places the type on its own canvas row and picks its lifecycle (see below). Turning a layer on in Requirement layers adds a matching requirement type. Turning it off removes that type again, as long as no nodes or other types still use the layer.

The optional band splits one layer into finer rows. Band 1 is the broadest, higher numbers sit below it. Use it when, for example, system requirements are refined in two steps.

Tests and risks have no fixed layer. Their position follows the requirements they verify or mitigate.

Appearance#

Icon & color sets how a type is recognized on the canvas, in lists, and in filters.

Card decides what a canvas card shows below the title: which attribute chips appear (status, responsible person, comment count, custom fields, and more) and how many lines of the description. The preview in the list matches what the canvas renders.

Attributes#

Every node has the same core fields: title, description, status, status rationale, responsible person, and tags. The template adds its own fields, for example the statement of a requirement.

Custom attributes are fields you add on top, per type. Typical examples are an ASIL level as a selection, a supplier as short text, or an effort estimate as a number. Available kinds are short text, long text, whole number, decimal, yes/no, and selection. Custom attributes appear in the node sidebar, in filters and analytics, in imports and exports, and can be placed on the canvas card.

Status and lifecycle#

The status says where a node stands in authoring and review. It does not say whether something is implemented or whether a test passed; those live in their own fields and in test results.

The lifecycle is defined by the platform and means the same in every project. A colleague reading "In review" in another project can rely on it meaning exactly that.

States#

State Meaning
Draft Being created or refined.
In review Awaiting review or a decision.
Approved Accepted without reservations.
Partly approved Accepted in part; the open points are recorded in the status rationale.
Rejected Explicitly not accepted.
Obsolete No longer applicable; kept for history.

Which states a type uses depends on its template and layer:

Type States
Customer requirements, and requirements without a layer All six
System, software, hardware, and mechanics requirements Draft, In review, Approved, Obsolete
Tests and risks Draft, In review, Approved, Obsolete

Only the customer decides on partial or negative acceptance, so only customer requirements can be partly approved or rejected. Internal requirements that do not pass review go back to Draft.

Allowed transitions#

A node can only move along the arrows. Saving any other change is rejected, on the canvas, in the sidebar, in batch edits, and through the API.

stateDiagram-v2
    direction LR
    [*] --> Draft
    Draft --> InReview
    Draft --> Obsolete
    InReview --> Approved
    InReview --> PartlyApproved
    InReview --> Rejected
    InReview --> Draft
    PartlyApproved --> InReview
    PartlyApproved --> Draft
    PartlyApproved --> Obsolete
    Approved --> Draft
    Approved --> Obsolete
    Rejected --> Draft
    Rejected --> Obsolete
    Obsolete --> Draft
    InReview: In review
    PartlyApproved: Partly approved

The rules behind the arrows:

  • No approval without review. A draft cannot jump to Approved, Partly approved, or Rejected. It has to be submitted for review first.
  • Changing an approved node reopens it. To edit the content of an approved node, move it back to Draft and review it again. There is no direct way from Approved back to In review or to Rejected.
  • Partly approved is resolved by another review. Once the open points are fixed, the node goes back to In review.
  • Rejected and Obsolete are not dead ends. Both can be reopened as Draft. Obsolete nodes stay in the project for traceability and history.

Internal layers, tests, and risks use the same arrows without Partly approved and Rejected.

The canvas card offers the main step as a one-click action (Draft to In review, In review to Approved, Partly approved to In review). The status menu on the card and the sidebar only list states that are allowed from the current one.

Imports are the exception: they take over the status from the source tool as it is, so a migration does not have to replay every review.

Process rules#

Workspace processes can add conditions to a state, for example that an approved requirement needs at least one verifying test. These rules are maintained under Processes, not in the metamodel. Settings → Metamodel → Status & lifecycle and the status field in the node sidebar show them next to each state.

See also#