Preconditions

The ReqIF files and SysML v2 models used with this tool must satisfy certain preconditions. Most are met by default when the requirements management tool follows the ReqIF specification.

Precondition satisfaction can be checked using the syside reqif check CLI command. syside reqif check reqif <file.reqif> runs the ReqIF preconditions against an exchange document; syside reqif check sysml runs the SysML v2 preconditions against the current workspace. The same checks also run automatically as part of syside reqif import and syside reqif export.

ReqIF preconditions

These checks run against the ReqIF exchange document.

Structural integrity

• Every cross-element reference must resolve to an element in the document of the right kind: a Spec* element’s type to its corresponding *Type definition; a SpecHierarchy’s object and a SpecRelation’s source and target to an existing SpecObject; a RelationGroup’s source and target to an existing Specification; and every AttributeDefinition’s datatype to an existing DatatypeDefinition.

• If the document contains any SpecRelation, it must also contain at least one RelationGroup. SysML v2 maps SpecRelation to a connection inside a RelationGroup, so an unhomed relation has no parent namespace.

• Every SpecRelation must be referenced by exactly one RelationGroup. References must resolve (no dangling ids), no relation may be claimed by more than one group, and no relation may be left unclaimed.

• For each RelationGroup, every SpecRelation it contains must reference SpecObjects that live inside one of the Specifications named on the group’s source and target.

• Each SpecObject may appear in at most one Specification.

• The SpecHierarchy must contain no cycles: no SpecObject may appear as its own descendant.

• A given SpecObject may parent nested hierarchy nodes in at most one position across the model. Two distinct hierarchy nodes that parent the same SpecObject would emit colliding indexed-name siblings ('1', '2', …) under one RequirementDefinition.

Name uniqueness

SysML v2 names that share a scope must be unique, so the import checks that every incoming ReqIF LONG_NAME is unique once translated. In practice this means:

• Each top-level ReqIF element (an enum DatatypeDef, a *Type template, a SpecObject, a Specification, or a RelationGroup) must have a name unique across this combined set.

• A SpecRelation must not share a name with any of those top-level elements, and within a single RelationGroup every SpecRelation must have a unique name. (The same SpecRelation name may be reused in a different RelationGroup.)

• Every EnumValue within an enumeration DatatypeDef and every AttributeDef within a SpecType must have a unique name.

• An enumeration DatatypeDef must not share its name with an AttributeDef it types. Otherwise SysML v2 emits an ambiguous attribute Priority : Priority, in which the attribute and its type cannot be told apart.

Tip

If the source tool does not enforce LONG_NAME uniqueness, re-run the import with --resolve-duplicate-names instead of editing the upstream document. The flag resolves every collision listed in this section. It is documented in Working with ReqIF, and the suffix it adds is stripped automatically on export.

Other reserved-name constraints

Two further name collisions break re-parse of the emitted SysML v2 for reasons orthogonal to the global namespace above. --resolve-duplicate-names does not resolve these, so they must be fixed in the source document:

• No element name may match a reserved SysideReqIF metadata name (the names defined by the SysideReqIF.sysml library).

• A SpecType must not carry both a magic ReqIF.Text / ReqIF.Description AttributeDef and a free-form AttributeDef named Text / Description. The magic attributes are emitted as doc Text / doc Description blocks on the parent and would shadow the free-form sibling.

Warnings (non-fatal)

• A DatatypeDef referenced by no AttributeDef is reported as a warning. Such a DatatypeDef has no carrier on the SysML v2 side (the embedding only emits DatatypeDefs reached through @reqif_* annotations on AttributeDefs) and is dropped on import.

SysML v2 preconditions

These checks run against the .sysml documents in the current workspace.

• Each .sysml document may declare at most one top-level Package or LibraryPackage. Incremental ReqIF import overwrites the document with one top-level package, so any extras would be dropped. Both kinds count toward the limit; a file that mixes one of each still fails.

• Every ReqIF tag (every element annotated with a @reqif_* metadata tag) must be “locked”: must carry both a stable identifier and a last_change value. Unlocked tags lose their identity across ReqIF round-trips. Run syside reqif lock to populate fresh UUIDs and last_change timestamps for any element flagged here.

• A @reqif-annotated def may subclassify (:>) another @reqif-annotated def only when the parent carries a #reqif_*_type prefix tag and the child does not. This is the instance-to-type pattern that import emits: a SpecObject / Specification / RelationGroup def specializing its corresponding SpecObjectType / SpecificationType / RelationGroupType. Any other @reqif :> @reqif chain (type extending type, or instance extending instance) has no ReqIF analogue and would be dropped on the next export. attribute usages that redefine (:>>) a type’s AttributeDef are unaffected; redefinition is not subclassification. The rule applies within one source: elements annotated for different exchanges may specialize each other freely, since no single exchange sees both and nothing is lost on round-trip.

• Every ReqIF tag’s source must be a string literal, or absent. Which exchange a tag belongs to has to mean the same thing to every reader, and the annotation writers behind syside reqif link apply read the source from the syntax rather than evaluating it. A source that only evaluation can resolve is one the toolchain cannot place, so link apply refuses to touch the element.

• No two distinct elements may claim the same (source, identifier) pair. That pair is an element’s ReqIF identity within one exchange, so a collision would export two SysML v2 elements as the same ReqIF element. Datatype marker tags (@reqif_string, @reqif_integer, …) are excluded, since one scalar DatatypeDef is legitimately referenced from a marker tag under each AttributeDef that uses it.

• No element may carry two identity-bearing tags of the same kind with the same source: at most one base @reqif, at most one @reqif_enum_value, and at most one datatype marker per element per exchange. The datatype markers count together, because @reqif_string beside @reqif_integer in one exchange is two datatype identities for one AttributeDef.