Module 5: Requirements & Constraints

SysML v2 requirements and constraints are built on KerML’s Constraint infrastructure — the part of the language that expresses boolean conditions that must hold. Every requirement keyword in this module is a SysML L2 specialisation of a KerML L1 construct from the Core and Constraint layers.

KerML origin: requirement def → ConstraintDefinition (Core layer)

A requirement definition declares a reusable requirement template. It names the requirement, optionally attaches documentation text, and can include formal constraint expressions. This is the definition side of the familiar definition/usage pattern from earlier modules.

Basic requirement with doc string

The simplest form attaches a doc string to a named requirement definition. This captures the traditional “shall” statement from systems engineering:

1
requirement def MaxSpeedReq {
2
    doc /* The vehicle shall not exceed a maximum speed of 250 km/h
3
         under normal operating conditions. */
4
}

Structured requirements with attributes

Requirements can carry typed attributes, just like part definitions. The attribute keyword inside a requirement definition declares parameters that are bound when the requirement is used:

1
requirement def SpeedLimitReq {
2
    doc /* The vehicle shall not exceed the specified speed limit. */
3
    attribute maxSpeed : ISQ::SpeedValue;
4
    subject vehicle : Vehicle;
5
    require constraint { vehicle.currentSpeed <= maxSpeed }
6
}

Requirement identifiers

Requirements can be given short identifiers for traceability. SysML v2 uses the short name syntax (angle-bracket notation) for this purpose:

1
requirement def <'REQ-BRK-001'> BrakingDistanceReq {
2
    doc /* The vehicle shall achieve full stop within 40 metres
3
         from 100 km/h on a dry surface. */
4
    subject vehicle : Vehicle;
5
    attribute surfaceCondition : SurfaceType;
6
}

KerML origin: requirement (usage) → ConstraintUsage (a Feature typed by ConstraintDefinition)

A requirement usage instantiates a requirement definition in a specific context. Like the definition/usage split for parts and actions, the definition is the reusable template and the usage binds it to concrete values and design elements.

Simple requirement usage

1
package VehicleRequirements {
2
    requirement maxSpeedReq : SpeedLimitReq {
3
        subject vehicle : SportsCar;
4
        attribute :>> maxSpeed = 250 [km/h];
5
    }
6
}

Nesting requirements into hierarchies

Requirements can be nested to form decomposition hierarchies. A parent requirement contains child requirements, expressing that all children must hold for the parent to be satisfied:

1
requirement def VehicleSafetyReq {
2
    doc /* The vehicle shall meet all safety requirements. */
3
    subject vehicle : Vehicle;
4

5
    requirement brakingReq : BrakingDistanceReq {
6
        doc /* Braking sub-requirement. */
7
    }
8

9
    requirement stabilityReq : StabilityControlReq {
10
        doc /* Stability control sub-requirement. */
11
    }
12

13
    requirement airbagReq : AirbagDeploymentReq {
14
        doc /* Airbag deployment sub-requirement. */
15
    }
16
}

Subject binding across the hierarchy

When a parent requirement declares a subject, child requirements inherit that binding unless they override it. This ensures all sub-requirements apply to the same design element:

1
requirement def PowertrainReq {
2
    subject powertrain : Powertrain;
3

4
    requirement torqueReq {
5
        doc /* Peak torque shall exceed 400 Nm. */
6
        require constraint { powertrain.peakTorque >= 400 [N*m] }
7
    }
8

9
    requirement efficiencyReq {
10
        doc /* Overall efficiency shall be at least 92%. */
11
        require constraint { powertrain.efficiency >= 0.92 }
12
    }
13
}

KerML origin: satisfy → SatisfyRequirementUsage (specialises RequirementUsage and AssertConstraintUsage)

The satisfy relationship (written assert satisfy) asserts that a design element meets a requirement. This is the primary traceability link between the requirements domain and the design domain. Requirement flow-down (deriving subsystem requirements from system requirements) is achieved using specialization (specializes), not a separate derive keyword.

Satisfy: linking requirements to design

1
part def BrakingSystem;
2

3
part vehicle : Vehicle {
4
    part brakes : BrakingSystem;
5

6
    // Assert that the braking system satisfies the braking requirement
7
    assert satisfy brakingReq by brakes;
8
}

Multiple satisfaction

A single design element can satisfy multiple requirements, and a single requirement can be satisfied by multiple elements working together:

