Reuse MODAVIS: build a small evidence graph

1. Begin with a question, then identify the things#

Ask a small question: “Which digital representation refers to this instrument?” Give the instrument and representation separate stable identifiers. RDFRDFA graph data model: statements connect a subject to an object through an identified relationship. For Cuntz, an observation can point to the pipe it describes and the evidence it uses.Follow a Cuntz observation through the graph →Close × records a connection as a subject, a predicate and an object. Turtle is a compact text notation for those triples. Prefixes shorten complete IRIs; they do not change their meaning.

The starter graph is deliberately generic. It uses ex:instrument and ex:model under https://example.org/modavis/learning/. These are practice identifiers, not identifiers from the Cuntz release. For your own work, use your project’s governed identity route and qualified sources. A model represents an object; that relationship never establishes that the two are the same thing.

2. Reuse the modules your question needs#

Use generic Instrument terms for a violin, bell or another instrument; Organ supplies a specialization, not a universal template. Audio and MIDI concern signal and protocol records. Events records historical occurrences. Virtual InstrumentVirtual instrumentA playable digital representation whose behaviour depends on particular resources, mappings and software. It is not identical to the physical instrument it may represent.Work through the Cuntz example →Close × separates playable instruments, products, versions and packages. Heritage governs contextual recognition and knowledge snapshots; Vocab supplies reviewed SKOSSKOSA model for controlled concepts, labels and their relationships. A vocabulary concept such as an instrument type remains distinct from a particular museum object.Separate a Cuntz label from a type concept →Close × concepts. Reuse the term whose definition fits your subject instead of choosing by a familiar name alone.

3. Read the complete first graph#

# Teaching adaptation of MODAVIS Ontology Network 0.1.0 examples.
# Author: Dominik Ukolov / MODAVIS. Source terms and fixtures: CC BY 4.0.
# This generic learning graph does not assert historical facts about Cuntz.
@prefix ex: <https://example.org/modavis/learning/> .
@prefix modavis: <https://w3id.org/modavis/ontology/core#> .
@prefix modinst: <https://w3id.org/modavis/ontology/instrument#> .
@prefix modmedia: <https://w3id.org/modavis/ontology/media#> .
@prefix insttype: <https://w3id.org/modavis/vocab/instrument-type/> .
@prefix repstatus: <https://w3id.org/modavis/vocab/representation-status/> .

ex:instrument a modinst:MusicalInstrument ;
  modavis:canonicalLabel "Learning organ"@en ;
  modinst:instrumentType insttype:pipe-organ .

ex:model a modmedia:DigitalRepresentation ;
  modavis:canonicalLabel "Illustrative model"@en ;
  modmedia:representationOf ex:instrument ;
  modmedia:representationStatus repstatus:authored .

The namespace IRIs above identify public terms. The validator below pins their meanings and constraints by loading the 0.1.0 release files. Do not append /0.1.0/ to a term namespace just because module documents have version IRIs. Term identity and the immutable ontology document that declares it are separate roles.

4. Validate with the pinned release hierarchy#

Download and extract the ontology release. Use its source/ directory as the working directory: it contains ontology/, vocab/, shapes/ and requirements-dev.txt. Prepare a separate environment and install its pinned dependencies. Keep this environment separate from the VAO tools if their dependency locks differ.

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --require-hashes -r requirements-dev.txt

Run the kit’s helper from that directory, replacing the example kit path with the location where you extracted it. The helper loads every local ontology and vocabulary file as class-hierarchy knowledge, then the exchange shapes. It intentionally excludes the publication profileProfileA versioned set of additional requirements. A client must satisfy the declared capabilities before claiming full support for that profile.Work through the Cuntz example →Close ×, whose additional requirements concern publication resources. It fetches no remote imports and runs no general inference.

python /path/to/modavis-learning-kit/verify-graph.py --release . --data /path/to/modavis-learning-kit/learning-instrument.ttl
python /path/to/modavis-learning-kit/verify-graph.py --release . --data /path/to/modavis-learning-kit/invalid-self-representation.ttl

Inspect the failing record and change its represented resource back to ex:instrument. Never “fix” the exercise by deleting the applicable shape. A valid positive example and a failing negative example make the rule understandable and demonstrate that your local checking path is active. Neither report establishes historical truth.

5. Query the question you started with#

PREFIX modavis: <https://w3id.org/modavis/ontology/core#>
PREFIX modmedia: <https://w3id.org/modavis/ontology/media#>
SELECT ?representation ?label ?subject WHERE {
  ?representation modmedia:representationOf ?subject ;
                  modavis:canonicalLabel ?label .
}

from pathlib import Path
from rdflib import Graph
kit = Path('/path/to/modavis-learning-kit')
graph = Graph().parse(kit / 'learning-instrument.ttl', format='turtle')
for row in graph.query((kit / 'representations.rq').read_text()):
    print(row.representation, row.label, row.subject)

The positive fixture returns one row: the model IRI, “Illustrative model”, and the instrument IRI. A query result shows what this graph says. It is not an independently verified attribution or a search across every MODAVIS collection.

6. Grow through qualified records, not invented shortcuts#

For a source-backed claim, study the released event-assertionAssertionA statement that can be identified, attributed, qualified and reviewed. Its presence in a source or dataset does not by itself establish truth.Work through the Cuntz example →Close ×.ttl example. It records a SourceResource, a checksum-fixed SourceSnapshot, a SourceFragment with a Selector, an EvidenceRelation and an Assertion. The assertion uses assertsSubject, assertsPredicate and assertsObject or assertsLiteral, plus its status and generating activity. Use rawValue for source wording when needed; a literal’s datatype and language still matter for comparison.

Keep context separate from provenanceProvenanceThe documented origin and processing or editorial history of a resource or statement. It explains how a result came about.Work through the Cuntz example →Close ×. ContextBinding explains where, when or from which perspective an assertion applies. PROV-O-compatible activities and agents explain how the record was produced. A recent cataloguing date can describe a claim about an older instrument stateInstrument stateA historically scoped condition or arrangement of an instrument. A statement about one state should not automatically describe the instrument at every date.Work through the Cuntz example →Close ×. No context binding means unqualified or unknown applicability, not validity for all time.

For components, read the complete released violin example. hasComponent is useful for discovery; ComponentMembership and FunctionalRoleAssignment preserve the structural and functional distinctions when scope matters. A string can remain the same component while a documented membership or role assignment changes. Do not copy an organ-specific property into a non-organ project merely to make a shape pass.

7. Reuse, profile or extend: make the choice explicit#

Use the fourteen-module network as a shared vocabulary for your research questions, not a reason to invent fields for every module in every graph. Start with the small, tested question above. Add one qualified relationship at a time, keep a positive and negative fixture for your own requirements, and make the sources and unresolved claims available to the next researcher.