Legal information

Copyright DB Netz AG, licensed under CC-BY SA 3.0 DE (see full text in CC-BY-SA-3.0-DE)

5. Modelling Rules for Data

5.1. Overall

IDRule
DMR-001

In order to ensure consistency within the project, British English is to be used at all times.

Refer to the Cambridge Dictionary for further information.

DMR-002

Images and/or diagrams that are to be used in the descriptions of Capella model elements shall be created and maintained on the following Confluence page:

Images for Capella model element descriptions

DMR-003

Description Links for model elements shall be used in all model element descriptions.

E.g. if a certain description refers to a defined model element, the name of the model element being referred to shall be copied (as a Description Link) and pasted (as a Link) in the corresponding description field.

Exception: model elements defined as abstract concepts or terms, which serve solely as a form of documenting information external to the project, shall be excluded from this rule.

5.2. Data Model Elements

5.2.1. Guidance

ARCH.M.050 Method for definition of data model

5.2.2. General Rules

DAT-003

Units and physical quantities are always defined and edited on the operational level.

Rationale: To ensure that they can be reused at all levels and that there is only one location for these standard definitions.

DAT-004
  • Data model elements are always created at the level where they are first needed.
  • These data model elements can be reused unchanged at all levels below.
  • Where a interaction between activities on operational level requires a defined data model element, the data model element are created on operational level.
  • Where a functional exchange between functions on system level requires a defined data model element that is NOT yet defined at operational level, the data model element are created on system level.
  • Where a functional exchange between functions on logical level requires a defined data model element that is NOT yet defined at system level, the data model element are created on logical level.
  • If there is a need to refine or change data model element at lower levels, a new data model element should be created at the needed level. The new data element should be linked via a realisation to the corresponding data model element at the higher level.
DAT-005

It is not allowed to have identical data model elements on multiple levels.

EXCEPTION: when working together in a cooperation project in which there is no operational level model content. In the model where there is model content at the operational level it is allowed that there is identical data at the operational level and system level. But the realisation relationship must then be set correctly and the name of the operational level data model element must then end with _O.

For example, the system of interest does not have an operational level, while another system of interest project does. In such a case, it is permissible for the system of interest to utilise operational-level data from the other system of interest on its system level, since in this case the data are not being duplicated. However, in the case that the two projects are merged in the future, realisation relationships will have to be created between the previously-created data on operational level and the newly-merged data on system level. It must also be ensured that the names of the data elements are provided postfixes corresponding to their levels.

Note: identical refers to naming conflicts and identical content properties.

DAT-009

All data model elements at operational, system, and logical levels represent abstract application layer data only (that is, data connected with the functionality of the system).

EXCEPTION: constraint system interface see ARCH.M.030 Method for definition of interfaces.

5.2.3. Terms

IDRule
GT-010Terms are always created and edited on the Operational Analysis level and are modelled in Capella as Classes.
GT-011Terms does not have relationships/associations to other terms.
GT-020

Naming convention for a class name in the terms::

  • Title Case - the first letter of each word is capitalised, words separated by space.
  • Names should be singular

5.2.4. Data Object

5.2.4.1. Data Object Class

DOC-010

Where a class realises a higher level class, there shall exist a realisation relationship between realising class and realised class.

Note: see DAT-004 and DAT-005 for additional rules.

DOC-020

Naming convention for a class name:

  • Title Case - the first letter of each word is capitalised, words separated by space.
  • Names should be singular
DOC-030

Each class has an adequate description.

DOC-040

In the case of modelling a super-class the following two things are forbidden:

  • Repeated definition of a property when it is already defined on the super-class and therefore inherited.
  • Specification of a subclass's type with respect to the super-class through an additional property (this is redundant since the definition of the subclass itself represents the type with respect to the super-class)
DOC-050

A class property is either an attribute directly typed by one of the following, listed in order of preference:

  • A predefined Simple Type (predefined type in Capella / basic computing types such as string, int, etc.)

  • A project-specific Simple Type

  • A project-specific Structured Type

OR

is derived from a navigable role through an association link.

DOC-060