1
part vehicle : Vehicle {
2
    part brakes   : BrakingSystem;
3
    part esc      : ElectronicStabilityControl;
4
    part airbags  : AirbagSystem;
5

6
    assert satisfy brakingReq   by brakes;
7
    assert satisfy stabilityReq by esc;
8
    assert satisfy airbagReq    by airbags;
9
}

Requirement flow-down using specialization

Requirement flow-down (deriving subsystem requirements from system requirements) is achieved using specializes. The child requirement inherits all constraints from the parent and can add further constraints or tighten existing ones:

1
requirement def SystemSafetyReq {
2
    doc /* The system shall prevent unintended acceleration. */
3
}
4

5
requirement def ThrottleSafetyReq specializes SystemSafetyReq {
6
    doc /* The throttle controller shall return to idle
7
         within 200 ms of brake pedal activation. */
8
}

KerML origin: constraint def → ConstraintDefinition;  constraint → ConstraintUsage

A constraint is a boolean expression that evaluates to true or false. Constraints are the formal backbone of requirements: while doc strings capture the human-readable intent, constraints capture the machine-checkable condition. Every requirement def is itself a specialised constraint def.

Defining constraints

1
constraint def TemperatureRange {
2
    attribute temp : ISQ::TemperatureValue;
3
    attribute minTemp : ISQ::TemperatureValue;
4
    attribute maxTemp : ISQ::TemperatureValue;
5
    temp >= minTemp and temp <= maxTemp
6
}

Using constraints on parts

Constraints can be applied to structural elements to assert invariants that must hold throughout the system’s lifetime:

1
part def Engine {
2
    attribute operatingTemp : ISQ::TemperatureValue;
3
    attribute coolantTemp   : ISQ::TemperatureValue;
4

5
    constraint tempLimit : TemperatureRange {
6
        attribute :>> temp    = operatingTemp;
7
        attribute :>> minTemp = 70 [degC];
8
        attribute :>> maxTemp = 120 [degC];
9
    }
10
}

Constraint expressions with operators

SysML v2 supports a rich expression language for constraints, including arithmetic, comparison, and logical operators:

1
constraint def PowerBudget {
2
    attribute totalPower     : ISQ::PowerValue;
3
    attribute maxPower       : ISQ::PowerValue;
4
    attribute safetyMargin   : Real;
5
    totalPower <= maxPower * (1.0 - safetyMargin)
6
}
7

8
constraint def MassBalance {
9
    attribute dryMass    : ISQ::MassValue;
10
    attribute fuelMass   : ISQ::MassValue;
11
    attribute payloadMass: ISQ::MassValue;
12
    attribute maxTakeoff : ISQ::MassValue;
13
    dryMass + fuelMass + payloadMass <= maxTakeoff
14
}

KerML origin: assume constraint → ConstraintUsage with isAssumption = true;  require constraint → ConstraintUsage with isRequired = true

SysML v2 distinguishes between two kinds of constraints within a requirement: assumptions (conditions taken for granted) and required constraints (conditions that must be guaranteed). This separation mirrors the contract programming paradigm: if the assumptions hold, then the required constraints must be satisfied.

Assume vs. require

1
requirement def BrakingPerformanceReq {
2
    doc /* The vehicle shall stop within 40 m from 100 km/h. */
3
    subject vehicle : Vehicle;
4

5
    assume constraint dryRoad {
6
        doc /* Surface friction coefficient is at least 0.7. */
7
        vehicle.surface.frictionCoeff >= 0.7
8
    }
9

10
    assume constraint normalLoad {
11
        doc /* Vehicle mass does not exceed gross vehicle weight. */
12
        vehicle.totalMass <= vehicle.grossVehicleWeight
13
    }
14

15
    require constraint stopDistance {
16
        doc /* Stopping distance from 100 km/h shall not exceed 40 m. */
17
        vehicle.stoppingDistance(100 [km/h]) <= 40 [m]
18
    }
19
}

Preconditions and postconditions on actions

Assumptions and required constraints can also be applied to actions, acting as preconditions and postconditions:

1
action def EmergencyBrake {
2
    in part vehicle : Vehicle;
3

4
    // Precondition: vehicle must be moving
5
    assume constraint {
6
        vehicle.speed > 0 [km/h]
7
    }
8

9
    // Postcondition: vehicle must be stopped
10
    require constraint {
11
        vehicle.speed == 0 [km/h]
12
    }
13
}

