Markdown-SysML Format Specification¶

Version: 1.0
Status: Draft
Reference: OMG SysML v2.0 (formal/2026-03-02)

Disclaimer: Syscribe is a modeling and documentation tool provided "as-is" without warranty of any kind. The authors and contributors accept no responsibility or liability for the use of this tool in safety-critical, life-critical, or mission-critical applications.

Output from Syscribe — including validation results, generated templates, traceability reports, and analysis artifacts — must be independently reviewed and verified by qualified engineers before use in any certification, regulatory submission, or safety case. Compliance with standards such as ISO 26262, IEC 61508, ISO 13849-1, ISO/SAE 21434, IEC 61025, DO-178C, or any other functional safety or cybersecurity standard remains the sole responsibility of the user and their organisation.

This tool does not replace a certified safety process, a qualified safety engineer, or a formal assessment body.

Table of Contents¶

1. Overview and Design Principles
2. Element Type Inventory
3. Common Frontmatter Schema
4. Directory and Namespace Conventions
5. Cross-Reference Syntax
6. Multiplicity and Cardinality Syntax
7. Inline vs File-per-Element Rules
8. Element-Specific Schemas
9. 8.1 Package and Namespace Elements
10. 8.2 Structural Elements: Part, Item, Occurrence, Individual
11. 8.3 Port and Interface Elements
12. 8.4 Connection, Binding, and Succession Elements
13. 8.5 Attribute and Enumeration Elements
14. 8.6 Flow Elements
15. 8.7 Action and Behavior Elements
16. 8.8 State Machine Elements
17. 8.9 Calculation Elements
18. 8.10 Constraint Elements
19. 8.11 Requirement Elements
    • 8.11.6 Native Requirement Type
20. 8.12 Case Elements (Analysis, Verification, Use Case)
    • 8.12.5 Native TestCase Type
    • 8.12.6 Native TestPlan Type
21. 8.13 Allocation Elements
22. 8.14 View, Viewpoint, and Rendering Elements
23. 8.15 Metadata Elements
24. 8.16 Diagram Elements
25. 8.17 Architecture Decision Records (ADR)
26. 8.18 Safety and Security Analysis Elements
    • 8.18.10 Asset (ISO/SAE 21434 §15.3)
27. 8.19 Release Baselines (Baseline)
28. Variability and Variation Points
29. 9.1–9.4 Structural Variation (isVariation / isVariant)
30. 9.5 Product Line Engineering Overview
31. 9.6 FeatureDef: Feature Model Element
32. 9.6a Single-file authoring: type: FeatureModel (REQ-TRS-FM-005)
33. 9.7 Feature Parametrization
34. 9.8 Configuration: Feature Selection
35. 9.9 Two-Level Feature Models
36. 9.10 appliesWhen: Conditional Model Elements
37. 9.11 PLE Validation Rules
38. 9.12 PLE Graph Edges
39. Worked Examples
40. Parser and Tool Contract
    • 11.10 Native-Element ID-Based Cross-Reference Resolution
    • 11.11 Computed Reverse Indices and Coverage
    • 11.12 Validation Rule Reference
41. Traceability Rules and Domain Conventions
42. 12.1 OSLC Link Direction Convention
43. 12.2 Requirement Breakdown and ADRs
44. 12.3 Leaf-Level Assignment Rule
45. 12.4 Parent Requirements Cannot Be Assigned
46. 12.5 Requirement Domain Classification
47. 12.6 Hardware/Software Architecture Independence
48. 12.7 Safety/Security Integrity Level Propagation
49. 12.8 Implementation Trace
50. 12.9 Allocation: Two Forms over One Edge Model
51. 12.10 User-Defined Link Types ([linkTypes], links:)
52. IEC 62443 Industrial Cybersecurity (Zone/Conduit Model)
53. Multi-Repository Model Composition
54. General-Purpose Trade Study
55. N² Interface Matrix
56. Change Impact Analysis
57. SBOM Generation
58. Review Records
59. Behavioral Coverage
60. ReqIF Export
61. Extensions to Existing Sections
62. 22.1 State Machine Completeness Validation (extends §8.8)
63. 22.2 Budget Expression Language (extends §8.9)
64. 22.3 ASIL/SIL Decomposition Pair Completeness (extends §12.7)
65. 22.4 Sequence Diagram Send/Receive Completeness (extends §8.16.8.3)
66. Native PlanningItem: Work-Item Tracking
67. Appendix A: Frontmatter Field Reference
68. Appendix B: Mapping of SysML Textual Keywords to type: Values

1 Overview and Design Principles¶

1.1 Core Concept¶

Every SysMLv2 model element is represented as a single .md file. The file has two parts:

• YAML frontmatter (between --- delimiters): declares the element's type, identity, and all structural/relational metadata.
• Markdown body: the documentation comment (doc annotation in SysML terms). This is the human-readable description of the element.

The directory hierarchy encodes namespace containment. A directory corresponds to a package. The _index.md file inside each directory carries that package's own metadata.

1.2 Design Principles¶

1. One element, one file. Every named SysML definition or usage that merits independent identity gets its own .md file. Exceptions are noted in Section 7.
2. Path is identity. An element's qualified name is derived algorithmically from its file path relative to the model root. The name: field in frontmatter overrides the display name but does not change the qualified name.
3. YAML for structure, Markdown for prose. Relationships, types, multiplicities, and flags go in frontmatter. Human-readable descriptions go in the body.
4. camelCase for all frontmatter keys. Consistent with SysML's own abstract syntax naming convention.
5. Qualified names use :: separator. This matches SysML's textual notation.
6. Defaults should match SysML defaults. Where SysML specifies a default (e.g., multiplicity 1..1 for owned usages, isAbstract: false), the Markdown-SysML format silently applies that default when the field is absent.

1.3 Relationship to SysMLv2¶

Markdown-SysML is a concrete syntax for SysMLv2 semantics, alternative to the official SysML textual notation (.sysml files). It trades the full expressiveness of SysML expressions for readability and LLM-friendliness. The following SysML features are fully represented:

• All definition and usage kinds (part, item, port, connection, interface, action, state, calculation, constraint, requirement, case, view, metadata, allocation, flow, enumeration, attribute, occurrence, individual)
• Specialization relationships (subclassification, subsetting, redefinition)
• Multiplicity, direction, abstract, variation, variant flags
• Port conjugation
• Requirements with subjects, satisfactions, verifications, concerns
• Actions with parameters, succession flows, control nodes
• State machines with transitions, triggers, guards
• Metadata annotation and user-defined keywords
• Import and alias declarations
• Viewpoint/view/rendering

The following are out of scope for this format (they require a formal expression language): - KerML/OCL constraint bodies (stored as opaque strings, not interpreted) - Calculation body expressions (stored as opaque strings) - Import filter conditions (stored as opaque strings)

2 Element Type Inventory¶

