Language Reference#

The SysML v2 language is made up of a series of nested objects. At its core, you can define elements like package, requirement, part, and other modeling constructs.

Package#

Packages are the root container objects of SysML v2 models. They provide namespace organization and grouping for model elements.

Basic Syntax:

package Name {
    // Package contents
}

package 'Multiple Word Name' {
    // Package contents
}

Nested Packages:

package OuterPackage {
    package InnerPackage {
        // Nested package contents
    }
}

Requirements#

Requirements define system needs, constraints, and specifications. They support both short identifiers and descriptive names.

Requirement Declaration Syntax#

Valid requirement declarations:

requirement;

requirement { }

requirement OneWordName { }

requirement 'Multiple Word Name' { }

requirement <'REQ-001'> 'Descriptive Requirement Name' { }

Best Practice: Use both a declared short name (ID) and a declared name for traceability:

requirement <'REQ-PERF-001'> 'Maximum Cruise Speed' {
    // Requirement contents
}

Requirement Structure#

A complete requirement typically includes:

requirement <'REQ-XXX-###'> 'Descriptive Requirement Name' {
    doc 
    /* 
     * Primary requirement text goes here.
     * "Shall statements" and long-form descriptions.
     */

    // Technical attributes with specific value types and units
    attribute maxSpeed : SpeedValue = 100.0 [knots];
    attribute mass : MassValue = 50.0 [kg];

    // Standard requirement metadata (built-in)
    metadata RequirementMetadata {
        rationale = "Justification for why this requirement exists";
        level = 1;  // Hierarchy level: 1=top-level, 2=derived, etc.
    }

    // Custom metadata (optional, if needed beyond RequirementMetadata)
    metadata CustomRequirementMetadata {
        notes = "Additional context or information";
        validationMethod = "Test method description";
    }
}

Docstring#

The doc block contains the primary requirement text, narrative descriptions, and "shall statements":

requirement <'REQ-001'> 'Power Output Requirement' {
    doc 
    /* 
     * The propulsion system shall provide a minimum continuous 
     * power output of 20 horsepower at 6000 RPM under standard
     * atmospheric conditions.
     */

    attribute minPower : PowerValue = 20.0 [hp];
}

Requirement Attributes#

Use specific value types instead of generic Real types when possible:

Measurement Type	Value Type	Example Units
Length/Distance	`LengthValue`	`[m]`, `[ft]`, `[in]`, `[nm]`
Mass	`MassValue`	`[kg]`, `[lb]`
Speed/Velocity	`SpeedValue`	`[knots]`, `[m/s]`
Power	`PowerValue`	`[hp]`, `[W]`, `[kW]`
Force	`ForceValue`	`[N]`, `[lbf]`
Voltage	`ElectricPotentialValue`	`[V]`
Current	`ElectricCurrentValue`	`[A]`
Frequency	`FrequencyValue`	`[Hz]`, `[MHz]`, `[GHz]`
Angle	`AngularMeasureValue`	`[deg]`, `[rad]`
Volume	`VolumeValue`	`[L]`, `[gal]`, `[cc]`

Examples:

attribute wingspan : LengthValue = 10.5 [m];
attribute voltage : ElectricPotentialValue = 28.0 [V];
attribute efficiency : Real = 0.85;  // Dimensionless ratio
attribute rpm : Real = 6000.0 [rpm];  // Angular speed

Requirements#

Requirements can contain nested sub-requirements to create hierarchical structures:

requirement <'REQ-SYS-001'> 'Mission Performance Capability' {
    doc /* Top-level mission performance requirements */

    metadata RequirementMetadata {
        rationale = "Defines overall mission performance envelope";
        level = 1;
    }

    requirement <'REQ-RANGE-001'> 'Minimum Range Requirement' {
        doc /* The system shall achieve a minimum range of 500 nm */

        attribute minRange : LengthValue = 500.0 [nm];

        metadata RequirementMetadata {
            rationale = "Mission profile requires extended range operations";
            level = 2;
        }
    }
}

