Skip to content

Definitions

Jump to bottom
Tobias Spears edited this page Mar 24, 2020 · 12 revisions

Home Modelling

Good definitions of model elements are important for human understanding of the models. In UML, definitions are written in the Notes field, and possibly also in tagged values. ISO19103 - Conceptual Schema Language and ISO19109 - Rules for Application Schemas have several rules and recommendations for definitions of packages, classes, attributes and roles. Basically, they all tell you that you should

write definitions for all model elements

Rules and recommendations

ISO 19103

General

Requirement 3: All normative class models shall contain definitions sufficient for understanding of all classes, attributes, associations, operations and appropriate data type definitions.

Enumerations and codelists

Requirement 7: As the values of enumerated types are concepts, each value shall have a definition for the value.

Naming and namespaces

Recommendation 12: UML elements should use documentation fields to further explain the meanings (semantics) of named elements.

Documentation of models

Requirement 19: Each classifier shall have a definition describing its intended meaning or semantics.

Requirement 20: Each package, classifier, operation, attribute, association role, association and constraint shall have a textual description in the text near its context diagram.

ISO 19109

Documentation of an application schema

/req/uml/documentation: An application schema shall be documented. The textual definition of each CLASS, ATTRIBUTE, ASSOCIATION ROLE, OPERATION and CONSTRAINT should be recorded using the primary documentation facility provided by the tool if this information can be exported.

Secondary descriptions and informative notes for each PACKAGE, CLASS, ATTRIBUTE, ASSOCIATION ROLE, OPERATION and CONSTRAINT may be recorded using a TAGGED VALUE with the name “description”.

If a CLASS or other UML component is an implementation of a model element defined in a feature catalogue, the reference to the catalogue shall be documented in a TAGGED VALUE with the name “catalogue-entry”.

Writing definitions

In Enterprise Architect, "the primary documentation facility provided by the tool" is the Note field for each class, attribute, association role, operation and constraint. The definition shall be written in this field, and shall be

  • as concise as possible and not contain examples or further explanations (these shall go into the tagged value "description")
  • shall not start with "An address component is …"
  • shall end with a full stop (".")

Example:

Identifier or geographic name of a specific geographic area, location, or other spatial object which defines the scope of an address.

Secondary descriptions - tagged value "description"

Secondary descriptions may be written in the tagged value "description" this can be for instance:

The natural language name

Example:

address component

A complementary description

  • The source reference of the definition can be included using the keyword SOURCE, after which a short name of the Source shall be included.
  • Additional explanations in the descriptions can be introduced by the keyword NOTE (all upper case). If there is more than one note, the notes should be numbered: NOTE 1, NOTE 2, etc.
  • Examples can be introduced by the keyword EXAMPLE (all upper case). If there is more than one example, the examples should be numbered: EXAMPLE 1, EXAMPLE 2, etc.

Example:

SOURCE [UPU-S21]

NOTE 1 Four different subclasses of address components are defined:

  • Administrative unit name, which may include name of country, name of municipality, name of district
  • Address area name like e.g. name of village or settlement
  • Thoroughfare name, most often road name
  • Postal descriptor In order to construct an address, these subclasses are often structured hierarchically.

NOTE 2 It is the combination of the address locator and the address components, which makes a specific address spatial object readable and unambiguous for the human user.

EXAMPLE The combination of the locator "13" and the address components "Calle Mayor" (thoroughfare name), "Cortijo del Marqués" (address area name), "41037" (postal descriptor), "Écija", "Sevilla" and "España" (administrative unit names) makes this specific address.

For information: Definitions in INSPIRE

The INSPIRE Repository tutorial have a convention for how the information in the note field can be structured (see page 8 in the document). According to the convention, the note field can include three main elements: Natural name, definition and description

This convention does not completely follow the rules from ISO 19103 and ISO 19109, but it can be modified to do so by moving the natural name and description to the tagged value "description"

Clone this wiki locally