Instances: Core Structure

A template instance is an instance artifact. It holds metadata that conforms to a template. In YAML it identifies its template with isBasedOn. It gives a value for each field or nested element under children, keyed by the child's key. The key is the identifier the template assigns each child, not its display name.

type: instance
name: "SDY232"
description: "Metadata for the SDY232 cardiology study"
id: "https://repo.metadatacenter.org/template-instances/1f9a2b3"
isBasedOn: "https://repo.metadatacenter.org/templates/ec3f500"
children:
  study-name:
    value: "Cardiology cohort"

Field Values

Which keys a field's value carries depends on the kind of value. A plain literal carries just value. A typed literal adds datatype. A controlled term carries id with a label.

type: instance
name: "SDY232"
isBasedOn: "https://repo.metadatacenter.org/templates/ec3f500"
children:
  study-name:
    value: "Cardiology cohort"
  participants:
    value: "2323"
    datatype: xsd:int
  disease:
    id: "http://purl.obolibrary.org/obo/DOID_530"
    label: "eyelid disease"

A field with no value is omitted from children entirely.

A controlled term value can carry two further labels drawn from its vocabulary. prefLabel holds the term's preferred label, the canonical name the vocabulary assigns it, which may differ from the label shown to the author. notation holds the term's short code or accession within the vocabulary.

  disease:
    id: "http://purl.obolibrary.org/obo/DOID_530"
    label: "eyelid disease"
    prefLabel: "eyelid disease"
    notation: "DOID:530"

Multiple Values

A field that accepts more than one value holds a list under its key. Each entry has the same shape it would have as a single value. For a plain literal field, each entry carries a value.

  keywords:
  - value: "genomics"
  - value: "oncology"

A controlled-term field behaves the same way. Each entry is a full controlled term, carrying its id and label.

  conditions:
  - id: "http://purl.obolibrary.org/obo/DOID_2841"
    label: "asthma"
  - id: "http://purl.obolibrary.org/obo/DOID_10763"
    label: "hypertension"

Nested Elements

An element does not hold a value of its own. Its entry under children holds its own children, one for each field or element it contains, nested the same way as at the top level. A repeating element holds a list of such entries.

  address:
    children:
      street:
        value: "450 Serra Mall"
      city:
        value: "Stanford"
  contributors:
  - children:
      full-name:
        value: "Ada Lovelace"
  - children:
      full-name:
        value: "Alan Turing"

Instance Types

An instance can state the classes it is an instance of, its RDF types. They sit under instanceType, the key a template uses for the type it asserts on its instances. One class is written as a string and several as a list, and each is an absolute IRI. In the JSON-LD form they are the instance's @type.

type: instance
name: "SDY232"
id: "https://repo.metadatacenter.org/template-instances/1f9a2b3"
instanceType:
- "https://schema.org/Dataset"
- "https://schema.org/CreativeWork"
isBasedOn: "https://repo.metadatacenter.org/templates/ec3f500"
children:
  study-name:
    value: "Cardiology cohort"

A nested element states its own classes the same way, after its id and before its children. A compact document keeps them, since they are the instance's data rather than the repository's. An element that states classes and holds no value is still written, with type: element-instance to mark it as an element.

  address:
    instanceType: "https://schema.org/PostalAddress"
    children:
      street:
        value: "450 Serra Mall"
  contact:
    type: element-instance
    instanceType: "https://schema.org/ContactPoint"

Standalone Element Instances

An element instance can also stand on its own, outside any template instance, using type: element-instance. It carries the same name, id, and children as a nested element value, plus the type discriminator that lets it stand alone.

type: element-instance
name: "Address"
children:
  street:
    value: "450 Serra Mall"
  city:
    value: "Stanford"