Schema Data Model

This section describes the structure of LinkML schemas. For precise semantic interpretation of these structures, refer to the following two parts on derived schemas (part 4) and validation (part 5).

Schema Basics

A LinkML schema specifies rules and structural conformance conditions for instances. Schemas allow for:

• parsing of instance serializations to LinkML instances
• structurally and semantically validating LinkML instances
• inference of missing values in LinkML instances

The LinkML Metamodel

Every LinkML schema m is itself an instance of a special class SchemaDefinition that forms part of a special schema called the LinkML metamodel, which is denoted by m^M. There is exactly one metamodel.

In this specification:

• ClassDefinitions in m^M are called metaclasses
• SlotDefinitions in m^M are called metaslots

The metamodel is itself expressed in LinkML, and the latest version can found from canonical URLs:

• https://w3id.org/linkml/SchemaDefinition -- top level class
• https://w3id.org/linkml/meta.yaml -- canonical YAML serialization of the metamodel

This specification specifies the normative elements necessary to specify the behavior of LinkML schemas. Schemas may have additional elements provided in the metamodel. For example, elements in schemas can have informative slot assignments for slots such as title, description, and so on, but these slots are not described in this specification as they are not normative and do not affect the formal interpretation of schemas.

The subset of the metamodel that corresponds to the specification is called the SpecificationProfile, and it is found at:

• https://w3id.org/linkml/SpecificationSubset

YAML representation of schemas

This part of the specification specifies schemas in terms of the abstract functional syntax (part 2).

For practical purposes, the canonical serialization of a schema is in YAML. The rules for serializing and deserializing LinkML schemas are the same as for instances, because every schema is an object that instantiates a SchemaDefinition class in the metamodel.

See section 6 for rules for mapping to YAML.

Analogies to other modeling frameworks

To help understand the basic concepts, it can be helpful to think about analogous structures in other frameworks. However, it should be understood these are not precisely equivalent.

• ClassDefinitions are analogous to:
  • classes in object-oriented languages
  • tables in relational databases and spreadsheets
  • owl:Class entities in RDFS/OWL
• SlotDefinitions are analogous to:
  • attributes in object-oriented languages
  • columns or fields in relational databases and spreadsheets
  • properties in JSON-Schema
  • rdf:Property entities in RDFS/OWL
• EnumDefinitions are analogous to:
  • enumerated types in programming languages and some relational systems
  • drop-down selections in spreadsheets
  • Note however that in LinkML enums are optionally backed by stronger semantics with enum elements (permissible values) mapped to vocabularies or ontologies
• TypeDefinitions are analogous to:
  • data types in most object-oriented languages
  • primitive types in database systems
  • extensible types in some systems
  • rdf:Literals in RDF
  • Datatypes in OWL

SchemaDefinition Metaclass

• metamodel documentation: SchemaDefinition

SchemaDefinition: Normative subset metaslots

A schema m is an instance of a SchemaDefinition, with normative elements:

SchemaDefinition: Normative subset UML

A subset of the above normative slots are depicted as follows:

Schema example, functional syntax

The skeleton of a schema instance serialized as in functional syntax might look like:

SchemaDefinition(
  id=String^"http://example.org/organization",
  imports=[...],
  prefixes=[...],
  classes=[...],
  slots=[...],
  enums=[...],
  types=[...],
)  

Schema example, YAML

The skeleton of the above schema instance serialized as YAML might look like:

id: http://example.org/personinfo
imports:
  ...
prefixes:
  ...
classes:
  ...
slots:
  ...
enums:
  ...
types:
  ...

ClassDefinition Metaclass

• metamodel documentation: ClassDefinition

Instances of ClassDefinition are themselves instantiable. For example, a schema may contain a class definition "Person". This ClassDefinition instantiates the metaclass ClassDefinition, and can have instances, of actual persons.

Any LinkML instance that instantiates a ClassDefinition will have zero to many slot-value assignments, constrained by rules that operate off of the metaslot assignments of that class.

ClassDefinition: Normative subset metaslots

Any instance c of a ClassDefinition may have assignments in any of the following normative metaslots

ClassDefinition: UML

A subset of the above normative slots are depicted as follows:

ClassExpressions and anonymous ClassExpressions

Note this metaclass exemplifies a pattern that is reused by TypeDefinition, SlotDefinition and EnumDefinition metaclasses, below.

For the core definition types <D>, there are a triad of 3 metaclasses in the metamodel:

