Skip to content

Annotations

Annotations extend objects in the COOM model with metadata. They are not relevant for reasoning but provide a mechanism to store information for external systems.

Annotation Tables

Annotation tables are the preferred method for defining annotations. They centralize annotation definitions and ensure consistency. For example:

annotation sapid, label.en, label.de {
    Capacity = 1234, "Capacity", "Kapazität"
}

Each annotation is defined within an annotation { ... } block, analogous to behavior, structure, or enumeration blocks. A block specifies one or more annotations (e.g., sapid, label.en, label.de).

Each row first references a COOM object by its fully qualified name. For instance, Capacity refers to an enumeration, while Capacity.B10 addresses the option B10. The row must then provide a value for every annotation, separated by commas.

Annotation values may be:

  • String: either a symbol (capacity) or a quoted string if it contains spaces ("Kapazität in Liter").
  • Number: integer or floating-point.
  • Boolean: true or false.

The same annotation may appear in multiple blocks, but each COOM item can have only one value per annotation. For example:

annotation label {
    Capacity = "Kapazität in Liter"
    Capacity.B10 = "..."
}

annotation label { // both blocks valid
    Capacity = "Capacity in Liters" // invalid: Capacity already has "label"
    Capacity.B20 = "..." // valid
}

Annotations can be applied to:

  • product (referenced via root in tables)
  • structures, features
  • enumerations, attributes, options

Inline Annotations

Some COOM items lack a name suitable for table annotations, in particular behaviors. These can be annotated inline. For example:

behavior {
    @explanation = "The front and rear wheel must be equal"
    require frontWheel = rearWheel
}

Inline annotations take the form @<name>. A value is optional:

  • @name is equivalent to @name = true.
  • Otherwise, values follow the same rules as table annotations.

For behaviors, an inline annotation applies only to the immediately following statement:

behavior {
    @explanation = "The color must be red"
    require Color != Yellow // annotated
    require Color != Red    // not annotated
}

Although possible, using inline annotations for named items is discouraged. Annotation tables are the recommended approach.

Examples

A comprehensive illustration:

@inline
@inline_true = true
@inline_false = false
@inline_string = "Hello, world!"
@inline_symbol = hello_world
@inline_integer = 42
@inline_float = 13.37
structure Wheel {

}

annotation table_true, table_false, table_string, table_symbol, table_integer, table_float {
    Wheel = true, false, "Rad am Fahrrad", wheel, 42, 13.37
}