Navigation step reference

Navigation steps let a column of a table view in the Syside VS Code Extension show information about a related model element. For example, Subject(baseViewElement) finds the subject of the requirement in the current row. To learn how steps combine into chains, see Table navigation chains.

Navigation steps at a glance

Every step has its own section below, in this order:

Step	Finds
Definitions	The definitions a usage is typed by.
Specializations	The definitions a definition specializes.
Heritage	Everything an element inherits from, across levels.
Usage	An element’s usage features, optionally of one kind.
NamedUsage	One usage feature, by name.
Subject	A requirement’s or case’s subject.
Actors	A requirement’s or case’s actors.
Stakeholders	A requirement’s stakeholders.
Objective	A case’s objective.
RequirementConstraints	A requirement’s assume and require constraints.
Owner	An element’s owning namespace.
MetadataUsageTag	A metadata tag owned by an element.

How a step is written

Each step takes a starting element as its first argument. Any additional parameters follow in the order shown in this reference. You can leave out optional parameters at the end of the argument list. The parameter tables explain what happens when you omit them.

Steps that can find more than one element have three variants: First, List, and Fan. These accept the same parameters unless the reference states otherwise:

• First expects one target. When it finds several, the cell shows the first with a warning and cannot be edited (see Cell outcomes).

• List shows every target together in one read-only cell, and ends its chain.

• Fan gives each target its own fanned-out row, and must be named at view level (see Fanning a row out).

Table navigation chains explains when to use each.

Some steps only work with certain types of elements. For example, Subject works with requirements and cases but does not apply to parts. When a step does not apply to a row, the cell displays the column’s notApplicableValue. See Cell outcomes.

Allowed expressions

The steps listed here are defined in the SysideViews library. A column’s columnFeature can combine these steps with:

• Named navigations.

• Literal values or enumeration values passed as arguments.

Other KerML expressions are not supported. If a column uses an unsupported expression, its cells are empty and cannot be edited. A banner above the table explains the problem. See A column shows an error, not values.

Definitions

Returns the definitions explicitly assigned to a usage with :.

Applies to: usages.

DefinitionsFirst(element), DefinitionsList(element), DefinitionsFan(element)

Additional parameters: none.

Example

This usage has two types:

part def Powered;
part def Tracked;
part rover : Powered, Tracked;

Each call starts from rover.

Element	DefinitionsFirst	DefinitionsList	DefinitionsFan
rover	Powered	Powered, Tracked	Powered
			Tracked

These steps do not continue to definitions that Powered or Tracked specializes. Implicit types from the standard library are excluded. If the usage has no explicit type, these steps return no elements.

Every row of a table is the element itself, so DefinitionsFirst(baseViewElement) is how a column shows the definition behind a usage row. On a definition row, such as the top row of a hierarchical table under expose X::**, the step does not apply and the cell shows the column’s notApplicableValue.

Specializations

Returns the definitions that a definition directly specializes.

Applies to: definitions.

SpecializationsFirst(element), SpecializationsList(element), SpecializationsFan(element)

Additional parameters: none.

Example

This definition specializes two definitions:

part def Powered;
part def Tracked;
part def Rover :> Powered, Tracked;

Each call starts from Rover.

Element	SpecializationsFirst	SpecializationsList	SpecializationsFan
Rover	Powered	Powered, Tracked	Powered
			Tracked

These steps do not continue to definitions that Powered or Tracked specializes.

Heritage

Returns the types an element inherits from, including types reached through several levels of inheritance. It checks one level at a time, in declaration order.

Applies to: types.

HeritageFirst(element), HeritageList(element, depth), HeritageFan(element, depth)

HeritageFirst checks only the first level. It does not accept a depth argument. Passing one causes an error.

The List and Fan variants accept this additional parameter:

Parameter	Type	Meaning	Default / required
depth	Integer	Number of inheritance levels to check. Use -1 for no limit.	Optional. No limit.

At each level, the step follows explicit subclassification (:>), typing (:), subsetting, and redefinition (:>>) relationships. For a usage, this includes its type and any features it redefines, then continues through their inheritance relationships. Implicit inheritance from the standard library is excluded.

Example

Consider this inheritance chain:

part def Vehicle;
part def Drone :> Vehicle;
part def DeliveryDrone :> Drone;

Each call starts from DeliveryDrone.

Element	HeritageFirst	HeritageList	HeritageFan
DeliveryDrone	Drone	Drone, Vehicle	Drone
			Vehicle

With a depth limit, HeritageList(DeliveryDrone, 1) returns only Drone.

Usage

Returns an element’s usage features, including features declared in the element and features it inherits. Use kind to select a particular kind of usage.

Applies to: definitions and usages.

UsageFirst(element, kind, includeSubtypes), UsageList(element, kind, includeSubtypes), UsageFan(element, kind, includeSubtypes)

Parameter	Type	Meaning	Default / required
kind	UsageKind enumeration	Kind of usage to return. See UsageKind.	Optional. Matches any kind.
includeSubtypes	Boolean	Set to true to include kinds derived from kind, such as parts when selecting items.	Optional. false (exact match).