This is called a "Requirements Decomposition" relationship.

Requirement Metadata#

RequirementMetadata (Built-in):

The platform provides pre-imported RequirementMetadata with standard fields:

metadata RequirementMetadata {
    rationale = "Why this requirement exists or its justification";
    level = 1;  // Integer: hierarchy level (1=top, 2=derived, 3=sub-derived)
}

CustomRequirementMetadata (Optional):

Define custom metadata only if you need additional fields beyond rationale and level:

// Define once at package level
metadata def CustomRequirementMetadata {
    attribute priority : ScalarValues::String;
    attribute needBy : Time::Iso8601DateTimeEncoding;
    attribute requested : Time::Iso8601DateTimeEncoding;
    attribute validationMethod : ScalarValues::String;
    attribute notes : ScalarValues::String;
}

// Use within requirements
requirement <'REQ-001'> 'My Requirement' {
    metadata RequirementMetadata {
        rationale = "Customer specification requirement";
        level = 1;
    }

    metadata CustomRequirementMetadata {
        priority = "high";
        requested = "2025-12-04T17:00:00.000Z";
        needBy = "2025-12-24T17:00:00.000Z";
        validationMethod = "Flight test at design altitude";
    }
}

Best Practice: Use RequirementMetadata for standard information (rationale, level), and only add CustomRequirementMetadata for project-specific needs.

SysML v2 uses two different operators for navigating to elements:

Double colon (::) — For package/namespace qualification
Dot (.) — For member/feature navigation within elements

Examples:

// Package qualification with ::
Requirements::TopLevelRequirements::'Maximum Speed'

// Nested feature navigation with .
'Mission Performance Capability'.'Minimum Range Requirement'

// Combined: package qualification, then nesting
Requirements::Performance::'System Requirements'.'Speed Requirement'

// Reference nested requirement in verification
verify Requirements::'Mission Performance Capability'.'Minimum Range Requirement';

// Allocate to nested part
allocate Requirements::'Power Requirement' to System.'Propulsion'.'Engine';

Quick Reference Table:

Navigation Type	Operator	Example
Package qualification	`::`	`Requirements::Performance`
Nested requirement	`.`	`'Parent Req'.'Child Req'`
Nested part/feature	`.`	`Drone.'Power System'.'Battery'`
Combined	`::` then `.`	`Pkg::Element.'Nested Feature'`

Derivation#

Derived requirements show traceability from source requirements to refined or decomposed requirements:

dependency derivation {
    client original ::> Requirements::'Original Requirement';
    supplier derived ::> Requirements::'Derived Requirement';
}

Alternative syntax:

#derivation connection {
    end #original ::> OriginatingRequirement;
    end #derive ::> DerivedRequirement;
}

Satisfy Relationships#

Satisfy relationships link requirements to the system elements that fulfill them:

// Simple satisfy
satisfy Requirements::'Maximum Range' by 'Power System';

// With package qualification
satisfy Requirements::Performance::'Maximum Speed' by 'Propulsion Assembly';

// Nested requirement satisfied by nested part
satisfy Requirements::'System Performance'.'Speed Requirement' 
    by System.'Propulsion'.'Engine';

Allocate Relationships#

Allocate relationships assign requirements to specific system elements:

// Allocate requirement to part
allocate Requirements::'Power Requirement' to Drone.'Power System';

// Allocate nested requirement to nested part
allocate 'Mission Performance Capability'.'Minimum Range Requirement' 
    to 'Complex Drone System'::Drone.'Power System';

// Allocate to deeply nested element
allocate Requirements::'Battery Capacity' 
    to System.'Propulsion'.'Power System'.'Battery';

Verifications#

Verifications define how requirements will be validated or verified. A single verification can verify multiple requirements to avoid duplication.

Verification Structure#