Every .md file must have a type: field drawn from the following table. The sysml_keyword column shows the corresponding SysML textual notation keyword sequence.

2.1 Definition Types¶

2.2 Usage Types¶

2.3 Namespace/Package Types¶

2.4 Relationship Types¶

Relationship elements are directed relationships between named elements. Unlike definitions and usages, they are not classifiers or features — they live at package level, have no typedBy: field, and cannot be owned as sub-features of another element.

Specializations of Dependency (e.g., Realization, Derivation) are expressed via supertype: referencing library types rather than requiring distinct type: values:

---
type: Dependency
name: EngineControlRealization
supertype: SysML::Dependencies::Realization
clients:
  - LogicalArch::EngineControl
suppliers:
  - PhysicalArch::EngineControlUnit
---
The logical engine control function is realized by the physical ECU.

Dependency-specific fields:

Placement convention: Dependency files live either alongside the primary client element or in a dedicated Dependencies/ package when they cross package boundaries.

2.5 Diagram Types¶

Diagrams are visual representations of model elements. They are not SysML language constructs but a format extension for diagrams that trace back to the model elements they depict.

2.6 Record Types¶

Record elements are engineering-process artifacts that live in the model directory tree for traceability. They have no SysML counterpart. All are id-identified: the file is <id>.md, cross-references resolve by id, and name is a required free-prose label.

2.7 Safety and Security Analysis Types¶

Native, id-identified element types for functional safety (ISO 26262, IEC 61508, ISO 13849-1), automotive cybersecurity (ISO/SAE 21434), and industrial cybersecurity (IEC 62443).

The native Requirement (REQ-*, §8.11.6), TestCase (TC-*, §8.12.5), FeatureDef (FEAT-*), Configuration (CONF-*) and FeatureModel types are listed with the usage types in §2.2. syscribe spec types prints the list known to the installed tool.

3 Common Frontmatter Schema¶

This section defines every frontmatter field that may appear on any element file. Element-specific additional fields are defined in Section 8.

All fields are optional unless marked Required. Defaults listed apply when the field is absent.

3.1 Identity Fields¶

