Navigation step reference

Navigation steps let a table column show information about a related model element. For example, Subject(baseViewElement) finds the subject of the requirement in the current row.

This page lists the available steps, their parameters, and the types of model elements they work with. To learn how to combine steps, see 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 subject.
RequirementConstraints	A requirement’s assume and require constraints.
Owner	An element’s owning namespace.
MetadataUsageTag	A metadata tag owned by an element.
UsageHTV	The usage behind a hierarchical table row.

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.

Some steps only work with certain types of elements. For example, Subject works with requirements 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.sysml 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.

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).

A feature’s effective name is usually its declared name. 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.

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 requirement’s subject.

Applies to: requirements.

Subject(element)

Additional parameters: none.

Example

This requirement has a subject named drone:

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

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

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.

UsageHTV

Returns the usage associated with the current row in a hierarchical table.

Each row displays a definition, but different usages can refer to the same definition. UsageHTV lets a column show information about the particular usage represented by that row.

Applies to: baseViewElement in a hierarchical table view.

UsageHTV(element)

Additional parameters: none.

Use it as the first step of a chain, with baseViewElement as its argument. Using it in a flat table causes a column error.

Example

This drone has two usages of the same Motor definition:

part def Motor;
part def Drone {
    part leftMotor : Motor;
    part rightMotor : Motor;
}

In a hierarchical table expanded from Drone, both motor rows represent Motor.

Definition	UsageHTV(baseViewElement)
Motor	leftMotor
Motor	rightMotor

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::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::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.
NameType::shortName	The element’s short name.