Example

Consider a drone with a payload, a battery, and a motor:

part def Drone {
    item payload;
    part battery;
    part motor;
}

Each call starts from Drone. All three use UsageKind::itemUsage and includeSubtypes = true.

Element	UsageFirst	UsageList	UsageFan
Drone	payload	payload, battery, motor	payload
			battery
			motor

With an exact kind match, UsageList(Drone, UsageKind::itemUsage) returns only payload.

Features declared in the standard library are excluded. Features from third-party libraries are included. Enumeration members are variants rather than usage features, so navigation steps do not return them.

NamedUsage

Returns the usage feature whose name or short name (controlled by nameType) matches name. It searches features declared in the element and features it inherits. Use kind to limit the search to a particular kind of usage.

Applies to: definitions and usages.

NamedUsage(element, name, nameType, kind, includeSubtypes)

Parameter	Type	Meaning	Default / required
name	String	Name to match, as a non-empty string literal.	Required.
nameType	NameType enumeration	Which name to match. See NameType.	Required.
kind	UsageKind enumeration	Kind of usage to return. See UsageKind.	Optional. Matches any kind.
includeSubtypes	Boolean	Set to true to include kinds derived from kind, such as parts when selecting items.	Optional. false (exact match).

The same exclusions as for Usage apply: features from the standard library and enumeration members are excluded, while features from third-party libraries are included.

If several features match, the cell shows the first, read-only, with a warning that the model has more than one match, as a First step does.

Example

This drone has two parts:

part def Drone {
    part battery;
    part motor;
}

Call	Returns
NamedUsage(Drone, "battery", NameType::name)	battery
NamedUsage(Drone, "motor", NameType::name)	motor

Subject

Returns the subject of a requirement or case. This includes a subject the element inherits, for example a requirement usage’s subject declared in its definition.

Applies to: requirements and cases, including concerns, viewpoints, use cases, analysis cases and verification cases.

Subject(element)

Additional parameters: none.

If the requirement or case declares no subject and inherits none, the cell shows the column’s notApplicableValue.

Note

The Subject step returns a subject that the requirement declares or inherits. A nested requirement can also take the subject of the requirement it is nested in, without declaring one. The step does not report that subject, so the cell shows the column’s notApplicableValue. To show the subject in the table, declare it in the nested requirement.

For a satisfy declaration with by, the step returns the subject of the satisfy declaration, not the element after by. In satisfy braking by car, car is the value given to that subject. The documentation of this subject is read-only in a table, because the declaration has no body to hold it.

Example

This requirement has a subject named drone:

part def DroneDef;
requirement def MaxAltitude {
    subject drone : DroneDef;
}
requirement altitudeCheck : MaxAltitude;

Element	Subject(element)	DefinitionsFirst(Subject(element))
MaxAltitude	drone	DroneDef
altitudeCheck	drone	DroneDef

altitudeCheck declares no subject of its own, so the step returns the one it inherits from MaxAltitude.

Actors

Returns the actors of a requirement or case in declaration order. This includes actors declared in the element and actors it inherits.

Applies to: requirements and cases.

ActorsFirst(element), ActorsList(element), ActorsFan(element)

Additional parameters: none.

Example

This requirement has two actors:

part def Car;
part def Environment;
requirement def Braking {
    subject vehicle : Car;
    actor road : Environment;
    actor weather : Environment;
}

Each call starts from Braking.

Element	ActorsFirst	ActorsList	ActorsFan
Braking	road	road, weather	road
			weather

An actor redefined in a usage replaces the one it redefines. Here ActorsList(wetBraking) returns wetRoad, weather:

requirement wetBraking : Braking {
    subject :>> vehicle;
    actor wetRoad :>> road;
}

The subject is redeclared because a requirement that declares its own actor or stakeholder must declare its subject first.

Stakeholders

Returns the stakeholders of a requirement in declaration order. This includes stakeholders declared in the element and stakeholders it inherits.

Applies to: requirements, including concerns and viewpoints. Cases have no stakeholders, so the step does not apply to them.

StakeholdersFirst(element), StakeholdersList(element), StakeholdersFan(element)

Additional parameters: none.

On a viewpoint, the step returns only the stakeholders the viewpoint declares. The stakeholders of the concerns it frames are not included.

Example

This requirement has two stakeholders:

part def Car;
part def Person;
requirement def Braking {
    subject vehicle : Car;
    stakeholder driver : Person;
    stakeholder regulator : Person;
}

Each call starts from Braking.

Element	StakeholdersFirst	StakeholdersList	StakeholdersFan
Braking	driver	driver, regulator	driver
			regulator

Objective

Returns the objective that a case declares.

Applies to: cases, including use cases, analysis cases and verification cases.

Objective(element)

Additional parameters: none.

The step returns only an objective the case declares itself. An objective inherited from a definition is not returned, and the cell shows the column’s notApplicableValue. To reach an inherited objective, look it up by name with NamedUsage:

