sysml-conventions

name	sysml-conventions
description	Use when writing SysML v2 code, asking about "SysML syntax", "naming conventions", "how to write" a part def or calc def, "imports", "syntax error", "parse error", "common mistakes", "pitfalls", "SysML patterns", attribute declarations, units notation, doc comment format, ADR-002, or definition vs usage rules. Provides the canonical syntax rules and patterns for SysML v2 modeling.
allowed-tools	Read, Grep, Glob
user-invocable	false

SysML Conventions

Canonical syntax rules, naming conventions, and patterns for writing correct SysML v2 models.

Core Principle

Every SysML element is either a definition (reusable type in library/) or a usage (specific instance in designs/). This distinction drives naming, file placement, and calculation architecture. When unsure, ask: "Could this apply to multiple designs?" Yes = definition, No = usage.

When to Reference

• /design-model — when specifying SysML structure and syntax in designs
• /implement-model — when writing SysML files (pre-flight syntax validation)
• /plan-model — when reviewing planned changes for syntax compliance
• /audit-models — when checking naming and syntax conformance

Naming Conventions

Element	Convention	Example
Definitions	'Title Case' with single quotes	part def 'Pump'
Usages	snake_case	part my_pump : 'Pump'
Attributes	snake_case	attribute flow_rate : Real
Packages	lowercase_underscores	package thermal_components

Quoted names are fine. Multi-word quoted names ('Fusion Power Plant', 'HIF Driver') are supported everywhere a name appears. Codegen sanitizes them to valid identifiers (Fusion_Power_Plant) — the identifier is derived, you do not write it. Use the readable quoted name.

Definition vs Usage Rule

Decision question: "Could this apply to multiple designs?"

// DEFINITION — reusable type (library/)
part def 'Heat Exchanger' {
    attribute heat_transfer_area : Real;
    attribute pressure_drop : Real;
}

// USAGE — specific instance (designs/)
part primary_hx : 'Heat Exchanger' {
    attribute heat_transfer_area : Real = 50.0 [m^2];
}

For directory placement of definitions and usages, see the project-structure skill.

Calculation Architecture (ADR-002)

calc def declarations belong in library/ only. Design files contain values and wiring.

Expression taxonomy for design files:

In Design Files	Status
Literal: = 3.0 [m]	OK
Static expr: = 3.14 * 2.0	OK
EXPOSE: = my_calc.output	OK
Inline FORMULA: = radius * 2.0 (same-part siblings)	OK for simple arithmetic
Computation on calc output: = calc.power * 0.95	VIOLATION — extract to calc def
Self-reference or dotted path: = self.x, = a.b.c	VIOLATION — extract to calc def

A design attribute may reference same-part siblings inline (a FORMULA) for simple arithmetic and unit conversions. For any real or reusable calculation — and always when the value depends on a calc output or another part — express it as a calc def in library/analyses/, not inline.

Standard Imports

package MyProject::Library::Components {
    import ScalarValues::*;    // Real, Integer, Boolean
    import ISQ::*;             // Physical quantities
    import SI::*;              // SI units

    // For cost aggregation over multiplicities:
    private import NumericalFunctions::sum;
}

Doc Comment Format

Every part def, calc def, and constraint def requires a doc comment:

part def 'Component' {
    doc /*
    Description of component.

    **Source**: Reference document
    **Reference**: path/to/source.pdf
    **Last Updated**: YYYY-MM-DD
    */
}

Required fields: Source (what authority), Reference (where to find it), Last Updated (when verified).

For doc comment field content requirements and citation patterns, see the source-traceability skill.

Common Pitfalls

Pitfall	Correction
attribute radius = 0.5 [m];	attribute radius : Real = 0.5 [m]; — always declare type
[m^3] written as [m³]	Use ASCII only: [m^3], [kg/m^3], [K] — syside rejects unicode
[°C] for temperature	Use Kelvin: = 300 [K] — convert Celsius, or use comment
:>> radius = 0.5 [m]; without parent	Redefinition (:>>) requires a parent type that declares radius
material : Material = SS316;	Use material : String = "SS316"; unless Material type is imported
Qualified names in calc expressions	Use local bindings: in x = other.value; not other.value inline
redefines when meaning specializes	redefines replaces a feature; :> specializes a type — different semantics
Missing imports for cross-file refs	Every cross-file reference needs explicit import or private import

Key Syntax Patterns

Conditional expressions:

attribute diff : Real = if x > y? x - y else y - x;

Constraints:

assert constraint TempLimit { temperature < 1000 [K] }

Cross-file binding:

private import OtherPackage::other_part;
calc my_calc { in value = other_part.exposed_attr; }

Semantic operators:

• = — fixed value (cannot be overridden)
• default := — default value (can be overridden by specialization)
• :>> — redefinition (replaces inherited feature)
• :> — specialization (extends a type)

Anti-Patterns

Instead of	Do
Real calculations inline, or computing on a calc output in a design attribute	Extract to calc def in library/analyses/ (inline FORMULA over same-part siblings is fine for simple arithmetic)
Unicode unit symbols (m³, °C)	ASCII equivalents (m^3, K)
Bare attributes without types	Always declare type: attribute x : Real
part x : 'Base' { ... } without import	Add import for the package containing 'Base'
Copying definitions into design files	Import from library; keep one source of truth
Skipping doc comments on definitions	Every def needs Source, Reference, Last Updated

Related Skills

• For doc comment field content requirements and citation patterns, see the source-traceability skill.
• For directory placement of definitions and usages, see the project-structure skill.

Reference Files

For extended code stencils and the pattern documentation index:

• references/stencils.md — Code stencils for common definition types and pattern doc index