Naming conventions for Properties (Roles/Attributes) names:

  • camelCase - names start with a lower case but each proper word in the name is capitalised and so are acronyms
  • It is recommended to not use abbreviations, only in exceptional cases
  • Names should be chosen so that they are understandable
  • If the type of the property is already used in another case and has the same meaning, please check if the name of the property can be the same or at least similar.
DOC-070Each property has an adequate description.

5.2.4.2. Simple Types

IDRules
DOS-020In case of defining Simple Types choose one of this Types:
  • BooleanType (Can be further defined with BooleanLiteral)

  • Enumeration (Can be further defined with EnumerationLiteral)

  • NumericType

    Guidance: For Operational Level System Level and Logical level, it does not make sense to distinguish numeric attributes into integer, long, unsigned float etc., as these distinctions are part of the solution, not the external requirements (use generic numeric type). Exception: For externally constraint system interface, the numeric subtypes may be used. For the subsystem architecture we can start to defining the interfaces between subsystems. Then detailed numeric types can be used. 
  • StringType

  • PhysicalQuantity (Can be further defined with Unit) (PhysicalQuantity and Unit are always defined and edited on the operational level - DAT-003)

Note: Simple Types can not have properties. If you need them please define Structured Types.

DOS-050

Naming conventions for Simple Types:

  • BooleanType, Enumeration, NumericType, StringType, PhysicalQuantity: PascalCase - All words capitalised and run together. First letter is capitalised. 
  • Unit: SI-Based Symbol
  • EnumerationLiteral: Sentence case - the first letter of the first word in a sentence is capitalised, except for words like abbreviations or standardised terms which have their own (externally-defined) naming conventions.
  • NumericLiteral: Title_Case - the first letter of each word is capitalised, words separated by underscores.
  • BooleanLiteral: Title_Case - the first letter of each word is capitalised, words separated by underscores.