The following model integrates all five sections: a vehicle braking system with requirement definitions, hierarchical decomposition, satisfaction links, formal constraints, and assumption/guarantee separation.

1
package VehicleBrakingRequirements {
2
    private import ISQ::*;
3
    private import SI::*;
4
    private import ScalarValues::*;
5

6
    // ── Structure (from earlier modules) ────────────────────
7
    part def Vehicle {
8
        attribute totalMass : ISQ::MassValue;
9
        attribute speed     : ISQ::SpeedValue;
10
    }
11

12
    part def BrakingSystem {
13
        attribute brakingForce    : ISQ::ForceValue;
14
        attribute responseTime    : ISQ::TimeValue;
15
        attribute thermalCapacity : ISQ::EnergyValue;
16
    }
17

18
    part def ABSController;
19
    part def BrakeActuator;
20

21
    // ── Constraints (reusable boolean expressions) ──────────
22
    constraint def MaxStoppingDistance {
23
        attribute distance : ISQ::LengthValue;
24
        attribute limit    : ISQ::LengthValue;
25
        distance <= limit
26
    }
27

28
    constraint def ResponseTimeLimit {
29
        attribute actual : ISQ::TimeValue;
30
        attribute limit  : ISQ::TimeValue;
31
        actual <= limit
32
    }
33

34
    // ── Requirement definitions ─────────────────────────────
35
    requirement def <'REQ-BRK-000'> BrakingSafetyReq {
36
        doc /* The braking system shall ensure safe deceleration
37
             under all normal operating conditions. */
38
        subject vehicle : Vehicle;
39

40
        // ── Child: stopping distance ──
41
        requirement <'REQ-BRK-001'> stopDistReq {
42
            doc /* Full stop within 40 m from 100 km/h. */
43

44
            assume constraint drySurface {
45
                vehicle.surface.frictionCoeff >= 0.7
46
            }
47

48
            require constraint : MaxStoppingDistance {
49
                attribute :>> distance = vehicle.stoppingDistance;
50
                attribute :>> limit    = 40 [m];
51
            }
52
        }
53

54
        // ── Child: response time ──
55
        requirement <'REQ-BRK-002'> responseTimeReq {
56
            doc /* Brake actuation shall begin within 150 ms
57
                 of pedal input. */
58

59
            require constraint : ResponseTimeLimit {
60
                attribute :>> actual = vehicle.brakes.responseTime;
61
                attribute :>> limit  = 150 [ms];
62
            }
63
        }
64

65
        // ── Child: thermal endurance ──
66
        requirement <'REQ-BRK-003'> thermalReq {
67
            doc /* Brakes shall sustain 10 consecutive emergency stops
68
                 without fade below 80% effectiveness. */
69

70
            assume constraint normalAmbient {
71
                vehicle.ambientTemp >= -20 [degC] and
72
                vehicle.ambientTemp <= 45 [degC]
73
            }
74

75
            require constraint {
76
                vehicle.brakes.fadeAfterRepeatedStops(10) >= 0.80
77
            }
78
        }
79
    }
80

81
    // ── Specialised requirement: ABS-specific ──────────────
82
    requirement def <'REQ-ABS-001'> ABSActivationReq specializes BrakingSafetyReq {
83
        doc /* ABS shall modulate brake pressure at 15 Hz minimum
84
             when wheel slip exceeds 10%. */
85
        subject abs : ABSController;
86
        // flow-down via specializes (declared above)
87

88
        require constraint {
89
            abs.modulationFrequency >= 15 [Hz]
90
        }
91
    }
92

93
    // ── Satisfaction: linking design to requirements ────────
94
    part testVehicle : Vehicle {
95
        part brakes     : BrakingSystem;
96
        part absCtrl    : ABSController;
97
        part actuators  : BrakeActuator;
98

99
        assert satisfy BrakingSafetyReq by brakes;
100
        assert satisfy ABSActivationReq by absCtrl;
101
    }
102
}

This model demonstrates: requirement def with doc strings and identifiers, hierarchical requirement decomposition (parent BrakingSafetyReq containing three child requirements), assume and require constraint separation, reusable constraint definitions (MaxStoppingDistance, ResponseTimeLimit), specializes for requirement flow-down (ABSActivationReq specializes BrakingSafetyReq), and assert satisfy links connecting requirements to design elements.