-
Notifications
You must be signed in to change notification settings - Fork 17
Definitions
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 recomendations for definitions of packages, classes, attributes and roles. Basically, they all tell you that you should
write definitions for all model elements
The INSPIRE Repository tutorial have a good 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 (Text copied from the INSPIRE Tutorial):
###The natural language name (mandatory)
- introduced by the tag "-- Name --"
- given in lower case
###The definition (mandatory)
- introduced by the tag "-- Definition --"
- as concise as possible and not contain examples or further explanations (these shall go into the description)
- shall not start with "An address component is …"
- shall end with a full stop (".")
- If the definition uses another term that needs to be defined, this additional definition shall be included using the keyword DEFINITION (all upper case).
###The description (optional)
- introduced by the tag "-- Description --"
- is optional. If there is not further description, do not include the -- Description -- tag. The source reference of the definition can be included using the keyword SOURCE, after which a short name of the Source shall be included. The full reference shall be included in the INSPIRE data specification.
- Additional explanations in the descriptions shall be introduced by the keyword NOTE (all upper case). If there is more than one note, the notes shall be numbered: NOTE 1, NOTE 2, etc.
- Examples shall be introduced by the keyword EXAMPLE (all upper case). If there is more than one example, the examples shall be numbered: EXAMPLE 1, EXAMPLE 2, etc.
###Example
The following (partly fictional) example for the spatial object type “AddressComponent” shows how the convention should be applied:
-- Name --
address component
-- Definition --
Identifier or geographic name of a specific geographic area, location, or other spatial object which defines the scope of an address.
DEFINITION Geographic name: A proper noun applied to a real world entity.
-- Description --
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.
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.
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”.