Guidance for the usage of units when defining physical quantities:

  1. Use only units that are part of the SI (https://en.wikipedia.org/wiki/SI_base_unit and https://en.wikipedia.org/wiki/SI_derived_unit) or accepted by the SI (https://en.wikipedia.org/wiki/Non-SI_units_mentioned_in_the_SI)
  2. Choose between units for the same physical quantity:
    1. The SI coherent unit (e.g. metre), if the field of application is new or mostly closed
    2. A non-coherent unit (e.g. kilometre), if an external standard or common practise prefers this unit against the coherent unit (e.g. Railway common practise and ETCS language describe speeds in km/h, not in m/s)
  3. The "Unit" Capella elements get the Unit's symbol (e.g. m/s) as a Capella Name and the written-out name (e.g. metre/second) as a Summary.

5.2.4.3.  Structured Types

IDRule
DOT-040

In case of defining a Structured Type the chosen Class must be specified as Primitive.
StructuredTypes/Primitive Classes can have properties and can be used as type of a property in another Class or in another Structured Type.

Note: Concept of primitive class corresponds to that of DataType in UML, whose instances have no identity, unlike for classes.

Guidance: the data object exchanged between an external actor and the system may vary:

    • If the information is already known by the system, therefore it is sufficient to simply send an ID of that information

    • If the system doesn't know the information, then it is necessary to provide the whole data structure

Naming conventions for Structured Type:

  • PascalCase - All words capitalised and run together. First letter is capitalised. 
  • Names should be singular
DOT-060Each Structured Type has at least one property.

5.2.5. Exchange Item and Exchange Item Element

XGI-001

Naming Convention for Exchange Item: lower_case - all letters lowercase, words separated by underscores.

Guidance/recommendation: names of exchange items should end with one of the following nouns:

  • estimation
  • calculation
  • observation
  • requirement
  • capture
  • indication
  • actuation
  • presence
  • perception
  • definition
  • command (exchange item type event only)
  • report (exchange item type event only)

Note: where message sets are defined in standards, and not all messages are used, ONLY the used messages need to be modelled; there is no need to spend extra time capturing Exchange Items for messages that are never used.

XGI-002

Each Exchange Item is defined by a communication mechanism:

  • UNSET: in the first stages of the engineering process, the communication mechanism applied to a given Exchange Item might not be known or decided upon;
  • FLOW: flow of continuously available DATA, matter, energy or light;
  • EVENT: asynchronous mechanism where an event is sent by an element and received by one or several others;
XGI-003

Naming Convention for Exchange Item Element:

  • camelCase - names start with a lower case but each proper word in the name is capitalised and so are acronyms
  • Not to use abbreviations is recommended, only to be used in exceptional cases

Guidance/recommendation: names of exchange item elements should begin with one of the following participles:

  • Estimated
  • Calculated
  • Observed
  • Required
  • Captured
  • Indicated
  • Actuated
  • Present
  • Perceived
  • Defined
  • Commanded
  • Reported

Note: An Exchange Item Element can be compared to a property/attribute of an exchange item so the name should take this into account.

XGI-004Where the data object is NOT specific to that Exchange Item, the "Is Composite" box is UNCHECKED for an Exchange Item Element.
XGI-005

Each Exchange Item Element links Exchange Items to data object.

Guidance: the data object exchanged between an external actor and the system may vary:

    • If the information is already known by the system, therefore it is sufficient to simply send an ID of that information

    • If the system doesn't know the information, then it is necessary to provide the whole data structure
XGI-006

The cardinality of each Exchange Item Element is defined correctly.

Note: by default, the cardinality is set to 1; that is, a Exchange Item has one field of the specified type. Some Exchange Items need to be defined such that the cardinality is variable depending on the number of Types being transmitted.

XGI-010

Where an exchange item implements or realises a higher level exchange item, there shall exist a realisation relationship between realising exchange item and realised exchange item.

Note: see DAT-004 and DAT-005 for additional rules.

5.2.6. Data Rationale

IDRule
DRA-010Rationales should be created using the model element requirement (type rationale).
DRA-020The description for the rationale is inserted in the field "text" in Capella.
DRA-030Each rationale has at least one outgoing link to a target model element using the relation type "justifies".
DRA-040

Basically, all data model elements can be justified by a rationale. At least the following data model elements should be justified:

  • where a exchange item is created due to a purely architectural decision, a rationale element is created documenting the decision.

  • Where a class is created due to a purely architectural decision, a rationale element is created documenting the decision.
DRA-050

If a rationale is expanded by an artefact, e.g. a trade study result or other type of supporting artefact, the rationale text shall include a reference to the expanding artefact, including (where possible) its document number and a hyperlink to the artefact's current version.

Guidance:

ARCH.M.110 Method for definition of rationales

5.3. Diagram Types and Viewpoints

5.3.1. General Rules 

IDRule
GRV-010

Each diagram shall be named according to following convention:

[<Capella diagram type abbreviation>][<Viewpoint number>] <Subject of view> [<Viewpoint name>]

Capella diagram type abbreviation: abbreviation indicating the type of the diagram with the following possible values:

  • O.CDB - Operational Class Diagram Blank
  • S.CDB - System Class Diagram Blank
  • L.CDB - Logical Class Diagram Blank
  • P.CDB - Physical Class Diagram Blank

Viewpoint number: number given to the viewpoint based on ARCH process

Subject of view: either a <model element> or <free text>

  • <model element>
    • exact name of the model element
    • is used if the viewpoint focuses on a single model element
  • <free text>
    • a useful title providing initial information about the contents of the diagram (e.g. set of model elements shown)
    • is used if the viewpoint does not focus on a single model element or for other cases
    • shall be written in sentence case - the first letter of the first word in a sentence is capitalised

Examples:

  • [O.CDB][AMOD-025] Abstract concept defnition consolidated [Abstract concepts]
  • [S.CDB][AMOD-113] Exchange item definition for set point to rquired position by operational plan [System exchange items]
  • [S.CDB][AMOD-091] Enumerations [Logical data object definition]
GRV-030

If a note is used on a diagram, it should include the name of the person responsible and the date of creation.

Note: if after the design review there is still a need for the note, the name can be removed.

5.3.2. AMOD-025 Abstract concepts 

025-040

Relationships between concept classes are logically consistent.
The name of the relationship should be in lower case and is centered around a verb, so that the relation can be read as a noun-verb-noun sentence (e.g. Mission Concept - can be realised as a - Mission).

Note: Permitted relationships are association, composition, aggregation, and generalisation. These relationships in Capella have their usual meanings as defined in UML/SysML.

025-060

The navigability of all associations is set to match the intended direction of the association (and therefore should be consistent when the tuple is read as a sentence in English, in the direction of the association).

Note: this is a workaround that is not semantically correct, but is done because Capella does not provide the ability to set a direction of an association separately from its navigability.

025-070The filters on the diagram are set to display the names of associations.
025-071The filters on the diagram are set to hide the properties.
025-072The filters on the diagram are set to hide the role names.
025-080The multiplicity of associations is set appropriately at both ends.
025-090

When a class is modelled as part of more than one class, the aggregation type is always "aggregate".

Guidance: This is achieved by editing the properties of the aggregation, and has the effect that the diamond end of the association is hollow.

5.3.3. Data Object Definition Class Diagram 

5.3.3.1. General Rules

COB-030

Where a specific type is defined the types should be visible on the definition diagram to increase understanding.
COB-040

Relationships between class classes are logically consistent.

COB-050The filters on the diagram are set to hide the names of associations.
COB-060The filters on the diagram are set to show the properties.
COB-070The filters on the diagram are set to show the role names.
COB-080The multiplicity of associations is set appropriately at both ends.

5.3.3.2. AMOD-105 Operational data objects [O.CDB]

105-010

Instances should be structured in line with the structure used for the abstract concept viewpoint (so that there is generally one instance per instance of AMOD-025 - unless it is necessary to split the views up for readability).

5.3.3.3. AMOD-112 System data objects [S.CDB] 

112-010

Instances should be structured in line with the structure used for the abstract concept viewpoint (so that there is generally one instance per instance of AMOD-025 - unless it is necessary to split the views up for readability).

5.3.3.4. AMOD-091 Logical data objects [L.CDB] 

091-010

Instances should be structured in line with the structure used for abstract concept viewpoint (so that there is generally one instance per instance of AMOD-025 - unless it is necessary to split the views up for readability).

5.3.3.5. AMOD-086 Interface layer data objects

IDRule
086-010All data objects are shown which are used in the exchange items of the considered interface layer.

5.3.4. Exchange Item Definition Class Diagram

5.3.4.1. General Rules

MSG-010

The <free text> for exchange item definition diagrams shall be the capability name.

Note: For further details on diagram titles see General rules.

5.3.4.2. AMOD-110 Operational exchange items [O.CDB] 

IDRule
110-010

There is at least one diagram per operational capability.

110-020All exchange items (including all exchange item elements and their data objects) are shown which are allocated to an interaction which connects two activities of interest for for the capability.
110-030Data objects that itself does not have a exchange item element link to an exchange item, but are the type for an attribute are shown as well on the diagram.

5.3.4.3. AMOD-113 System exchange items [S.CDB]

ID

Rule

113-010

There is at least one diagram per system capability.

110-020All exchange items (including all exchange item elements and their data objects) are shown which are allocated to an functional exchange which connects two functions of interest for for the capability.
113-030Data objects that itself does not have a exchange item element link to an exchange item, but are the type for an attribute are shown as well on the diagram.

5.3.4.4. AMOD-092 Logical exchange items [L.CDB] 

ID

Rule

092-010

There is at least one diagram per realised capability.

092-020All exchange items (including all exchange item elements and their data objects) are shown which are allocated to an functional exchanges which connects two function of interest for for the capability.
092-030Data objects that itself does not have a exchange item element link to an exchange item, but are the type for an attribute are shown as well on the diagram.

5.3.4.5. AMOD-094 Interface layer exchange items

IDRule
094-010All exchange items (including all exchange item elements and their data objects) are shown which are allocated to a functional exchange which connects two interface layer functions.
094-020If the exchange items are related to a interface, there is at least one diagram per interface.

Color legend :

MeaningColor
Naming convention