Naming Conventions #OpenForComments

Naming Conventions for Data Inputs and other Model Elements

There is a need to standardize the naming (and structure) of data objects.

[Semantics] The naming convention SHOULD reflect the meaning of the named model element - input, decision, task, item, etc…
- Consider leveraging the DataTypes that may be associated to a model element
- 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, at a minimum within the scope of the model
- 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”
[Pragmatic] The name should not be too long to become impractical
- Consider using “Descriptions” instead
[Technical] The naming convention MUST be a valid identifier as per the modeling specification
- 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.
- For example, 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 asL

which would lead, e.g. to “Serum glucose in mmol per L”

In doing so, one should be careful when units may involve special characters that may be corrupted in the underlying mappings, and one should 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 - the names of the two model elements should reflect that distinction.