• <D>Expression
• Anonymous<D>Expression
• <D>Definition

depicted as:

For many purposes, all that is required is the Definition element. The purpose of the above abstraction is to allow composition of anonymous expressions using boolean operators. For example, we may want to refer to the union of collection of ClassDefinitions.

Class Definition Example, Functional Syntax

A collection of ClassDefinition instances might look

[  
   ClassDefinition(
    name=String^"NamedThing",
    abstract=True,
    slots=[
        SlotDefinitionReference&"id",
        SlotDefinitionReference&"name",
        ...
      ]
    ),
   ClassDefinition(
    name=String^"Person",
    description=String^"A person, living or dead",
    is_a=ClassDefinitionReference&"NamedThing",
    attributes=[
        SlotDefinition(
            name=String^"height",
            ...),
        SlotDefinition(
            name=String^"age",
            ...)
   ),
   ...
],

Class Definition Example, YAML

The above example following the YAML serialization is:

NamedThing:
   abstract: true
   slots:
      - id
      - name
Person:
   description: A person, living or dead
   is_a: NamedThing
   attributes:
      height:
         ...
      age:
         ...

SlotDefinition Metaclass

• metamodel documentation: SlotDefinition

Instances of SlotDefinition are not themselves instantiable. Each assignment in a LinkML ClassDefinition instance must use a SlotDefinition from the schema.

SlotDefinition: Normative subset metaslots

SlotDefinition inherits from both Element and SlotExpression. A SlotDefinition must have a name. other schema elements may refer to AnonymousSlotExpressions composed using boolean operators.

Any instance s of a SlotDefinition may have assignments in any of the following normative metaslots

SlotDefinition: Normative subset UML

A subset of the above normative slots are depicted as follows:

Slot Definition Example, Functional Syntax

An example collection of SlotDefinitions might be:

SchemaDefinition(
  slots=[
   SlotDefinition(
    name=String^"id",
    identifier=Boolean^True,
    description=String^"A unique identifier for an object",
    range=TypeDefinitionReference&"String",
    ...
    ),
   SlotDefinition(
    name=String^"name",
    description=String^"...",
    range=String^"String",
    ...
    )

EnumDefinition Metaclass

• metamodel documentation: EnumDefinition

Instances of EnumDefinition instances are instantiable. For example, a schema may have an enumeration with name "JobCode". This is an instance of an EnumDefinition, and can also be instantiated by different permissible values such as "Forklift Driver"

EnumDefinition: Normative subset metaslots

Any instance e of a EnumDefinition may have assignments in any of the following normative metaslots:

EnumDefinition: Normative subset UML

A subset of the above normative slots are depicted as follows:

TypeDefinition Metaclass

• metamodel documentation: TypeDefinition

Instances of TypeDefinition are themselves instantiable. For example, a schema might contain a TypeDefinition with name "PhoneNumber". This is an instance of TypeDefinition, and can itself be instantiated by individual phone numbers.

TypeDefinition: Normative subset metaslots

Any instance t of a TypeDefinition may have assignments in any of the following normative metaslots:

TypeDefinition: Normative subset UML

A subset of the above normative slots are depicted as follows:

Default Types

LinkML includes a default schema of types

• Schema: https://w3id.org/linkml/types.yaml.
• Documentation: https://linkml.io/linkml-model/docs/#types

These are:

• Boolean (Bool) - A binary (true or false) value
• Date (XSDDate) - a date (year, month and day) in an idealized calendar
• Datetime (XSDDateTime) - The combination of a date and time
• Decimal (Decimal) - A real number with arbitrary precision that conforms to the xsd:decimal specification
• Double (float) - A real number that conforms to the xsd:double specification
• Float (float) - A real number that conforms to the xsd:float specification
• Integer (int) - An integer
• Ncname (NCName) - Prefix part of CURIE
• Nodeidentifier (NodeIdentifier) - A URI, CURIE or BNODE that represents a node in a model.
• Objectidentifier (ElementIdentifier) - A URI or CURIE that represents an object in the model.
• String (str) - A character string
• Time (XSDTime) - A time object represents a (local) time of day, independent of any particular day
• Uri (URI) - a complete URI
• Uriorcurie (URIorCURIE) - a URI or a CURIE

The type schema can be imported, used directly, or used as a basis to extend new types

ClassDefinitionReference Metaclass

ClassDefinitionReferences are primitive elements that provide a way to reference a particular instances.

ClassDefinitionReferences are not part of the asserted schema but are derived from derivation rules -- see next section

Prefix Metaclass

• metamodel documentation: Prefix

A schema can contain any number of prefixes. Each prefix maps a short name such as "owl" to a URI. These are used to determine the canonical URI for any element.

Prefix: Normative subset metaslots

Prefix: Normative subset UML

Prefix Example, Functional Syntax

SchemaDefinition(
    prefixes=[
       Prefix(prefix_prefix=Ncname("linkml")
              prefix_reference=Uri("https://w3id.org/linkml/")),
       Prefix(prefix_prefix=Ncname("schema")
              prefix_reference=Uri("http://schema.org")),
       Prefix(prefix_prefix=Ncname("wgs")
              prefix_reference=Uri("http://www.w3.org/2003/01/geo/wgs84_pos#")),
       Prefix(prefix_prefix=Ncname("qudt")
              prefix_reference=Uri("http://qudt.org/1.1/schema/qudt#"))
    ])

Prefix Example, YAML

prefixes:
  linkml: https://w3id.org/linkml/
  schema: http://schema.org/
  wgs: http://www.w3.org/2003/01/geo/wgs84_pos#
  qudt: http://qudt.org/1.1/schema/qudt#

Complete Schema Example (Informative)

For example, consider a schema that models representations of individual people and organizations they belong to may include a class definition Person, and slot definitions for name, address, relationships and so on.

This might be depicted in UML as:

This would have a YAML serialization (see section 6):

classes:
  Person:
    description: ...
    slots:
       - id
       - name
       - height
       - date_of_birth
       - occupation
       - knows
slots:
  id:
     identifier: true
     range: string
  name:
     range: string
  date_of_birth:
     range: date
  height:
     range: float
  occupation:
     range: JobCode
  knows:
     range: Person
     multivalued: true
enums:
  JobCode:
    permissible_values:
      ForkliftDriver:
      ...:
types:
  date:
    ...

Because schemas, are instances of the metamodel, this hypothetical schema may be serialized in functional instance syntax as follows:

SchemaDefinition(
  id=String^"http://example.org/organization",
  name=String^"organization",
  prefixes=[
       Prefix(prefix_prefix=Ncname^"linkml"
              prefix_reference=Uri^"https://w3id.org/linkml/"),
       Prefix(prefix_prefix=Ncname^"org"
              prefix_reference=Uri^"http://example.org/organization/"),
       Prefix(prefix_prefix=Ncname^"schema"
              prefix_reference=Uri^"http://schema.org"),
       Prefix(prefix_prefix=Ncname^"wgs"
              prefix_reference=Uri^"http://www.w3.org/2003/01/geo/wgs84_pos#"),
       Prefix(prefix_prefix=Ncname^"qudt"
              prefix_reference=Uri^"http://qudt.org/1.1/schema/qudt#")
  ],
  default_prefix=String^"org",
  imports=[
    Uriorcurie^"linkml:types"
  ],
  classes=[
    ClassDefinition(
      name=String^"Person",
      slots=[
        SlotDefinition&"id",
        SlotDefinition&"name",
        SlotDefinition&"height",
        SlotDefinition&"age",
        SlotDefinition&"knows",
        SlotDefinition&"job",
        ...
      ]
    ),
    ClassDefinition(
      name=String^"Organization",
      slots=[
        SlotDefinition&"id",
        ...
      ]
    ),
    ...
  ],
  slots=[
    SlotDefinition(
      name=SlotDefinition&"id",
      identifier=Boolean^True,
      description=String^"...",
      range=TypeDefinition&"String",
      ...
    ),
    SlotDefinition(
      name=SlotDefinition&"name",
      description=SlotDefinition&"...",
      ...
    ),
    SlotDefinition(
      name=String^"occupation",
      ...
    ),
    SlotDefinition(
      name=String^"date_of_birth",
      ...
    ),
    SlotDefinition(
      name=String^"knows",
      description=String^"...",
      range=ClassDefinition&"Person",
      multivalued=Boolean^True,
      ...
    )
  ],
  enums=[
     EnumDefinition(
       name=String^"JobCode",
       permissible_values=[...],
     )
  ],
  types=[
     TypeDefinition(
       name=String^"Date",
       ...
     ),
     TypeDefinition(
       name=String^"String",
       ...
     ),
  ]
)