Schema Element Metadata

There are various slots that can be used to provide metadata about either a schema or elements of a schema. These typically don’t affect the semantics of the model, but rather act as annotations that can be used to provide more information to people, or that can guide the behavior of some tools.

Providing descriptions

The description slot can be used to provide a human-readable description of any schema element

  Person:
    is_a: NamedThing
    description: >-
      A person (alive, dead, undead, or fictional).

descriptions can include markdown

  Person:
    is_a: NamedThing
    description: :-
      A human being including those that are:
         * alive
         * dead
         * undead
         * fictional

However, this is only recommended for schema descriptions.

This guide to yaml formatting may be helpful

Providing aliases

The aliases slot can be used to define a list of aliases for a class or slot. This is useful for adding synonymous names to your class (or slot), that serve either as hints for human users, or to enhance search and findability over your model

Example:

Person:
  aliases:
    - human being
    - individual

In practice, aliases are used to help interpret the model, not as an equivalent name for a class or slot name. Downstream tooling could use these aliases to help users query the model for example, but the LinkML tooling does not consider aliases and element names interchangeable.

Structured aliases

Sometimes you may want to include additional information about an alias

Person:
  structured_aliases:
    - literal_form: Homo sapiens
      alias_predicate: skos:exactMapping
      source: Linnaeus
  - literal_form: Persona
      alias_predicate: skos:exactMapping
      source: Google Translate
      in_language: es

Deprecating elements

Any schema element can be deprecated, with a reason provided; optionally, a replacement can be provided

classes:
  Agent:
    deprecated: the concept of Agent was too abstract, use Person instead
    deprecated_element_has_exact_replacement: Person

Specifying units

You can use the unit element to annotate a slot as holding a value in a particular unit:

slots:
  height_in_cm:
    range: float
    unit:
      ucum_code: cm

In this case we are annotating the height_in_cm slot with a unit, where that unit is itself described as having a UCUM code of cm.

Note: embedding the unit in the name of the slot as well as the explicit annotation may seem redundant. However, in most scenarios it is good practice to make a measurement slot unambiguous, unless it can be guaranteed that the data will never be separated from the LinkML schema / data dictionary.

You can use a number of different systems for specifying the unit, including:

  • UCUM

  • QUDT

  • IEC61360 codes

  • Arbitrary ontology or vocabulary CURIEs, taken from sources like:

Additionally, you can specify what kind of quantity is being measured, using an ontology.

For example:

prefixes:
  linkml: https://w3id.org/linkml/
  UO: http://purl.obolibrary.org/obo/UO_
  PATO: http://purl.obolibrary.org/obo/UO_
  qudt: http://qudt.org/schema/qudt/
  uom: https://w3id.org/uom/
    
slots:
  height_in_cm:
    range: float
    unit:
      ucum_code: cm
      iec61360code: UAA375
      exact_mappings:
        - UO:0000015 ## centimeter
        - uom:cm
      has_quantity_kind: PATO:0000119 ## height     

If you must, you can omit any kind of formal description altogether and simply provide a symbol.

You can also declare your own primitive types extending float, double, decimal, or integer, and describing these with a unit element. This type can then be used in multiple different slots.

For example:

types:
  KilogramValue:
    typeof: float
    unit:
      ucum_code: kg

Specifying the unit doesn’t affect the behavior of the slot or type, but it’s a useful way of formally specifying the intended use of a slot, and provides a potential hook for interoperation and automated data model mapping.

Arbitrary annotations

You can use the annotations element to provide arbitrary key-value pairs for any of your schema elements. This can be used for when none of the existing metamodel slots are appropriate.

One use case is providing various tooltips, display hints, or UI hints for deta elements. These can then be used by applications such as UIs to drive behavior.

slots:
  name:
    annotations:
      entry_hint: make sure you enter the FULL name here
      color: green
      tooltip: name of person

Other metadata slots

See CommonMetadata for other slots