NamedUsage(element, "delivered", NameType::name, UsageKind::requirementUsage)

Note

This follows the SysML v2 specification. A case’s objective is the requirement the case owns through an objective membership (ObjectiveMembership), and that membership requires ownership. A case that inherits an objective therefore has no objective of its own. It inherits the requirement as a plain requirement feature, which is why NamedUsage finds it and Objective does not.

Example

This use case definition declares an objective, and transport is a usage of it:

part def Car;
use case def Transport {
    subject vehicle : Car;
    objective delivered;
}
use case transport : Transport;

Element	Objective(element)
Transport	delivered
transport	N/A

RequirementConstraints

Returns a requirement’s assume and require constraints in declaration order. This includes constraints declared in the requirement and constraints it inherits.

Applies to: requirements.

RequirementConstraintsFirst(element, kind), RequirementConstraintsList(element, kind), RequirementConstraintsFan(element, kind)

Parameter	Type	Meaning	Default / required
kind	RequirementConstraintKindSV enumeration	Kind of constraint to return. See RequirementConstraintKindSV.	Optional. Returns both kinds.

This step does not return ordinary constraint or assert constraint declarations in the requirement body. To find those, use Usage or NamedUsage with the corresponding UsageKind value.

Example

This requirement has one assumption and one required constraint:

requirement def SafeFlight {
    assume constraint clearWeather {
        language "English" /* The weather is clear. */
    }
    require constraint altitudeLimit {
        language "English" /* The drone stays below 500 m. */
    }
}

Each call starts from SafeFlight.

Element	RequirementConstraintsFirst	RequirementConstraintsList	RequirementConstraintsFan
SafeFlight	clearWeather	clearWeather, altitudeLimit	clearWeather
			altitudeLimit

To select only altitudeLimit, use:

RequirementConstraintsFirst(SafeFlight, RequirementConstraintKindSV::required)

Owner

Returns the element’s direct owner, also called its parent namespace.

Applies to: namespaces.

Owner(element)

Additional parameters: none.

Example

This package owns the Drone definition:

package Aircraft {
    part def Drone;
}

Element	Owner(Aircraft::Drone)
Drone	Aircraft

MetadataUsageTag

Returns a metadata tag owned by the element. It selects the tag by the name of the metadata definition that the tag applies.

Applies to: namespaces.

MetadataUsageTag(element, name, nameType)

Parameter	Type	Meaning	Default / required
name	String	Metadata definition’s name, as a non-empty string literal.	Required.
nameType	NameType enumeration	Which name to match. See NameType.	Required.

Example

Both parts below carry a Safety tag. On battery the tag is anonymous, written with the @ shorthand. On motor the tag usage has a name of its own, guard:

metadata def Safety {
    attribute level;
}
part battery {
    @Safety {
        :>> level = 10;
    }
}
part motor {
    metadata guard : Safety {
        :>> level = 3;
    }
}

MetadataUsageTag matches on the definition’s name, "Safety", on both parts. The tag usage’s own name never matches, so "guard" finds nothing:

Call	Returns
MetadataUsageTag(battery, "Safety", NameType::name)	the anonymous tag
MetadataUsageTag(motor, "Safety", NameType::name)	guard
MetadataUsageTag(motor, "guard", NameType::name)	empty

Only tags owned by the element are returned. Inherited tags are excluded.

Enumerations

These enumerations supply the argument values that steps accept. They are defined in the SysideViews library.

UsageKind

Selects the kind of usage that Usage or NamedUsage returns.

Value	Comment
UsageKind::usage	Matches any kind, including flow, succession and bind usages, which no other value matches.
UsageKind::occurrenceUsage	With includeSubtypes = true, also matches items, parts, actions and the other kinds of occurrence.
UsageKind::attributeUsage
UsageKind::itemUsage
UsageKind::partUsage
UsageKind::portUsage
UsageKind::connectionUsage
UsageKind::actionUsage
UsageKind::constraintUsage	Includes a requirement’s assume and require constraints, but not assert constraint declarations.
UsageKind::assertedConstraintUsage	Matches the assert constraint declarations that UsageKind::constraintUsage leaves out.
UsageKind::requirementUsage

The includeSubtypes parameter controls whether related kinds also match:

• With false or no argument, the match is exact. For example, UsageKind::itemUsage matches only item usages.

• With true, the match includes kinds derived from the selected kind. For example, UsageKind::itemUsage also matches parts, and UsageKind::partUsage also matches views.

RequirementConstraintKindSV

Selects which constraints RequirementConstraints returns.

Value	Selects
RequirementConstraintKindSV::either	Both kinds. The default.
RequirementConstraintKindSV::required	require constraints only.
RequirementConstraintKindSV::assumed	assume constraints only.

NameType

Selects which name NamedUsage or MetadataUsageTag matches against.

Value	Matches
NameType::name	The element’s effective name, usually its declared name.
NameType::shortName	The element’s short name.