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
}

Annotations must always appear before conditions:

behhavior {
    @explanation "Valid!"
    condition true
    require true

    condition false
    @explanation "Compile Error!" // don't do this
    require false
}

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

Well Known Annotations

There are a few annotations that are known by KnowWE:

• label [string]: Used as a human-readable label
• Applies to all named items, e.g. structures, features, etc.
• Used to refer to test cases
• explanation [string]: Used to provide more context about an item
• Used to describe behaviors during conflict explanation
• Used to document individual steps of regression tests
• solution_space_relevant [boolean]: Provides hints to solving engines about which behaviors to solve (non) smartly

This list may extend in the future.

Examples

A comprehensive illustration on valid ways to use annotations:

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

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