Page Comparison

Naming Conventions for Data Inputs and other Model Elements

There is a need to standardize the naming (and structure) of data objectsfollow 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

  - input, decision, task, item, etc…

  • 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 a different model elementelements

  • 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, 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”

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

  • Consider using “Descriptions” instead

• [Technical] The naming convention Names MUST be a valid identifier identifiers as per the modeling specificationnotation(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. For example, it

    • 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.

...

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 asLas

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

which would leadresulting, e.g. to “Serum in “[Most Recent Valid] Serum glucose in mmol per L”

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

Example : Naming Conventions Spectrum

...