Vocabularies in iSamples are used to provide discrete labels that help to categorize samples. The vocabularies are generally hierarchical in nature with a top level broad concept and progressively narrower concepts. Relationship between the concepts are defined using the Simple Knowledge Organization System ([SKOS](https://www.w3.org/2004/02/skos/)) common data model.

# Vocabulary Components

Herein `skos` refers to `http://www.w3.org/2004/02/skos/core#`

A vocabulary as used in iSamples is an [RDF graph](https://en.wikipedia.org/wiki/Resource_Description_Framework) composed of one instance of `skos:ConceptScheme` and one or more instances of `skos:Concept`.

One or more of the `skos:Concept` instances should include a `skos:topConceptOf` predicate, the object of which is the `skos:ConceptScheme` for the vocabulary. If a `skos:Concept` does not include a `skos:topConceptOf` predicate, then it should contain a `skos:inScheme` predicate that refers to the `skos:ConceptScheme` instance.[^a]

A `skos:Concept` instance that does not include a `skos:topConceptOf` predicate must include a `skos:broader` predicate, the object of which is an instance of `skos:Concept` with a broader definition.

Each `skos:Concept` instance must include a `skos:prefLabel` and should include a `skos:definition` that provides a clear textual description of the concept.[^b]

@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@prefix eg: <https://example.net/my/minimal/> .

eg:vocab
    rdf:type skos:ConceptScheme ;
    skos:prefLabel "Minimal Example Vocabulary"@en ;
.

eg:thing
    rdf:type skos:Concept ;
    skos:topConceptOf eg:vocab ;
    skos:prefLabel "thing"@en ;
    skos:definition "Any physical thing"@en ;
.

eg:solid
    rdf:type skos:Concept ;
    skos:inScheme eg:vocab ;
    skos:broader eg:thing ;
    skos:prefLabel "solid"@en ;
    skos:definition "A thing that was considered solid at the time of observation"@en ;
.

graph {
    rankdir=RL ;
    node [
        style=filled;
        fillcolor="white"; 
    ];
    subgraph clusterEx {
        label="<https://example.net/my/minimal/vocab>" ;
        bgcolor="#0044ff22" ;
        solid ;
        thing ;
        solid -- thing [dir=forward label="broader"];
    }
}

**Example.** A minimal vocabulary that defines two concepts "thing" and "living_thing" within the vocabulary `<https://example.net/my/minimal/vocabulary>`.

## Extending a Vocabulary

A vocabulary extension is used to augment an existing vocabulary, typically by adding more narrowly construed concepts ("narrower terms").

In iSamples, a vocabulary extension is a vocabulary where the `skos:ConceptScheme` instance includes a `skos:inScheme` predicate that refers to the `skos:ConceptScheme` of the vocabulary being extended. This is used programmatically to identify the vocabulary being extended and to help ensure that `skos:Concept` instances directly or indirectly extend the base vocabulary.

An extension vocabulary must include one or more instances of `skos:Concept`. Each instance must have a `skos:broader` predicate. Following a path of `skos:broader` properties must lead to a `skos:Concept` that is a `skos:topConceptOf` the base vocabulary directly or indirectly referred to by the `skos:inScheme` property of the `skos:ConceptScheme` instance of the extension vocabulary.

@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@prefix eg: <https://example.net/my/minimal/> .
@prefix ext: <https://example.net/my/extension/> .

ext:vocab
    rdf:type skos:ConceptScheme ;
    skos:prefLabel "Simple Vocabulary Extension"@en ;
    skos:inScheme eg:vocab ;
.    

ext:liquid 
    rdf:type skos:Concept ;
    skos:prefLabel "liquid"@en ;
    skos:definition "A thing that was considered to be of a liquid state at the time of observation"@en ;
    skos:inScheme ext:vocab ;
    skos:broader eg:thing ;
.

graph {
    rankdir=RL ;
    node [
        style=filled;
        fillcolor="white"; 
    ]
    subgraph clusterExt {
        label="<https://example.net/my/extension/vocab>" ;
        bgcolor="#00888822";

        subgraph clusterEx {
            label="<https://example.net/my/minimal/vocab>" ;
            bgcolor="#0044ff22" ;
            solid ;
            thing ;
            solid -- thing [dir=forward label="broader"];
        }

        liquid ;
        liquid -- thing [dir=forward label="broader"];
    }
}

**Example.** An extension vocabulary that extends `<https://example.net/my/minimal/vocabulary>` with a single concept.

## Other Semantic Relations

In many cases it is desireable to cross reference vocabulary concepts with concepts defined elsewhere. There are several `skos` predicates describing [semantic](https://www.w3.org/TR/2009/REC-skos-reference-20090818/#semantic-relations) and [mapping](https://www.w3.org/TR/2009/REC-skos-reference-20090818/#mapping) relations that can be helpful for describing the relationships between terms and vocabularies. These include:

* `skos:narrower`
* `skos:related`
* `skos:broaderTransitive`
* `skos:narrowerTransitive`
* `skos:closeMatch`
* `skos:exactMatch`
* `skos:broadMatch`
* `skos:narrowMatch`
* `skos:relatedMatch`

[^a]: The containing vocabulary may be inferred by traversing semantic relations such as `skos:broader` to find a semantically related concept that includes `skos:inScheme` or `skos:topConceptOf`, but including `skos:inScheme` with each concept provides a more explicit construct for consumers.

[^b]: Only one `skos:prefLabel` and one `skos:definition` per language is permitted.