verification 'Descriptive Verification Name' {
    objective { 
        doc 
        /* 
         * Description of what this verification does,
         * what is being verified, and how.
         */
        verify PackageName::'Requirement Name 1';
        verify PackageName::'Parent Requirement'.'Nested Requirement';
        // Can verify multiple requirements using declared names
    }

    // Optional: verification method (if specified or clearly implied)
    metadata VerificationCases::VerificationMethod {
        kind = VerificationCases::VerificationMethodKind::test;
    }

    // Optional: risk level (only if provided in source material)
    metadata RiskMetadata::Risk {
        totalRisk = RiskMetadata::RiskLevelEnum::medium;
    }
}

Verification Methods#

Choose the appropriate method based on how the requirement will be verified:

test — Physical testing, experimental validation, operational testing
inspect — Visual inspection, document review, examination of deliverables
analyze — Analysis, calculation, simulation, modeling
demo — Demonstration, operational verification, functional demonstration

Note: Omit the method metadata if no method is specified or cannot be reasonably inferred.

Verification Examples#

Single requirement verification:

verification 'Cruise Speed Flight Test' {
    objective { 
        doc /* Verify cruise speed through flight test at design altitude. */
        verify Requirements::'Maximum Cruise Speed';
    }

    metadata VerificationCases::VerificationMethod {
        kind = VerificationCases::VerificationMethodKind::test;
    }
}

Multiple requirements (consolidated):

verification 'Propulsion System Performance Analysis' {
    objective { 
        doc 
        /* 
         * Analytical verification of propulsion system performance 
         * including thrust, power output, and fuel consumption.
         */
        verify Requirements::'Maximum Thrust Requirement';
        verify Requirements::'Power Output Requirement';
        verify Requirements::'Fuel Consumption Limit';
    }

    metadata VerificationCases::VerificationMethod {
        kind = VerificationCases::VerificationMethodKind::analyze;
    }

    metadata RiskMetadata::Risk {
        totalRisk = RiskMetadata::RiskLevelEnum::low;
    }
}

Verifying nested requirements:

verification 'Range Performance Test' {
    objective { 
        doc /* Verify minimum range capability through flight test. */
        verify Requirements::'Mission Performance Capability'.'Minimum Range Requirement';
    }

    metadata VerificationCases::VerificationMethod {
        kind = VerificationCases::VerificationMethodKind::test;
    }
}

Best Practices for Verifications#

Consolidate first: Review all requirements and create a consolidated list of unique verification activities before creating verification usages
Minimize duplication: One verification can verify multiple requirements — create as few verifications as possible while providing sufficient coverage
Use declared names: Always reference requirements using their declared names (e.g., 'Maximum Speed'), never short names (e.g., <'REQ-001'>)
Include methods when known: Add verification method metadata when the approach is specified or clearly implied
Omit when uncertain: Leave out method or risk metadata if not provided or cannot be reasonably determined

Parts and System Elements#

While this reference focuses on requirements, SysML v2 also supports defining system structure through parts:

part def PropulsionSystem {
    attribute thrust : ForceValue;
    attribute weight : MassValue;
}

part myPropulsion : PropulsionSystem {
    attribute thrust : ForceValue = 500.0 [N];
    attribute weight : MassValue = 15.0 [kg];
}

Parts can be nested to represent system hierarchy:

part Drone {
    part 'Power System' {
        part 'Battery' {
            attribute capacity : Real = 5000.0 [mAh];
            attribute voltage : ElectricPotentialValue = 14.8 [V];
        }
    }
}

Language Reference#

Package#

Requirements#

Requirement Declaration Syntax#

Requirement Structure#

Docstring#

Requirement Attributes#

Requirements#

Requirement Metadata#

Path Navigation#

Derivation#

Satisfy Relationships#

Allocate Relationships#

Verifications#

Verification Structure#

Verification Methods#

Verification Examples#

Best Practices for Verifications#

Parts and System Elements#