Naming Conventions #OpenForComments

Naming Conventions for Data Inputs and other Model Elements

There is a need to follow common patterns and principles when naming model elements.

• [Semantics] The naming convention SHOULD reflect the clinical meaning of the named model element

  • Task/Decision element names SHOULD include a Verb

  • Data related element names SHOULD consist in Nouns

  • Goals/Milestones SHOULD be phrased as Predicates - statements with a truth degree

  • Events/Triggers COULD follow the “On <Event>” pattern

• [Semantics] Additional meaning SHOULD be conveyed using other features of the model elements

  • Consider leveraging the DataTypes, and constraints thereof, that may be associated to different model elements

  • Consider using semantic annotations, e.g. references to external ontologies/terminologies

    • Future: addressed in MVF - until then, tools may provide proprietary solutions (e.g. Trisotech’s “accelerators”)

    • The name SHOULD be consistent with any official term/label defined in the ontology being (implicitly or explicitly) referenced

• [Semantics] The name MUST be unique/unambiguous within the scope of the model, and SHOULD be generally unambiguous and explicit to minimize dependencies on assumptions and background knowledge

  • Implicit semantics (within the scope of the model).
    E.g. “Age” truly means “Current Chronological Age”, as implied by the context of use

  • Disambiguation (within the scope of the model)
    E.g. “Current Age” vs “Age at Initial Diagnosis” SHOULD NOT be both labeled “Age”

• [Pragmatics] The name should not be too long to become impractical

  • Consider using “Descriptions” instead

• [Technical] Names MUST be valid identifiers as per the modeling notation(s)

  • The (human readable) name used in the model MAY be mapped/aligned to formal model elements e.g. ‘variables', which are constrained by the specification.

    • It MAY be problematic if special characters, punctuation, and other symbols beyond common letters and numbers are used.
      
      

Historically, especially when DMN is involved, the name of an “InputData” model element is bound to the name of the underlying variable (as is, or for example via x-casing), which is then used in an API “signature” definition.
However, it can be argued that this requirement - the definition of an interface specification - needs more information, along the lines of what would be included in an OpenAPI or a WSDL API spec, which is way more than what a ‘name’ can contain.

Consequently, the need for a naming strategy may also be considered in a broader context of annotating model elements with a combination of:

• name

  • human readable/localizable aka “title”

  • technical name

• description

• associated datatype / schema

• semantic annotations

  • ontology binding (conceptual level)

  • valueset binding (admissible instance level - related to datatype/schema)

This ‘technical' motivation should be considered - and possibly handled - independently from the general author’s requirement of CLARITY: i.e. ensuring that the underlying meaning (semantic and/or computational) is reflected in the presentation/communication layer, including the labels/names used in the model itself.

Example / Use Case:

When working with Labs, one COULD adopt a naming convention such as

<specimen type><lab test name><units>

resulting, e.g. in “[Most Recent Valid] Serum glucose in mmol per L”

One should be careful when units may involve special characters that may be corrupted in the underlying mappings. Contrast “μmol/L” vs “mmol per L”.
In this case, one could also consider properly formalizing the units as constraints/schema elements, and removing it from the element name altogether.

However, if units help disambiguate - e.g. consider a model that uses a patient’s weight in both kilos and pounds for different purposes - the names of the two model elements should reflect that distinction.

Example : Naming Conventions Spectrum

Open

Open