Name resolution rule: The element's qualified name segment is always the filename stem (filename without .md), or the directory name for a package; name: is only a label and never changes the qualified name. A name-identified element whose name: differs from its stem raises W058 (exempt: a name: containing a space or starting with <, and FeatureModel / FMEASheet elements); references must use the stem. The full qualified name is the :: join of all ancestor directory names and the element's own stem, starting below the model root (the root's own name is never part of a qualified name).

Basic-name grammar (naming convention). Each qualified-name segment — the file stem (or directory name) of an element — should be a SysMLv2 basic name: ^[A-Za-z_][A-Za-z0-9_]*$ — a letter or _, then letters, digits or _. Hyphens, spaces and other punctuation are not permitted: a hyphen is the subtraction operator in the appliesWhen: and parameterConstraints expression grammars, so a name like Anti-Lock parses fine as a file/qname but cannot be referenced in those expressions (it raises E209). A non-basic stem raises warning W042 (it checks the file/directory stem, not the name: label); rename using _ or CamelCase (Anti-Lock → Anti_Lock / AntiLock). Stable ids (REQ-*, TC-*, …) are exempt — they have their own grammar and legitimately contain -. (SysMLv2 unrestricted quoted names, e.g. 'Anti-Lock', are not supported.)

This applies to every qualified-name segment, including package / directory names — both a package declared with an _index.md and a plain directory without one. Requirements and other stable-id elements are unaffected (their REQ-*/TC-* ids are exempt); only the directories that contain them must be basic names.

name is the single, universal label field. Every element type — id-identified and name-identified alike — carries name as its one human-readable label (SysMLv2 declaredName). There is no longer a per-identity-class split between name and title.

• name is the label on all types. It is optional in general but required on every type that previously required a label — the id-identified types: Requirement, TestCase, TestPlan, Configuration, ADR, ConfirmationMeasure, HazardousEvent, SafetyGoal, DamageScenario, ThreatScenario, CybersecurityGoal, SecurityControl, VulnerabilityReport, TARASheet, FaultTree, FaultTreeGate, FaultTreeEvent, FMEASheet, FMEAEntry, AttackTree, AttackTreeGate, AttackStep, Argument, AssumptionOfUse. For these id-identified types name is free prose (spaces and punctuation allowed; the basic-name grammar W042 does not apply, because identity is the stable id). For name-identified types (all SysML structural types — PartDef, Part, Port, ActionDef, … — plus Package, Diagram, and FeatureDef) name is the label, and — by convention — should equal the file/directory stem that forms the qualified-name segment (a differing name: is W058); the basic-name grammar W042 is applied to the stem.
• id (the stable shortName, such as REQ-*, TC-*, HE-*) remains the identity of the id-identified types — files stay <id>.md and cross-references resolve by id. The id axis and the name (label) axis are independent.
• title is removed. It is no longer a recognized label field on any element. Declaring a title: on any element — id-identified or name-identified — is error E025 ("the title field is removed — rename it to name"). Error E024 (formerly: a name: on an id-identified type) is retired — name is now the correct, required label on those types.

FeatureDef is name-identified (its name is its label; its file stem is the qualified-name segment) and also carries a mandatory stable id (its FEAT-* shortName, §9.6 — a feature with no id is E201). The id axis (shortName) and the name (label) axis are independent: under the unified rule a FeatureDef carries name + id and no title.

External references (extRef). A Syscribe element often mirrors an artifact that lives in another tool. extRef: records that correspondence as one or more opaque strings — a URI (https://dng.example/resources/4521) or a tool-qualified token (DNG:4521, cameo://model/Engine#id-99) — given either as a single string or a list. The field is optional and its syntax is unconstrained (external systems use widely varying identifier schemes). extRef is an external pointer: it is not a model cross-reference and is never a valid target for supertype:, verifies:, derivedFrom:, connections, etc. Look up the element(s) that carry a given reference with syscribe -m <root> extref <ref>. The same extRef value on two or more elements is permitted but warned (W028), since an external artifact normally maps to a single element.

# any element — represents DNG requirement 4521 and a Cameo block
extRef:
  - "DNG:4521"
  - "cameo://model/Engine#id-99"

On a TestCase, an extRef is also the key a test tool can put in a result: ingest-results --format records joins a record whose testCase is that value to the TestCase (REQ-TRS-RESJOIN-001). Because W028 keeps it unique, a tool-side test identifier such as RIG:SYS-012 is a good value.

3.2 Classification Flags¶

Normative note on isReference and compositeness:

isReference: true is equivalent to the SysML ref keyword and marks a usage as referential — the containing element does not own the referenced element, it merely holds a reference to one that exists independently.

Default compositeness by context: - Usages owned inside a PartDef, ItemDef, ActionDef, or similar definition → composite (isReference: false) by default. - Usages directly owned by a Package → referential by default.

Certain usage kinds imply isReference: true regardless of the field value. These kinds are always referential; setting isReference: false explicitly on them is not currently diagnosed:

3.3 Typing and Specialization¶

Note on supertype vs typedBy: Definitions use supertype (subclassification). Usages use typedBy (feature typing). Both support a single string or a YAML list for multiple supertypes/definitions.

3.4 Multiplicity¶

3.5 Direction¶

3.6 Inline Features¶

3.6.1 Inline Feature Schema¶

Each entry in features: is a map with these fields:

3.7 Packaging and Import Fields¶

3.7.1 Import Schema¶

Each entry in imports: may be a plain string (shorthand) or a map:

Shorthand: a qualified name string, optionally suffixed with ::* (namespace import) or ::** (recursive import).

imports:
  - VehicleSystem::*
  - ISQ::**

Full map form:

Examples:

imports:
  # shorthand — private import of all direct members
  - VehicleSystem::*

  # public import — re-exports ISQ members downstream
  - target: ISQ::**
    isPublic: true

  # filtered import — only abstract members
  - target: VehicleSystem::*
    filter: "isAbstract"

  # filtered import — only members annotated as normative
  - target: ISQ::**
    filter: "#(ModelingMetadata::Normative)"

Note on isPublic: A public import in SysML makes the imported names visible to any namespace that imports the importing namespace. A private import (the default) makes them visible only within the importing namespace itself.

3.7.2 Alias Schema¶

Each entry in aliases: is a map:

Note: aliases: may appear on any element, not just packages. When declared on a non-package element (e.g., a PartDef), it creates a local alias name for another element within the scope of the declaring element's namespace — useful for shortening deep cross-references within a definition body.

3.8 Metadata Application¶

Each entry in metadata: is a map:

Example:

metadata:
  - type: ModelingMetadata::StatusInfo
    status: approved
    approver: "Jane Smith"

3.9 Dependency¶

3.10 Annotation Fields¶

These fields control how the Markdown body is interpreted as a documentation annotation.

about: usage — for cross-cutting notes that apply to one or more elements without duplicating text. The comment is its own file (e.g. model/VehicleSystem/SafetyNote.md, never a package _index.md); its type: is nominal, since a comment defines no element:

---
type: Package        # nominal — the file is a comment, not an element
name: SafetyNote
about:
  - VehicleSystem::Engine
  - VehicleSystem::Transmission
  - VehicleSystem::Brakes
---
This subsystem group requires safety analysis per ISO 26262. All three elements
share the same hazard classification and must be reviewed together.

locale: usage — for multi-language documentation, create one file per language. The primary file defines the element (its own body may be tagged with locale:); every other language is a locale variant file that sets locale: and qualifiedName: — the qualified name of the element it documents. A variant is not an element: its file name does not become a qualified name, so any file name works (by convention <Stem>.<locale>.md next to the primary file).

# model/VehicleSystem/Engine.md  (English — primary file, also defines the element)
---
type: PartDef
name: Engine
---
The engine converts fuel energy into mechanical power.

# model/VehicleSystem/Engine.de.md  (German — documentation-only variant)
---
type: PartDef
qualifiedName: VehicleSystem::Engine   # points to the same element
locale: de
---
Der Motor wandelt Kraftstoffenergie in mechanische Leistung um.

about: versus a locale variant's qualifiedName:. Both attach a file's body to other elements, but they are different annotations and neither replaces the other: a locale variant (locale: + qualifiedName:) is the element's own documentation, translated, for exactly one element — at most one per locale; an about: file is an additional comment on one or more elements, any number of which may name the same element. A file with locale:, qualifiedName: and about: is a locale variant; its about: is ignored (W051).

Parser contract for about: and locale:: - A file with about: (other than a package _index.md, and not a locale variant) is an about: comment: it contributes its Markdown body — with its name: (default: the file stem), source file and optional locale: — as a note on every listed element, and does not define a model element. Entries resolve like cross-references, by qualified name and then by stable id (so a comment can name REQ-*/TC-* ids), and against synthesized elements too. show prints one Note: <name> section per comment on each listed element. - An about: entry that resolves to no element is error E027; the comment still attaches to the entries that resolve, and when none resolves the file is kept as its own element so it is not silently lost. - A comment carries only type, name, about and locale; any other field is ignored with warning W052, as is a non-string or empty about: entry. about: on a package _index.md is ignored with W052 — the _index.md defines its package and is never a comment. - A file with both locale: and qualifiedName: is a locale variant: it contributes its Markdown body as a locale-tagged doc annotation of the element whose qualified name equals qualifiedName:, and does not define a model element of its own. A qualifiedName: that resolves to no element is error E026 (the file is then treated as its own element so it is not silently lost). - A variant does not redefine the element's structure. It may carry only type, name, locale and qualifiedName; any other field, or a type: that differs from the target's, is ignored with warning W051. - Multiple locale files for the same element are all valid; a parser collects them as a map of locale → doc string (show prints one Documentation (<locale>) section per entry). One document per locale: a second variant for a locale the element already has (from an earlier variant in walk order, or the element's own locale:) is ignored with warning W051. - A file with locale: but no qualifiedName: is an ordinary element whose own body is tagged with that locale. - qualifiedName: is never an identity override (§3.1): the qualified name is purely path-derived (§4.5, §11.3).

3.11 Constraint Fields¶

These fields may appear on any element, not only on RequirementDef/Requirement. When used outside a requirement context, they declare informal constraints on the element.

Note: On RequirementDef and Requirement, these fields have full structural semantics (formal constraint clauses; §8.11.1). On other element types, they are treated as informal annotations and do not affect typing or redefinition.

3.12 Representation Field¶

3.13 Product Line Conditioning Field¶

appliesWhen: may appear on any element type, including Requirement, PartDef, Part, TestCase, Allocation, ActionDef, Connection, Diagram, and all others — and on a Package, where it applies transitively to the whole subtree (the effective condition; §9.10, error E228 enforces one declaration per path). It is the sole mechanism by which model elements are conditioned on feature selections. A string value is either a single FeatureDef reference or a boolean expression ("A and B", "A or B", "not A", parentheses; precedence not > and > or); a list means all listed features must be selected (AND semantics). Every operand must resolve to a FeatureDef and the expression must parse — otherwise error E209 (§9.10). Feature qualified names use :: between every segment (SystemFeatures::Propulsion::HexRotorPropulsion); . is reserved for the feature/parameter boundary in parameter references (§9.7) and is not valid inside an appliesWhen: operand.

3.14 Domain Classification¶

These fields encode the engineering domain of an element and are used to enforce hardware/software architecture independence (§12.6).

When domain: is not set, system is assumed — the element is domain-agnostic and can interoperate with both hardware and software elements.

isDeploymentPackage: true implies domain: software; a parser should warn (W304) if isDeploymentPackage: true is combined with domain: hardware.

3.15 Custom Fields¶

custom_fields: is the intentional, addressable home for user-defined metadata on any element. It is the only sanctioned channel for author-defined data: an unrecognised top-level key is still captured by the parser's catch-all (and so survives a round-trip), but it is no longer silent — it raises warning W047 (§3.17) directing you to move the data here. Data placed under custom_fields: is recognised: preserved, queryable (custom.<key>), shape-checked, and exempt from W047.

custom_fields:
  supplier: Bosch
  costCenter: PWT-4471
  maturity: prototype
  reviewCycle: 3
  partNumbers: [A-1001, A-1002]   # lists of scalars allowed

Rules:

• Values must be a scalar (string/number/bool/null) or a list of scalars. A nested map, or a list containing a non-scalar, raises warning W041 (custom field '<key>' must be a scalar or a list of scalars). W041 is advisory — never a hard error — and CI-gateable via --deny W041.
• The map serialises in sorted key order so writes do not produce noisy round-trip diffs.
• An element with no custom_fields: is unaffected; the feature adds no findings to models that do not use it.
• custom_fields: values are never resolved as references. A relationship to another element belongs in links: under a declared link type (§12.10), where it is resolved, validated and traversable.
• Custom fields are read-only in the web UI and CLI show; they are not editable via PUT /api/elements/<qname>.

Querying (CLI ls / find / list) — the --where predicate addresses custom fields via the custom.<key> namespace:

--where composes (AND) with the existing type / --tag / --status filters, and multiple --where predicates are ANDed. An unparseable predicate is a usage error.

3.16 Display Order¶

displayOrder: is a generic, first-class numeric field, accepted on every element type, that controls the order in which an element is presented alongside its peers in an ordered output. It exists to decouple presentation order from identity: stable identifiers (REQ-*, qualified names) are opaque and must never change, so they cannot be renumbered to express the order in which elements — most importantly requirements — are meant to be read.

---
type: Requirement
id: REQ-SCHED-001
name: "Scheduler determinism"
status: draft
displayOrder: 20        # read after displayOrder 10, before 30
---

Rules:

• Sort is ascending by displayOrder; an element without displayOrder sorts after every element that has one, and remaining ties break on the element's stable identifier (id else qualified name).
• The value is a number and may be a decimal, so a new element can be inserted between two neighbours (displayOrder: 15 between 10 and 20) without renumbering. Convention: leave gaps (10, 20, 30, …).
• displayOrder governs presentation order in the Requirements section of the Markdown validation report, the Requirement rows of the coverage matrix, and the containment tree of the web UI. It never affects validation, identity, or cross-reference resolution — it is purely a presentation hint.
• An element with no displayOrder: is unaffected; the field adds no findings to models that do not use it. (REQ-TRS-ORDER-001)

3.17 Frontmatter Schema Strictness¶

The frontmatter schema is fixed: the parser recognises a defined set of field names (the fields documented in this specification) and binds each to a typed slot. A top-level key that is not a recognised field is captured by an anonymous catch-all — it round-trips through writes, but it takes no part in validation or semantics.

Because such a key is otherwise invisible, every unrecognised top-level key raises warning W047:

Rules:

• W047 is advisory — a warning, never a hard error — so pre-existing models keep validating. Gate it in CI with --deny W047 to make an unrecognised field fail the build.
• It fires per unrecognised key, naming the key and the element's file.
• Keys under custom_fields: are exempt — that is the sanctioned home for author-defined data (§3.15). Recognised schema fields never trigger it.
• links: (user-defined link types, §12.10) is a recognised schema field and never triggers it; its keys are validated against [linkTypes] instead (E630).
• derive: (§3.18) is a recognised schema field and never triggers it.
• The most common cause is a typo in a real field name (reqDomian for reqDomain, verifis for verifies): the misspelling was previously accepted and the value silently discarded. W047 surfaces the mistake instead of losing the data quietly.

(REQ-TRS-SCHEMA-001.)

3.18 Derived Fields (derive:)¶

derive: is a recognised field accepted on every element type. It is a mapping of field name → formula string; the tool evaluates each formula after the model is walked and records the value as a computed (read-only) field of the element, shown under Derived Fields by show. (REQ-TRS-DERIVE-001..005.)

derive:
  wcetConsumed: sum(children.custom_fields.wcet)
  wcetHeadroom: self.custom_fields.wcetBudget - self.wcetConsumed

Formula grammar: numbers, "strings", self.<field> / self.custom_fields.<key>, elements["Qualified::Name"].<field>, the aggregates sum · max · min · count · collect over children or parent (optionally .<field>), + - * /, parentheses and the null-coalesce ??.

Rules:

• Dependency order. A derived field is evaluated after every derived field it reads — via self.<field>, elements["Q"].<field>, or a children/parent aggregate over <field> — so a reference always sees the computed value, whatever the element or entry order. Independent fields evaluate in file-walk, then block (top-to-bottom), order.
• Cycles (E504). A field that depends on itself — directly (a: self.a + 1), through other entries of the same block, or through other elements — is a cycle. Each cycle is reported as error E504 once on every element file taking part, naming the cycle (X.a → Y.b → X.a); the fields in it are not evaluated (absent from the derived fields). A field outside the cycle that reads a cyclic field still evaluates and reads it as absent (use ?? to supply a default).
• Malformed input (E505). A formula that does not parse, a derive: value that is not a mapping, and a formula value that is not a string are each E505; the field is not evaluated.
• Unknown element (E506). An elements["QName"] naming no element is E506; the reference evaluates to null.
• derive: is a recognised schema field: it never raises W047 (§3.17).

3.19 Suspect-Link Baselines (traceBaselines:)¶

A suspect link is a trace link whose target changed after the link was last reviewed (ADR-SYS-SUSLINK-001). The element that holds the link (the source, §12.1) may record, for each reviewed target, a hash of the target's content at review time:

Frontmatter excerpt (the TestCase's Gherkin body is omitted; the hash is illustrative):

---
type: TestCase
id: TC-BRK-001
name: Brake response time
status: active
testLevel: L2
verifies: [REQ-BRK-001]
traceBaselines:
  REQ-BRK-001: blake3:9f2c1e0d4b7a6c5e8d3f1a2b4c6d8e0f1a3b5c7d9e1f2a4b6c8d0e2f4a6b8c0d
---

The map is written by tooling, not by hand: syscribe suspect accept <source> <target> baselines one reviewed link, suspect accept --all re-baselines every suspect link, and suspect accept --all-unbaselined baselines every link that has no baseline yet (onboarding; it never overwrites an existing entry). Links tracked: verifies, derivedFrom, satisfies, refines, implementedBy, subsets, supertype, redefines, typedBy, breakdownAdr, hazardRef, mitigatedBy, supports, confirms, scalar evidence entries, a ViewpointDef's satisfiedBy, and user-defined links: whose type does not declare suspect = false (§12.10.6).

Validation. validate recomputes each baselined target's projection hash; a mismatch is warning W090 (suspect link — review the source, then re-run suspect accept). The feature is opt-in and additive: a link with no baseline raises nothing in validate and is listed only by suspect list, and a baselined target that no longer resolves is left to the unresolved-reference checks rather than reported as W090. Gate CI on stale links with --deny W090.

4 Directory and Namespace Conventions¶

4.1 Model Root¶

The model root is a directory chosen by the user (e.g., model/). All qualified name derivation is relative to this root. A parser is initialized with the path to the root.

The root directory may contain an _index.md with type: Namespace or type: Package. If absent, the root is treated as an anonymous root namespace.

4.2 Package Directories¶

A directory maps to a SysML package. The package's qualified-name segment is always the directory name. A name: in the directory's _index.md is only the package's human-readable label (display name); it never changes the qualified name (§11.3).

model/
  _index.md              # type: Namespace  — root namespace
  VehicleSystem/
    _index.md            # type: Package, name: VehicleSystem
    Chassis.md           # type: PartDef   — qname: VehicleSystem::Chassis
    Powertrain/
      _index.md          # type: Package
      Engine.md          # qname: VehicleSystem::Powertrain::Engine

4.3 _index.md Schema¶

An _index.md file may carry any fields from Section 3, plus the following package-specific fields:

Membership is generated, never authored (ADR-SYS-PKG-001, GH #120). A package's members are exactly the elements in its directory. Tools present that list from the directory itself — show <package> prints a ## Members (N) table (id or qualified name, type, name, status), and the web UI detail panel and export-html package pages show the same list — so it can never drift from the files on disk. The _index.md body should state the package's purpose and scope (the why), not enumerate its members (the what). lint-docs reports advisory W103 when an _index.md body mentions three or more distinct stable ids that resolve to the package's own direct members. Summary tables that carry genuine cross-element analysis (e.g. a HARA hazard → goal → ASIL table) remain legitimate; W103 is a prompt to check, not a rule.

4.4 Library Packages¶

A library package uses type: LibraryPackage. Library packages are treated identically to regular packages for qualified name resolution, but tools may display them differently and they implicitly export all their members publicly.

# model/ISQ/_index.md
---
type: LibraryPackage
name: ISQ
---
International System of Quantities domain library.

4.5 Name Collision Rules¶

1. The qualified name is purely path-derived (§11.3): the element's last segment is its filename stem, and each package segment is a directory name. The name: field is only the element's label (SysML declaredName used for display); it never changes the qualified name and never participates in collision detection.
2. Because the qualified name comes from the path, two elements in the same directory cannot share a qualified name — the file system already forbids two files with the same stem. Two elements in the same directory may carry the same name: label without error.
3. For name-identified types, author name: equal to the filename stem so the label and the identity segment agree; the stem (not name:) is what :: references resolve against. For id-identified types (Requirement, TestCase, …) the stem is the stable id and name: is free prose.
4. A file named _index.md is never assigned its own qualified name segment; it represents the containing directory's package.
5. A qualified name produced by more than one element — e.g. a file Foo.md next to a directory Foo/ that has an _index.md, or a synthesized element (a FeatureModel sheet entry, an FMEA/TARA row, a plugin- or annotation-emitted element) colliding with a file-backed one — is error E108.

4.6 Visibility Within Directories¶

By default, all elements in a directory are public members of that package. Set visibility: private in frontmatter to restrict membership visibility.

4.7 Standard Library Package Inventory¶

The following packages are part of the SysML v2 standard library. A parser must not error on references to these packages even if their .md files are not present in the model directory — they are resolved from the built-in library.

Auto-imported at model root (always available without explicit import):

These two packages have a fully known membership, so a type reference to a recognised member (e.g. typedBy: ScalarValues::Real, supertype: Base::DataValue) resolves cleanly — it raises no unresolved-reference finding — while a reference into one of them to a member it does not declare (e.g. ScalarValues::Flota) is flagged as a likely typo with warning W043, listing the package's known members. The import-only packages below are not enumerated, so references into them are never W043 and resolve leniently as standard-library references (W404 applies only to an operation's parameter and return types, §8.3).

Available via explicit import:

Curated recognition of ISQ and SI (open/lenient tier). Although ISQ/SI are large open packages, the tool recognises a curated subset — the ISQ quantity-value types (MassValue, ForceValue, EnergyValue, VoltageValue/ElectricPotentialValue, …) and the SI units (the seven base units plus common derived units), accepting both the full name (SI::kilogram) and the common symbol (SI::kg, or a bare kg). A recognised member resolves cleanly; an unrecognised ISQ/SI member on an inline feature's typedBy: or unit: is warning W057 (a likely typo, since the tool's tables are a subset of the library — never W043, unlike the closed ScalarValues/Base packages), and the unit: field stays fully permissive (non-SI/domain units like USD, kWh, percent are accepted). When an element/feature declares both a recognised quantity type (typedBy: ISQ::…) and a recognised unit (unit: SI::…), the tool checks their physical dimensions agree (over the seven SI base quantities) and raises warning W044 on a mismatch (e.g. ISQ::MassValue with unit: SI::metre).

5 Cross-Reference Syntax¶

5.1 Absolute Qualified Names¶

An absolute qualified name starts from a top-level package name:

typedBy: VehicleSystem::Powertrain::Engine
supertype: Requirements::FunctionalRequirementDef

5.2 Relative References¶

A simple unqualified name resolves within the current element's containing package first, then outward through enclosing namespaces:

typedBy: Engine        # resolves within current package first

A ./-prefixed name explicitly means "sibling in the same directory":

subsets: [./drivetrainPort]

5.3 Wildcard and Namespace Imports¶

In imports: fields:

imports:
  - ISQ::*
  - ScalarValues::**

5.4 Aliases¶

Declare an alias to create a short local name:

aliases:
  - name: MV
    for: ISQ::MassValue

Then reference it as MV within the same package.

5.5 Self-Reference¶

Use self to refer to the element defined by the current file, within constraint or expression bodies (opaque strings only; not used in structural YAML fields).

5.6 Feature Chains¶

Feature chains (dot-notation paths through usages) are written using . within qualified names that appear in connections:, flowConnections:, and successionConnections: entries. For example:

connections:
  - from: engine.exhaustPort
    to: exhaustSystem.inletPort

6 Multiplicity and Cardinality Syntax¶

The multiplicity: field and the multiplicity sub-field inside features: entries are quoted strings conforming to the following grammar:

multiplicity  ::= bound | bound ".." bound
bound         ::= integer | "*" | qualified-name
integer       ::= [0-9]+
qualified-name ::= name ("::" name)*
name          ::= [A-Za-z_][A-Za-z0-9_]*

Common forms:

Rules: - The string must be quoted in YAML to avoid misparse (e.g., "1" not bare 1). - If only a single token is given ("4" or "maxItems"), both bounds equal that value. - * is the only shorthand for an unbounded upper; it may not appear as the lower bound. - The lower bound must resolve to a non-negative integer at evaluation time. - When a bound is not a valid integer literal or *, it is treated as a qualified-name reference and resolved during the same cross-reference resolution pass as all other qualified names (§11.3). The tool does not currently resolve bound names: an unresolved name bound is not reported (only a malformed bound such as *..3 or a negative number is E118).

Feature-reference bound example:

# Vehicle.md
features:
  - name: passengers
    typedBy: Passenger
    multiplicity: "0..maxPassengers"   # upper bound from a sibling feature

  - name: maxPassengers
    typedBy: ScalarValues::Integer
    value: "8"

7 Inline vs File-per-Element Rules¶

7.1 Use Inline features: When¶

• The feature is a simple scalar attribute (a single typed_by with a primitive or library type, no sub-features of its own).
• The feature has no documentation body worth a separate file.
• The feature has no metadata of its own beyond what fits on one or two lines.
• The feature is used only within this one definition and is not referenced by qualified name from other files.

Examples of inline-suitable features:

features:
  - name: mass
    typedBy: ISQ::MassValue
    unit: SI::kg
  - name: length
    typedBy: ISQ::LengthValue
    unit: SI::m
  - name: status
    typedBy: VehicleStatus    # an EnumerationDef in the same package

7.2 Use a Separate .md File When¶

• The feature has its own sub-features (nested parts, ports, attributes).
• The feature has significant documentation.
• The feature is a PortDef, ActionDef, StateDef, or other definition reused across multiple parent definitions.
• The feature is a usage that itself owns usages (a composed sub-part, a sub-action, a sub-state).
• The feature needs its own metadata annotations.
• The feature must be reference-able by qualified name from other files.

7.3 Attribute Definitions¶

Simple AttributeDef elements that define a named data type (e.g., Temperature, Pressure) always get their own file so they can be typed-by from multiple locations.

Primitive inline literals may be expressed as:

features:
  - name: maxTemperature
    typedBy: ScalarValues::Real
    value: "200.0"
    unit: SI::degC

8 Element-Specific Schemas¶

8.1 Package and Namespace Elements¶

8.1.1 _index.md for Package¶

---
type: Package               # or LibraryPackage, Namespace
name: VehicleSystem         # optional; defaults to directory name
isAbstract: false
imports:
  - ISQ::*
  - ScalarValues::*
aliases:
  - name: Real
    for: ScalarValues::Real
filterCondition: ""         # optional KerML filter expression (opaque)
metadata:
  - type: ModelingMetadata::StatusInfo
    status: draft
---
The VehicleSystem package contains all definitions and usages
for modelling a generic vehicle.

8.2 Structural Elements: Part, Item, Occurrence, Individual¶

8.2.1 PartDef — Part Definition¶

Defines a class of physical or logical system components.

Type-specific additional fields:

performs: field — string shorthand and full map form:

A string entry expands to {typedBy: <string>} with all other fields at their defaults. The full map form supports all perform-action usage properties:

performs:
  - VehicleBehavior::ProvidePower          # shorthand — expands to {typedBy: ...}

  - name: driveAction                      # full form
    typedBy: VehicleBehavior::RegulateSpeed
    multiplicity: "1"
    redefines: [Parts::Part::performedActions]
    bindingConnections:
      - left: driveAction.inputSpeed
        right: self.currentSpeed

Example (model/VehicleSystem/Vehicle.md):

---
type: PartDef
name: Vehicle
isAbstract: true
supertype: Parts::Part
features:
  - name: mass
    typedBy: ISQ::MassValue
    unit: SI::kg
  - name: speed
    typedBy: ISQ::SpeedValue
    unit: SI::m_per_s
    isDerived: true
  - name: fuelCapacity
    typedBy: ISQ::VolumeValue
    unit: SI::L
connections:
  - from: engine.powerOut
    to: drivetrain.powerIn
    typedBy: PowerConnection
performs:
  - VehicleBehavior::providePower
---
Abstract definition of a vehicle with mass, speed, and fuel capacity.
All concrete vehicle types specialize this definition.

8.2.2 Part — Part Usage¶

A usage of a PartDef in a specific context.

Type-specific additional fields:

Example (model/VehicleSystem/vehicle_b.md):

---
type: Part
name: vehicle_b
typedBy: Vehicle
multiplicity: "1"
features:
  - name: engine
    type: Part
    typedBy: Powertrain::FourCylinderEngine
    multiplicity: "1"
  - name: transmission
    type: Part
    typedBy: Powertrain::AutomaticTransmission
    multiplicity: "1"
connections:
  - from: engine.powerOut
    to: transmission.powerIn
---
Specific vehicle configuration B with a four-cylinder engine
and automatic transmission.

8.2.3 ItemDef and Item¶

Items classify things that may flow through or be contained in a system (as opposed to the structural parts). Schema is identical to PartDef/Part with type: ItemDef / type: Item.

Notable difference: Items are always referential; isReference defaults to true for item usages inside attribute definitions and usages.

8.2.4 OccurrenceDef and Occurrence¶

Occurrences model things with temporal extent. An OccurrenceDef can define time-slice structure.

Note: OccurrenceDef and Occurrence are the base occurrence types. Use them for abstract occurrence hierarchies that do not specialize any of the more specific kinds (PartDef, ItemDef, ActionDef, StateDef, etc.). All more specific definition types in SysML ultimately specialize OccurrenceDef at the KerML level.

Additional fields for OccurrenceDef:

Example (model/Lifecycle/VehicleLifecycle.md):

---
type: OccurrenceDef
name: VehicleLifecycle
supertype: Occurrences::Occurrence
timeSlices:
  - name: operatingPhase
    typedBy: VehicleSystem::Vehicle
    isPortion: true
  - name: maintenancePhase
    typedBy: VehicleSystem::Vehicle
    isPortion: true
---
Models the full lifecycle of a vehicle from manufacture to disposal.

8.2.5 IndividualDef and Individual¶

Individuals represent specific instances with a fixed identity.

---
type: Individual
name: myVehicle2026
typedBy: VehicleSystem::Vehicle
isIndividual: true
features:
  - name: vehicleId
    typedBy: ScalarValues::String
    value: '"VIN-1234567890ABCDEF"'
  - name: manufactureDate
    typedBy: ISQ::DateTime
---
The specific vehicle with VIN 1234567890ABCDEF manufactured in 2026.

8.3 Port and Interface Elements¶

8.3.0 Concepts and decision guide¶

Ports and interfaces are the most error-prone area to model. Orient first, then use the schemas below.

Mental model (SysML v2). A PortDef is a reusable kind of connection point that carries directed features (in/out/inout). A Port is a usage of a PortDef on a part — it lives in the part's features: list with type: Port and typedBy: the PortDef. A connection wires two ports together. An InterfaceDef is a kind of ConnectionDef — in SysML v2, "an interface is simply a connection all of whose ends are ports" (§7.14) — so use it to package a reusable, compatible pairing of two ports; a plain ConnectionDef connects arbitrary features/parts, not necessarily ports.

Which construct → when:

Conjugation. The receiving end of a connection is the conjugate of the sending end: every directed feature flips direction (in↔out; inout is self-conjugate — SysML v2 §7.12.3, "each port definition has a conjugated port definition whose directed features are conjugate to those of the original"). Express it either with a dedicated conjugate PortDef (conjugates: <the source PortDef>) for reuse, or with isConjugated: true on the Port usage / interface end for a one-off. Connected directed features must be conjugate-compatible — that is how a supplier's out lines up with a consumer's in.

End-to-end shape. A supplier PartDef exposes a Port typed by a source PortDef; a consumer PartDef exposes a Port typed by the conjugate PortDef; an InterfaceDef ties the two PortDefs as its ends; a parent PartDef holds both as sub-parts and wires them in connections: (from: supplier.outPort, to: consumer.inPort, typedBy: the InterfaceDef). A FlowDef/flowConnections: may carry the items that move across.

8.3.0a Data records versus flowing items (E123)¶

A usage is typed by a definition of the matching kind (E123 otherwise): Attribute ← AttributeDef or EnumerationDef; Item/Part ← ItemDef/PartDef/OccurrenceDef/…; Port ← PortDef; Connection ← ConnectionDef/InterfaceDef; Interface ← InterfaceDef; Action ← ActionDef; State ← StateDef (and so on for the other usage kinds; Constraint and Calculation also accept a PartDef/ItemDef context).

An Attribute typed by an ItemDef is the common mistake. Do not silence it by changing the usage to type: Item unless the thing really flows; define the record as an AttributeDef. The E123 message states this remedy.

8.3.1 PortDef — Port Definition¶

Defines an interaction point. Ports can be conjugated.

Type-specific additional fields:

Example (model/Interfaces/PowerPortDef.md):

---
type: PortDef
name: PowerPortDef
features:
  - name: voltage
    typedBy: ISQ::VoltageValue
    direction: out
    unit: SI::V
  - name: current
    typedBy: ISQ::ElectricCurrentValue
    direction: out
    unit: SI::A
---
A port definition representing an electrical power interface.

Conjugated Port Example (model/Interfaces/PowerPortReceiverDef.md):

---
type: PortDef
name: PowerPortReceiverDef
conjugates: Interfaces::PowerPortDef
---
Conjugated port definition for receiving electrical power.
All features have their directions reversed relative to PowerPortDef.

8.3.2 Port — Port Usage¶

Type-specific additional fields:

Example (model/VehicleSystem/Engine.md features section):

features:
  - name: powerOut
    type: Port
    typedBy: Interfaces::PowerPortDef
    direction: out
  - name: fuelIn
    type: Port
    typedBy: Interfaces::FuelPortDef
    direction: in

8.3.3 InterfaceDef and Interface¶

An interface definition specifies the required compatibility between two connection ends.

Type-specific additional fields for InterfaceDef:

Each entry in constraints::

Example (Kirchhoff's current law on an electrical interface):

constraints:
  - name: kcl
    expression: "positive.current + negative.current = 0"
    isAsserted: true

Example (model/Interfaces/PowerInterface.md):

---
type: InterfaceDef
name: PowerInterface
ends:
  - name: sourceEnd
    typedBy: Interfaces::PowerPortDef
    direction: out
    isEnd: true
  - name: receiverEnd
    typedBy: Interfaces::PowerPortReceiverDef
    direction: in
    isEnd: true
---
Interface defining a valid power connection between a source and receiver.

8.3.4 Operations on Ports and Interfaces¶

The operations: field declares callable operations (synchronous) or receptions (asynchronous) on a definition element. It is valid on PortDef, InterfaceDef, ConnectionDef, and any other definition element where behavioral contracts need to be specified. In SysMLv2 terms, each entry corresponds to an OperationDef (synchronous) or a ReceptionDef (when isAsync: true) owned by the enclosing definition.

Operation entry schema:

Parameter entry schema (each entry in parameters:):**

Cross-reference rule: If typedBy on a parameter or returnType does not resolve to a known element in the model, the validator emits W404 (warning, not error, because standard library types such as ScalarValues::Boolean and ScalarValues::Integer may be unregistered external type libraries).

Mutual-exclusion rule: isAsync: true and returnType: are mutually exclusive. Specifying both is a modelling error.

Example 1 (model/Interfaces/TelemetryPortDef.md) — PortDef with synchronous query and async reception:

---
type: PortDef
name: TelemetryPortDef
supertype: Ports::Port
features:
  - name: packet
    typedBy: Items::TelemetryPacket
    direction: out
    multiplicity: "0..*"
operations:
  - name: requestLatest
    doc: "Synchronously return the most recent telemetry packet."
    isQuery: true
    isAsync: false
    parameters: []
    returnType: Items::TelemetryPacket
  - name: subscribe
    doc: "Register for periodic telemetry push at the given interval."
    isAsync: true
    parameters:
      - name: intervalMs
        typedBy: ScalarValues::Integer
        direction: in
---
Port definition for outgoing telemetry data. Components emitting telemetry expose this port.

Example 2 — InterfaceDef with operations spanning both ends:

---
type: InterfaceDef
name: CommandInterface
ends:
  - name: commander
    typedBy: Interfaces::ControlPortDef
  - name: executor
    typedBy: Interfaces::ControlPortDef
    isConjugated: true
operations:
  - name: executeCommand
    isAsync: false
    parameters:
      - name: cmd
        typedBy: Items::ControlCommand
        direction: in
    returnType: ScalarValues::Boolean
  - name: abort
    isAsync: true
    parameters: []
---
Interface definition for command dispatch between a commander and executor.

8.4 Connection, Binding, and Succession Elements¶

8.4.1 Connection Schema¶

The connections: field on PartDef, Part, ActionDef, and Action elements specifies internal block connections. Each entry is a map.

Binary shorthand — use from: and to: for the common two-end case:

N-ary form — use ends: for connections with three or more ends, or when end names matter:

Each entry in ends: (connection usage end-binding):

Rule: from: / to: and ends: are mutually exclusive within a single connection entry. from:/to: is syntactic sugar that expands to ends: [{end: source, binds: <from>}, {end: target, binds: <to>}].

8.4.2 ConnectionDef File¶

A ConnectionDef declares its ends using a top-level ends: field.

Each entry in ends: (connection definition end declaration):

Each entry in crossFeatures::

Binary example (model/Power/PowerConnection.md):

---
type: ConnectionDef
name: PowerConnection
supertype: Connections::BinaryConnection
ends:
  - name: source
    typedBy: Interfaces::PowerPortDef
  - name: receiver
    typedBy: Interfaces::PowerPortReceiverDef
---
A binary connection transmitting electrical power.

N-ary example (model/Hydraulics/HydraulicJunction.md):

---
type: ConnectionDef
name: HydraulicJunction
ends:
  - name: supply
    typedBy: HydraulicPortDef
    multiplicity: "1"
  - name: return
    typedBy: HydraulicPortDef
    multiplicity: "1"
  - name: drain
    typedBy: HydraulicPortDef
    multiplicity: "0..1"
---
A three-way hydraulic junction connecting supply, return, and optional drain lines.

Cross-feature example (model/Fluid/FluidPath.md):

---
type: ConnectionDef
name: FluidPath
ends:
  - name: source
    typedBy: FluidPortDef
    crossFeatures:
      - name: flow
        typedBy: FluidItemDef
        crosses: target
        direction: out
  - name: target
    typedBy: FluidPortDef
---
A directed fluid path carrying a FluidItem from source to target.

N-ary usage (inside a PartDef):

connections:
  - typedBy: HydraulicJunction
    ends:
      - end: supply
        binds: pump.outPort
      - end: return
        binds: tank.inPort
      - end: drain
        binds: reservoir.drainPort

8.4.3 Binding Connectors¶

The bindingConnections: field specifies equality bindings. Each entry:

bindingConnections:
  - left: engine.speed
    right: transmission.inputSpeed

8.4.4 Successions¶

The successionConnections: field specifies ordering between occurrences/actions. Each entry:

successionConnections:
  - after: startEngine
    before: engageTransmission
    guard: "engine.rpm > 600"

The field is accepted on ActionDef/Action (ordering between sub-actions) and on PartDef/Part, where it carries the structural successions between the owned usages (SysML v2's first a then b; / succession s first a then b; inside a part def body).

8.5 Attribute and Enumeration Elements¶

8.5.1 AttributeDef¶

Defines a data value type.

---
type: AttributeDef
name: Temperature
supertype: ISQ::ThermodynamicTemperatureValue
features:
  - name: unit
    typedBy: SI::ThermodynamicTemperatureUnit
    value: SI::K
---
A thermodynamic temperature value defaulting to Kelvin.

Value constraints (REQ-TRS-DATA-001..-003, GH #366). An AttributeDef may constrain the values of the type it defines:

A specialising AttributeDef (a typedef) inherits range and pattern and may narrow the range, never widen it (E683); an ItemDef whose features are attributes is a struct. A value: bound to an inline feature or an Attribute typed by a constrained type must satisfy the effective constraints (E682). A type that declares none of the fields adds no check, and the three fields on any other element type are W047.

---
type: AttributeDef
name: Speed
unit: SI::m_per_s
range: "0..70"
default: 0
---
Vehicle speed in metres per second.

8.5.2 EnumerationDef¶

Defines a discrete-valued attribute. The enumerated values are listed in values:.

Type-specific additional fields:

Each entry in values::

Example (model/VehicleSystem/VehicleStatus.md):

---
type: EnumerationDef
name: VehicleStatus
values:
  - name: parked
  - name: idling
  - name: moving
  - name: maintenance
---
Operational status of a vehicle.

Example with bound values (model/Interfaces/StandardVoltage.md):

---
type: EnumerationDef
name: StandardVoltage
supertype: ISQ::VoltageValue
values:
  - name: lowVoltage
    value: "12.0"
    unit: SI::V
  - name: highVoltage
    value: "48.0"
    unit: SI::V
---
Standard vehicle bus voltage levels.

8.5.3 Attribute Usage¶

---
type: Attribute
name: vehicleStatus
typedBy: VehicleSystem::VehicleStatus
multiplicity: "1"
---
Current operational status of this vehicle instance.

Value and unit. A standalone Attribute may carry value: (a literal default/binding — number, string or boolean) and unit: (name of the unit of a quantity-valued value:), the same shorthand §3.6.1 defines for inline features: entries. Ingested SysML v2 attribute mass : Real = 12.5 [kg]; produces value: 12.5, unit: kg; export-sysml writes them back as = 12.5 [kg].

8.6 Flow Elements¶

8.6.1 FlowDef¶

Defines a flow connection type (items moving between ports).

Type-specific additional fields:

Payload shorthand note: itemType: Fuel is syntactic sugar for a payload feature that redefines Transfers::Transfer::payload:

# shorthand
itemType: VehicleSystem::Fuel

# equivalent full form (use when explicit redefinition chain is needed)
features:
  - name: payload
    redefines: [Transfers::Transfer::payload]
    typedBy: VehicleSystem::Fuel

A parser that expands itemType: to the full form can participate in type-compatibility checking on connected ports. When specializing another FlowDef, use the full form with redefines: pointing to the supertype's payload feature to preserve the redefinition chain.

---
type: FlowDef
name: FuelFlowDef
supertype: Flows::FlowConnection
itemType: VehicleSystem::Fuel
ends:
  - name: sourcePort
    typedBy: Interfaces::FuelPortDef
    direction: out
    isEnd: true
  - name: sinkPort
    typedBy: Interfaces::FuelPortReceiverDef
    direction: in
    isEnd: true
---
A flow connection carrying fuel between a fuel source and consumer.

8.6.2 flowConnections: Schema¶

The flowConnections: field on PartDef or Part elements:

Flow kind semantics:

8.7 Action and Behavior Elements¶

8.7.1 ActionDef¶

Defines a behavioral step. Actions can have parameters (in/out/inout/return) and contain sub-actions connected by succession.

Type-specific additional fields:

8.7.2 Parameter Schema¶

Each entry in parameters::

8.7.3 Sub-Action Schema¶

Each entry in subActions::

Sub-action kinds:

8.7.4 Control Node Schema¶

Each entry in controlNodes::

Example (model/VehicleBehavior/ProvidePower.md):

---
type: ActionDef
name: ProvidePower
parameters:
  - name: requestedPower
    typedBy: ISQ::PowerValue
    direction: in
  - name: actualPower
    typedBy: ISQ::PowerValue
    direction: out
subActions:
  - name: startEngine
    typedBy: VehicleBehavior::StartEngine
    kind: Action
  - name: regulatePower
    typedBy: VehicleBehavior::RegulatePower
    kind: Action
    parameters:
      - name: target
        value: requestedPower
  - name: measureOutput
    typedBy: VehicleBehavior::MeasurePower
    kind: Action
successionConnections:
  - after: startEngine
    before: regulatePower
  - after: regulatePower
    before: measureOutput
bindingConnections:
  - left: measureOutput.measuredPower
    right: actualPower
---
Action definition for providing engine power in response to a power request.