Prompt Engineering for SysML v2#
Thanks to both LLMs and the Textual Notation, it's straightforward to get to a near-functional system model by using a common foundational model.
We reccomend creating a new Project, and inserting the below instructions. Also we suggest downloading the SysML v2 textual notation language reference PDF and including it as well.
Chatbot Instructions#
Use the following instructions
# SysML v2 Modeling Rules
## Attribute Type Selection Rules
When defining attributes in SysML v2, replace generic `Real` types with specific value types according to the following mappings:
**Use Specific Value Types:**
- Volume → `VolumeValue`
- Power → `PowerValue`
- Mass → `MassValue`
- Electric current (Amperes) → `ElectricCurrentValue`
- Electric potential/Voltage (Volts) → `ElectricPotentialValue`
- Frequency (Hz, MHz, GHz) → `FrequencyValue`
- Length/Distance → `LengthValue`
- Force (Newtons) → `ForceValue`
- Speed/Velocity → `SpeedValue`
- Angle/Angular measure (degrees, radians) → `AngularMeasureValue`
**Keep as `Real` for:**
- Angular speed (RPM, rad/s, revolutions per minute)
- Compound units without standard value types (e.g., specific fuel consumption lb/hp/hr, data rate kbps, C rating)
- Dimensionless ratios and percentages (e.g., efficiency, discharge rate)
- Battery capacity in mAh
**Keep as `String`:**
- Text values (fuel types, materials, protocols, model names, configurations)
**Keep as `Integer`:**
- Counts (cell count, number of ports, channels, axes, number of outputs)
## Attribute Definition and Usage Syntax
**In Part Definitions (defining the attribute type):**
```sysml
part def MyComponent {
attribute mass : MassValue; // type declaration with comment
attribute voltage : ElectricPotentialValue; // Volts
}
```
**In Part Usages (assigning values with units):**
```sysml
part myInstance : MyComponent {
attribute mass : MassValue = 12.5 [lb];
attribute voltage : ElectricPotentialValue = 28.0 [V];
}
```
**Common Unit Abbreviations:**
- `[hp]` - horsepower
- `[lb]` - pounds
- `[kg]` - kilograms
- `[cc]` - cubic centimeters
- `[rpm]` - revolutions per minute
- `[V]` - volts
- `[A]` - amperes
- `[W]` - watts
- `[N]` - newtons
- `[in]` - inches
- `[gal]` - gallons
- `[mAh]` - milliamp-hours
- `[Hz]` - hertz
- `[m]` - meters
- `[ft]` - feet
- `[knots]` - nautical miles per hour
## Path Navigation and Reference Rules
**CRITICAL: Understanding Path Navigation Syntax**
SysML v2 uses two different operators for navigating to elements:
- **Double colon (`::`**) - Used for package/namespace qualification
- **Dot (`.`)** - Used for member/feature navigation within elements
### Path Navigation Rules
**Rule 1: Use `::` for package/namespace qualification**
```sysml
Requirements::TopLevelRequirements::'Maximum Speed'
ComplexDroneSystem::Drone
```
**Rule 2: Use `.` for navigating into nested features/members**
```sysml
'Mission Performance Capability'.'Minimum Range Requirement'
Drone.'Power System'
'Power System'.'Battery'
```
**Rule 3: Combine both when needed**
```sysml
'Complex Drone System'::Drone.'Power System'
Requirements::Performance::'Speed Requirement'.'Cruise Speed'
```
### Correct vs Incorrect Examples
✅ **CORRECT - Nested requirement reference:**
```sysml
verify 'Mission Performance Capability'.'Minimum Range Requirement';
```
❌ **INCORRECT - Using :: for nesting:**
```sysml
verify 'Mission Performance Capability'::'Minimum Range Requirement'; // WRONG
```
✅ **CORRECT - Part with package qualification and nesting:**
```sysml
allocate requirement to 'Complex Drone System'::Drone.'Power System';
```
❌ **INCORRECT - Using :: for part nesting:**
```sysml
allocate requirement to 'Complex Drone System'::Drone::'Power System'; // WRONG
```
✅ **CORRECT - Multiple levels of nesting:**
```sysml
satisfy Requirements.'System Requirements'.'Performance'.'Speed' by System.'Propulsion'.'Engine';
```
❌ **INCORRECT - All :: navigation:**
```sysml
satisfy Requirements::'System Requirements'::'Performance'::'Speed' by System::'Propulsion'::'Engine'; // WRONG
```
### Path Navigation Summary Table
| Navigation Type | Operator | Example |
|----------------|----------|---------|
| Package qualification | `::` | `Requirements::TopLevel` |
| Nested feature/member | `.` | `'Parent Req'.'Child Req'` |
| Part member | `.` | `Drone.'Power System'` |
| Combined | `::` then `.` | `Package::Element.'Nested Feature'` |
## Naming and Reference Rules
**Declared Short Names vs Declared Names:**
✅ **USE Declared Short Names when DEFINING requirements:**
```sysml
requirement <'REQ-001'> 'My Requirement' {
doc /* requirement text */
}
requirement def <'REQ-DEF-001'> 'My Requirement Definition' {
doc /* requirement definition */
}
```
❌ **DO NOT USE Declared Short Names when REFERENCING requirements:**
```sysml
// INCORRECT - Do not reference using short name
satisfy Requirements::<'REQ-001'> by System;
verify Requirements::<'REQ-PERF-002'>;
```
✅ **ALWAYS USE Declared Names when REFERENCING requirements:**
```sysml
// CORRECT - Always reference using declared name
satisfy Requirements::'My Requirement' by System;
verify Requirements::'Maximum Cruise Speed';
```
**Summary:**
- **Definitions**: Use BOTH `<'SHORT-ID'>` AND `'Declared Name'`
- **References**: Use ONLY `'Declared Name'`
**Complete Examples:**
✅ **CORRECT - Definition and Reference:**
```sysml
// Definition - uses both short name and declared name
requirement <'REQ-PERF-001'> 'Maximum Cruise Speed' {
doc /* The system shall achieve... */
}
// Reference - uses only declared name
satisfy Requirements::'Maximum Cruise Speed' by 'Propulsion System';
verify Requirements::'Maximum Cruise Speed';
```
✅ **CORRECT - Nested requirement reference:**
```sysml
// Define nested requirements
requirement <'REQ-SYS-001'> 'System Performance' {
requirement <'REQ-PERF-001'> 'Maximum Cruise Speed' {
doc /* ... */
}
}
// Reference using dot notation for nesting
verify Requirements::'System Performance'.'Maximum Cruise Speed';
```
## Requirement Modeling Rules
### Basic Requirement Structure
```sysml
requirement <'REQ-XXX-###'> 'Descriptive Requirement Name' {
doc
/*
* Primary requirement text goes here.
* This is where "shall statements" belong.
* Long-form descriptions go here.
*/
// Technical attributes with units
attribute attributeName : ValueType = value [unit];
// OR use constraint if described as a constraint
assert constraint constraintName { /* constraint expression */ }
// Standard requirement metadata (already imported in platform)
metadata RequirementMetadata {
rationale = "Why this requirement exists";
level = 1; // Requirement hierarchy level (integer)
}
// Custom metadata for additional information (if needed beyond RequirementMetadata)
metadata CustomRequirementMetadata {
notes = "Additional notes or descriptions";
validationMethod = "Method description if applicable";
}
}
```
### Requirement Metadata
**RequirementMetadata (Built-in):**
The platform provides a pre-imported `RequirementMetadata` metadata definition with the following attributes:
- `rationale` (String): Explanation of why the requirement exists or its justification
- `level` (Integer): Requirement hierarchy level (typically 1 for top-level, 2 for derived, etc.)
**Usage:**
```sysml
metadata RequirementMetadata {
rationale = "The drone needs to fly at high altitude for surveillance missions";
level = 1;
}
```
**When to use RequirementMetadata:**
- Use `rationale` for requirement justification, background, or reasoning
- Use `level` to indicate requirement hierarchy (1 = top-level, 2 = derived, 3 = sub-derived, etc.)
- This is the preferred metadata for standard requirement information
**CustomRequirementMetadata (Optional):**
If you need additional metadata fields beyond `rationale` and `level`, you can define and use `CustomRequirementMetadata`:
```sysml
metadata def CustomRequirementMetadata {
attribute validationMethod : ScalarValues::String;
attribute notes : ScalarValues::String;
}
```
Then use within requirements:
```sysml
metadata CustomRequirementMetadata {
notes = "Additional context specific to this project";
validationMethod = "Inspection of technical drawings";
}
```
**Best Practice:**
- Use `RequirementMetadata` for rationale and level information
- Only create `CustomRequirementMetadata` if you need fields beyond what `RequirementMetadata` provides
- You can use both in the same requirement if needed
### Requirement Content Placement
**Declared Short Name** (`<'...'>`):
- Use for requirement IDs and shorthand identifiers
- Examples: `<'REQ-001'>`, `<'REQ-PERF-10'>`, `<'REQ-PROP-THR-01'>`
- This makes the requirement traceable and easy to identify
- **IMPORTANT**: Only use in the requirement definition itself, NOT in references
**Declared Name** (`'...'`):
- Use unique, descriptive name from source material if available
- If not available, generate a clear, concise descriptive name
- Examples: `'Maximum Cruise Speed'`, `'Fuel Capacity Requirement'`, `'Battery Endurance'`
- This is what you'll use when referencing the requirement elsewhere
**Docstring** (`doc /* ... */`):
- Primary requirement text
- "Shall statements" (e.g., "The system shall provide...")
- Long-form descriptions
- Narrative requirement content
**Attributes**:
- Technical values with units → use `attribute` with appropriate type and unit
- Example: `attribute maxSpeed : SpeedValue = 100.0 [knots];`
- If the requirement specifies a constraint relationship → use `assert constraint` instead
**RequirementMetadata**:
- `rationale`: Why the requirement exists, its justification or background
- `level`: Requirement hierarchy level (integer)
**CustomRequirementMetadata** (if needed):
- Additional notes, descriptions, or context that don't fit elsewhere
- Validation/verification method descriptions
- Source traceability information
- Any project-specific metadata fields
### Complete Requirement Examples
**Example 1: Using RequirementMetadata only**
```sysml
requirement <'REQ-PERF-001'> 'Maximum Cruise Speed' {
doc
/*
* The aircraft shall achieve a maximum cruise speed of at least 100 knots
* at design altitude under standard atmospheric conditions.
*/
attribute maxSpeed : SpeedValue = 100.0 [knots];
attribute designAltitude : LengthValue = 10000.0 [ft];
metadata RequirementMetadata {
rationale = "Required to meet mission profile for long-range surveillance";
level = 1;
}
}
```
**Example 2: Nested requirements with correct referencing**
```sysml
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;
}
}
}
// Reference nested requirement using dot notation
verification 'Range Test' {
objective {
verify Requirements::'Mission Performance Capability'.'Minimum Range Requirement';
}
}
```
**Example 3: Using both RequirementMetadata and CustomRequirementMetadata**
```sysml
requirement <'REQ-PROP-005'> 'Engine Power Output' {
doc
/*
* The propulsion system shall provide a minimum continuous power output
* of 20 horsepower at 6000 RPM.
*/
attribute minPower : PowerValue = 20.0 [hp];
attribute operatingRPM : Real = 6000.0 [rpm];
metadata RequirementMetadata {
rationale = "Derived from thrust requirements and propeller efficiency analysis";
level = 2;
}
metadata CustomRequirementMetadata {
validationMethod = "Engine dynamometer test";
notes = "Test to be conducted at sea level, standard day conditions";
}
}
```
## Verification Modeling Rules
### When to Create Verifications
- Create verifications when source material provides validation/verification methods
- **Consolidate first**: Review all requirements and create a consolidated list of unique verification activities
- **Minimize duplication**: One verification can verify multiple requirements
- Create as few verifications as possible while providing sufficient coverage
- Only create the verification usages after completing the consolidated list
### Verification Structure Template
```sysml
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 - use Declared Names only (NOT short names)
// Use dot notation for nested requirements
}
// Include method only if provided or clearly implied
metadata VerificationCases::VerificationMethod {
kind = VerificationCases::VerificationMethodKind::METHOD_TYPE;
}
// Include risk only if provided in source material
metadata RiskMetadata::Risk {
totalRisk = RiskMetadata::RiskLevelEnum::RISK_LEVEL;
}
}
```
### Verification Method Types
Choose the appropriate method based on source material or implied approach:
- **`inspect`** - Visual inspection, document review, examination of deliverables
- **`test`** - Physical testing, experimental validation, operational testing
- **`analyze`** - Analysis, calculation, simulation, modeling
- **`demo`** - Demonstration, operational verification, functional demonstration
**Omit the method metadata entirely if:**
- No method is specified in source material
- The method cannot be reasonably inferred
- You are unsure which method applies
### Risk Level Types
Use only if explicitly provided in source material:
- **`low`** - Low risk
- **`medium`** - Medium risk
- **`high`** - High risk
**Omit the risk metadata entirely if:**
- No risk level is provided in source material
- Risk cannot be reasonably determined
### Verification Examples
**Single Requirement (using Declared Name in reference):**
```sysml
verification 'Cruise Speed Flight Test' {
objective {
doc
/*
* Verify cruise speed through flight test at design altitude.
*/
verify Requirements::'Maximum Cruise Speed'; // Use declared name, not <'REQ-PERF-001'>
}
metadata VerificationCases::VerificationMethod {
kind = VerificationCases::VerificationMethodKind::test;
}
metadata RiskMetadata::Risk {
totalRisk = RiskMetadata::RiskLevelEnum::medium;
}
}
```
**Nested Requirement (using dot notation):**
```sysml
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;
}
}
```
**Multiple Requirements (using Declared Names in references):**
```sysml
verification 'Propulsion System Performance Analysis' {
objective {
doc
/*
* Analytical verification of propulsion system performance parameters
* 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;
}
}
```
## Relationship Rules (Satisfy, Allocate, Derive)
### Satisfy Relationships
When creating satisfy relationships, always use Declared Names (NOT Declared Short Names) and correct path navigation:
✅ **CORRECT:**
```sysml
// Simple satisfy
satisfy Requirements::'Minimum Range Requirement' by 'Power System';
// With package qualification
satisfy Requirements::Performance::'Maximum Speed' by 'Propulsion Assembly';
// Nested requirement with dot notation
satisfy Requirements::'System Performance'.'Speed Requirement' by 'Propulsion System';
```
❌ **INCORRECT:**
```sysml
satisfy Requirements::<'REQ-RANGE-001'> by 'Power System'; // Don't use short name
satisfy Requirements::'System Performance'::'Speed Requirement' by 'Propulsion System'; // Wrong operator
```
### Allocate Relationships
Allocate relationships use the same path navigation rules - `::` for packages, `.` for nested members:
✅ **CORRECT - Allocate with proper path navigation:**
```sysml
// Allocate nested requirement to nested part
allocate 'Mission Performance Capability'.'Minimum Range Requirement'
to 'Complex Drone System'::Drone.'Power System';
// Allocate to deeply nested part
allocate Requirements::'Power Requirement'
to System.'Propulsion'.'Engine'.'Fuel System';
```
❌ **INCORRECT - Using :: for all navigation:**
```sysml
allocate 'Mission Performance Capability'::'Minimum Range Requirement' // WRONG
to 'Complex Drone System'::Drone::'Power System'; // WRONG
```
### Complete Allocate Example
```sysml
package 'Complex Drone System' {
package Requirements {
requirement <'REQ-SYS-001'> 'Mission Performance Capability' {
requirement <'REQ-RANGE-001'> 'Minimum Range Requirement' {
doc /* The system shall achieve a minimum range of 500 nm */
attribute minRange : LengthValue = 500.0 [nm];
}
}
}
part Drone {
part 'Power System' {
part 'Battery' {
// Battery definition
}
}
}
// Correct allocation syntax - dot for nesting, :: for package qualification
allocate 'Mission Performance Capability'.'Minimum Range Requirement'
to 'Complex Drone System'::Drone.'Power System';
// Allocate to deeply nested element
allocate Requirements::'Mission Performance Capability'.'Minimum Range Requirement'
to Drone.'Power System'.'Battery';
}
```
## Application Guidelines
These rules apply when:
- Creating new SysML v2 models from scratch
- Converting existing engineering artifacts to SysML v2:
- Spreadsheets with requirements or specifications
- Unstructured text documents
- Written specifications or technical reports
- Requirements databases or documents
- Legacy system documentation
- Cleaning up or refactoring existing SysML v2 models
- Reviewing and improving SysML v2 code quality
## Processing Workflow
When converting source material to SysML v2:
1. **Identify requirement-like content** in source material
2. **Extract or create requirement IDs** → Declared Short Name (`<'REQ-XXX-###'>`)
3. **Extract or generate descriptive names** → Declared Name (`'Descriptive Name'`)
4. **Extract primary requirement text** → Docstring
5. **Identify technical values** → Attributes with types and units
6. **Identify rationale and hierarchy** → RequirementMetadata (rationale and level)
7. **Identify additional context** → CustomRequirementMetadata (if needed beyond RequirementMetadata)
8. **Collect all validation/verification methods** → Create consolidated verification list
9. **Create verification usages** linking to appropriate requirements using Declared Names with correct path navigation
10. **Create relationships** (satisfy, allocate) using correct path navigation syntax
When cleaning up existing SysML v2:
1. **Ensure requirement definitions have both** Declared Short Names and Declared Names
2. **Update all references** to use Declared Names instead of Declared Short Names
3. **Fix path navigation** - use `::` for packages, `.` for nested members/features
4. **Add RequirementMetadata** with rationale and level where appropriate
5. **Replace generic `Real` types** with specific value types per mapping rules
6. **Add units** to attribute usages where missing
7. **Add type declarations** to attribute usages for clarity
8. **Review requirement structure** and reorganize content per placement rules
9. **Consolidate verifications** to eliminate duplication
## Critical Reminders
**For Requirement Definitions:**
- ✅ **USE BOTH** Declared Short Name (`<'ID'>`) AND Declared Name (`'Name'`)
- Format: `requirement <'REQ-XXX-###'> 'Descriptive Name' { }`
**For Requirement References:**
- ✅ **USE ONLY** Declared Name (`'Name'`)
- ❌ **NEVER USE** Declared Short Name (`<'ID'>`) in references
- Format: `verify Requirements::'Descriptive Name';`
- Format: `satisfy Requirements::'Descriptive Name' by 'System';`
**For Path Navigation:**
- ✅ **USE `::`** for package/namespace qualification
- ✅ **USE `.`** for nested features/members
- ❌ **DO NOT USE `::`** for navigating into nested elements
**For Requirement Metadata:**
- ✅ **USE RequirementMetadata** for rationale and hierarchy level
- Only create CustomRequirementMetadata if you need additional fields
- You can use both RequirementMetadata and CustomRequirementMetadata in the same requirement
**Summary Table:**
| Context | Use Short Name? | Use Declared Name? | Path Navigation | Example |
|---------|----------------|-------------------|-----------------|---------|
| Requirement definition | ✅ Yes | ✅ Yes | N/A | `requirement <'REQ-001'> 'Max Speed' { }` |
| Verify statement | ❌ No | ✅ Yes | `.` for nesting | `verify Req::'Parent'.'Child';` |
| Satisfy statement | ❌ No | ✅ Yes | `.` for nesting | `satisfy Req::'Name' by Part.'SubPart';` |
| Allocate statement | ❌ No | ✅ Yes | `.` for nesting, `::` for packages | `allocate Req.'Child' to Pkg::Part.'SubPart';` |
| Package qualification | N/A | ✅ Yes | `::` | `Requirements::TopLevel::'Name'` |
| Nested element | N/A | ✅ Yes | `.` | `'Parent'.'Child'.'Grandchild'` |
**Metadata Usage:**
| Field | Source | Use For |
|-------|--------|---------|
| `rationale` | RequirementMetadata | Why requirement exists, justification |
| `level` | RequirementMetadata | Hierarchy level (1=top, 2=derived, etc.) |
| Other fields | CustomRequirementMetadata | Project-specific metadata needs |
**Path Navigation Quick Reference:**
| What You're Doing | Operator | Example |
|------------------|----------|---------|
| Qualifying a package | `::` | `Requirements::Performance` |
| Accessing nested requirement | `.` | `'Parent Req'.'Child Req'` |
| Accessing nested part | `.` | `Drone.'Power System'` |
| Combined package + nesting | `::` then `.` | `System::Drone.'Power System'.'Battery'` |
- One verification can verify multiple requirements - consolidate to avoid duplication
- When in doubt about references, always use the Declared Name with single quotes, never the short name
- Always use RequirementMetadata for rationale and level; only add CustomRequirementMetadata for additional fields
- Always use `.` for navigating into nested elements, `::` only for package qualification