{
"title": "Reuse MODAVIS: build a small evidence graph — Ontologies & vocabularies",
"text": "MODAVIS (2026). Reuse MODAVIS: build a small evidence graph — Ontologies & vocabularies. Research notebooks, October 2026 · Wider reading and source audit edition. https://modavis.org/editions/2026-10-reading/ontologies/reuse/",
"bibtex": "@misc{modavis_ontologies_reuse_2026_10_reading,\n author = {{MODAVIS}},\n title = {Reuse MODAVIS: build a small evidence graph — Ontologies & vocabularies},\n year = {2026},\n month = {10},\n version = {2026-10-reading},\n url = {https://modavis.org/editions/2026-10-reading/ontologies/reuse/},\n note = {Content SHA-256: 4dc77c9593a9078770b1f10011d754f0fbdf6fc5e1a6d5938d0633d841bab70e}\n}",
"url": "https://modavis.org/editions/2026-10-reading/ontologies/reuse/",
"sha256": "4dc77c9593a9078770b1f10011d754f0fbdf6fc5e1a6d5938d0633d841bab70e",
"edition": "2026-10-reading",
"date": "2026-10-09",
"canonicalPayload": "{\"book\":{\"number\":\"07\",\"slug\":\"ontologies\",\"title\":\"Ontologies & vocabularies\"},\"chapter\":{\"blocks\":[{\"text\":\"A small RDF graph using actual MODAVIS 0.1.0 terms, a successful exchange-profile check, an intentionally failing comparison, and a query you can adapt. Allow about 30–45 minutes. You need Python and the ontology release’s dependencies; prior RDF experience is helpful but not required.\",\"title\":\"Your outcome\",\"type\":\"note\"},{\"id\":\"graph-question\",\"text\":\"1. Begin with a question, then identify the things\",\"type\":\"heading\"},{\"text\":\"Ask a small question: “Which digital representation refers to this instrument?” Give the instrument and representation separate stable identifiers. RDF 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.\",\"type\":\"p\"},{\"type\":\"visual\",\"visual\":{\"caption\":\"Read the triple as “ex:model representationOf ex:instrument”. Never merge the two identities with owl:sameAs.\",\"layout\":\"compare\",\"nodes\":[{\"detail\":\"MusicalInstrument: the research subject.\",\"icon\":\"compass\",\"label\":\"Instrument IRI\",\"value\":\"ex:instrument\"},{\"detail\":\"DigitalRepresentation: a separate digital resource.\",\"icon\":\"cube\",\"label\":\"Representation IRI\",\"value\":\"ex:model\"}],\"title\":\"Two subjects, one explicit relation\"}},{\"text\":\"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.\",\"type\":\"p\"},{\"byteSize\":7547,\"description\":\"A small, attributed VAO 0.5.0 workspace fixture, a generic MODAVIS graph, an intentionally invalid graph, a SPARQL query and a local validation helper. The fixture is not the Cuntz dataset; the full normative tools come from the linked releases.\",\"format\":\"ZIP\",\"id\":\"reuse-starter-kit\",\"sha256\":\"f287c5bae8d772937c74677e98c869c6ad387d443b193c3fef92ebf6a2b656b3\",\"src\":\"/examples/modavis-learning-kit-f287c5bae8d77293.zip\",\"title\":\"Download the reuse starter kit\",\"type\":\"file\"},{\"id\":\"choose-modules\",\"text\":\"2. Reuse the modules your question needs\",\"type\":\"heading\"},{\"type\":\"visual\",\"visual\":{\"caption\":\"The full network has fourteen modules. You can learn with a small graph while the validator loads the released hierarchy required by its profiles.\",\"layout\":\"flow\",\"nodes\":[{\"detail\":\"Labels, instrument identity, states and components; organ specialization only when appropriate.\",\"icon\":\"compass\",\"label\":\"Describe the subject\",\"value\":\"Core · Instrument · Organ\"},{\"detail\":\"Sources, attributable statements and explicit applicability.\",\"icon\":\"network\",\"label\":\"Explain the claim\",\"value\":\"Evidence · Assertion · Context\"},{\"detail\":\"Representation status, exact resources and processing lineage.\",\"icon\":\"cube\",\"label\":\"Describe the digital resource\",\"value\":\"Media · Provenance\"}],\"title\":\"Choose meaning by responsibility\"}},{\"text\":\"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 Instrument separates playable instruments, products, versions and packages. Heritage governs contextual recognition and knowledge snapshots; Vocab supplies reviewed SKOS concepts. Reuse the term whose definition fits your subject instead of choosing by a familiar name alone.\",\"type\":\"p\"},{\"id\":\"write-first-triples\",\"text\":\"3. Read the complete first graph\",\"type\":\"heading\"},{\"label\":\"Turtle · complete generic teaching graph\",\"text\":\"# Teaching adaptation of MODAVIS Ontology Network 0.1.0 examples.\\n# Author: Dominik Ukolov / MODAVIS. Source terms and fixtures: CC BY 4.0.\\n# This generic learning graph does not assert historical facts about Cuntz.\\n@prefix ex: .\\n@prefix modavis: .\\n@prefix modinst: .\\n@prefix modmedia: .\\n@prefix insttype: .\\n@prefix repstatus: .\\n\\nex:instrument a modinst:MusicalInstrument ;\\n modavis:canonicalLabel \\\"Learning organ\\\"@en ;\\n modinst:instrumentType insttype:pipe-organ .\\n\\nex:model a modmedia:DigitalRepresentation ;\\n modavis:canonicalLabel \\\"Illustrative model\\\"@en ;\\n modmedia:representationOf ex:instrument ;\\n modmedia:representationStatus repstatus:authored .\\n\",\"type\":\"code\"},{\"headers\":[\"Notation\",\"Read it as\"],\"rows\":[[\"@prefix modmedia: …\",\"Use a short name for the released Media term namespace.\"],[\"a modinst:MusicalInstrument\",\"The resource is declared to be a musical instrument.\"],[\"\\\"Learning organ\\\"@en\",\"A readable label whose language is English.\"],[\"modmedia:representationOf ex:instrument\",\"This separate representation depicts the identified instrument.\"],[\"repstatus:authored\",\"A governed representation status for this deliberately authored teaching example.\"]],\"type\":\"table\"},{\"text\":\"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.\",\"type\":\"p\"},{\"boundary\":\"The displayed model is a derived visualization with an unverified physical scale. Being about the Cuntz organ does not make every visible detail a measured historical fact.\",\"concept\":\"An ontology is an explicit agreement about the kinds of things we describe and the relationships between them. Its first useful distinction here is between an instrument and a representation of it.\",\"expanded\":false,\"id\":\"cuntz-identity\",\"scenario\":\"The physical Cuntz positive organ is identified as mXp 4010243. The release also contains a geometric model and audio files. They concern the instrument, but each has its own identity.\",\"sources\":[{\"detail\":\"Published manifest: identities, measurement observations, realization digests, profiles and rights. Exact examples checked against this release.\",\"href\":\"https://doi.org/10.5281/zenodo.22151203\",\"label\":\"Cuntz Positiv · VAO 0.5.0-rc.2\"},{\"detail\":\"Identity, state, configuration, evidence, assertions, context and provenance. Teaching examples explain its distinctions without inventing new normative properties.\",\"href\":\"https://doi.org/10.5281/zenodo.22126086\",\"label\":\"MODAVIS Ontology Network 0.1.0\"}],\"steps\":[{\"text\":\"Use the instrument identity for claims about the organ itself. Its record can link to the museum and to documentary evidence.\",\"title\":\"Name the physical subject\"},{\"text\":\"Give a model, a recording and a playable software product separate identities. A relationship such as “represents this instrument” connects them without declaring them the same thing.\",\"title\":\"Name each representation\"},{\"text\":\"Compressing the model changes its digital realization. It does not rebuild the museum instrument. Repairing a physical component is a different event and needs its own evidence.\",\"title\":\"Follow a change\"}],\"takeaway\":\"An identity answers “which thing?”; a representation relationship answers “what is this about?”.\",\"title\":\"Is the 3D model the Cuntz organ?\",\"type\":\"example\",\"visual\":{\"caption\":\"“Represents” connects these identities; high visual fidelity does not make them identical.\",\"layout\":\"compare\",\"nodes\":[{\"detail\":\"The instrument the research concerns.\",\"icon\":\"compass\",\"label\":\"Physical subject\",\"value\":\"Cuntz positive organ\"},{\"detail\":\"A file representing selected visible features.\",\"icon\":\"cube\",\"label\":\"Digital representation\",\"value\":\"The GLB model\"}],\"title\":\"A representation keeps its own identity\"}},{\"id\":\"validate-graph\",\"text\":\"4. Validate with the pinned release hierarchy\",\"type\":\"heading\"},{\"text\":\"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.\",\"type\":\"p\"},{\"items\":[{\"detail\":\"Terms, governed vocabularies, versioned shapes and interpretation guide.\",\"href\":\"https://doi.org/10.5281/zenodo.22126086\",\"label\":\"MODAVIS Ontology Network 0.1.0 · immutable release\"}],\"type\":\"links\"},{\"label\":\"Ontology 0.1.0 source/ root · environment setup\",\"text\":\"python3 -m venv .venv\\n. .venv/bin/activate\\npython -m pip install --require-hashes -r requirements-dev.txt\",\"type\":\"code\"},{\"text\":\"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 profile, whose additional requirements concern publication resources. It fetches no remote imports and runs no general inference.\",\"type\":\"p\"},{\"label\":\"Ontology source/ root · positive and negative checks\",\"text\":\"python /path/to/modavis-learning-kit/verify-graph.py --release . --data /path/to/modavis-learning-kit/learning-instrument.ttl\\npython /path/to/modavis-learning-kit/verify-graph.py --release . --data /path/to/modavis-learning-kit/invalid-self-representation.ttl\",\"type\":\"code\"},{\"type\":\"visual\",\"visual\":{\"caption\":\"The negative graph should report a representation cycle and return exit code 1. That failure is the intended learning result, not a broken installation.\",\"layout\":\"compare\",\"nodes\":[{\"detail\":\"The generic model represents the distinct instrument.\",\"icon\":\"check\",\"label\":\"Separate identities\",\"value\":\"Conforms: True\"},{\"detail\":\"The invalid variant makes the model represent itself.\",\"icon\":\"reset\",\"label\":\"Self-representation\",\"value\":\"Conforms: False\"}],\"title\":\"Read the two reports side by side\"}},{\"text\":\"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.\",\"type\":\"p\"},{\"id\":\"query-the-connection\",\"text\":\"5. Query the question you started with\",\"type\":\"heading\"},{\"label\":\"SPARQL · which representation refers to which subject?\",\"text\":\"PREFIX modavis: \\nPREFIX modmedia: \\nSELECT ?representation ?label ?subject WHERE {\\n ?representation modmedia:representationOf ?subject ;\\n modavis:canonicalLabel ?label .\\n}\",\"type\":\"code\"},{\"label\":\"Python · execute the query over the kit graph\",\"text\":\"from pathlib import Path\\nfrom rdflib import Graph\\nkit = Path('/path/to/modavis-learning-kit')\\ngraph = Graph().parse(kit / 'learning-instrument.ttl', format='turtle')\\nfor row in graph.query((kit / 'representations.rq').read_text()):\\n print(row.representation, row.label, row.subject)\",\"type\":\"code\"},{\"text\":\"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.\",\"type\":\"p\"},{\"id\":\"grow-evidence-graph\",\"text\":\"6. Grow through qualified records, not invented shortcuts\",\"type\":\"heading\"},{\"type\":\"visual\",\"visual\":{\"caption\":\"Context bindings qualify the assertion’s applicability; provenance describes the record’s production. These are additional links, not a single undifferentiated date field.\",\"layout\":\"network\",\"nodes\":[{\"detail\":\"A selector locates evidence in a fixed source snapshot.\",\"icon\":\"book\",\"label\":\"Source fragment\",\"value\":\"An inspectable passage\"},{\"detail\":\"Supporting, opposing or another governed role.\",\"icon\":\"network\",\"label\":\"Evidence relation\",\"value\":\"How the source bears on it\"},{\"detail\":\"Subject, predicate, value, status and generating activity.\",\"icon\":\"quote\",\"label\":\"Assertion\",\"value\":\"An attributable claim\"}],\"relations\":[\"is used by an evidence relation\",\"is evaluated by that relation\"],\"title\":\"A qualified claim remains connected to its grounds\"}},{\"text\":\"For a source-backed claim, study the released event-assertion.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.\",\"type\":\"p\"},{\"text\":\"Keep context separate from provenance. 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 state. No context binding means unqualified or unknown applicability, not validity for all time.\",\"type\":\"p\"},{\"type\":\"visual\",\"visual\":{\"caption\":\"Use ComponentMembership when instrument, parent, type or scope matters. The direct hasComponent link is a discovery shortcut.\",\"layout\":\"network\",\"nodes\":[{\"detail\":\"The generic released example works beyond organs.\",\"icon\":\"compass\",\"label\":\"Instrument\",\"value\":\"A violin\"},{\"detail\":\"A component identity is distinct from membership.\",\"icon\":\"wave\",\"label\":\"Component\",\"value\":\"Its string\"},{\"detail\":\"A FunctionalRoleAssignment carries the role.\",\"icon\":\"network\",\"label\":\"Assigned role\",\"value\":\"Sound generator\"}],\"relations\":[\"has a component record\",\"has a role assignment\"],\"title\":\"A component’s role is an identified assignment\"}},{\"text\":\"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.\",\"type\":\"p\"},{\"boundary\":\"This is a teaching application of the assertion model, not a claim that a new authoritative review of the historical register mapping has been completed.\",\"concept\":\"An assertion is an attributable claim. A review decision records how that claim is interpreted; a projection is a selected view of the reviewed knowledge.\",\"expanded\":false,\"id\":\"cuntz-assertions\",\"scenario\":\"The Cuntz thesis description and the digital inventory present different register counts. Treating the latest imported count as an unconditional replacement would erase the question the discrepancy raises.\",\"sources\":[{\"detail\":\"Published manifest: identities, measurement observations, realization digests, profiles and rights. Exact examples checked against this release.\",\"href\":\"https://doi.org/10.5281/zenodo.22151203\",\"label\":\"Cuntz Positiv · VAO 0.5.0-rc.2\"},{\"detail\":\"Identity, state, configuration, evidence, assertions, context and provenance. Teaching examples explain its distinctions without inventing new normative properties.\",\"href\":\"https://doi.org/10.5281/zenodo.22126086\",\"label\":\"MODAVIS Ontology Network 0.1.0\"},{\"detail\":\"Submitted dissertation, 11 September 2026; §§8.2.2.1 and 8.4.1, printed pp. 264–265 and 275–276. The historical description and digital inventory require a resolved mapping; the manuscript is not redistributed here.\",\"label\":\"Dominik Ukolov · Musikinstrumente im virtuellen Raum (2026)\"}],\"steps\":[{\"text\":\"Retain the four-register physical description and the five-label digital configuration, including their sources and intended subjects.\",\"title\":\"Store both claims with their scope\"},{\"text\":\"Ask whether the accounts concern comparable states and counting units. The missing Regal 8′ mapping remains an explicit review issue rather than an invented explanation.\",\"title\":\"Review the relationship\"},{\"text\":\"A catalogue summary can show a selected statement and its qualification, while an evidence view exposes the other assertion and the reason the relationship remains unresolved.\",\"title\":\"Publish an understandable view\"}],\"takeaway\":\"A clean interface can present an editorial decision without deleting the evidence behind competing interpretations.\",\"title\":\"How can two accounts disagree without corrupting the database?\",\"type\":\"example\",\"visual\":{\"caption\":\"Two assertions can coexist. A reviewed display must explain its selection instead of deleting the alternative.\",\"layout\":\"compare\",\"nodes\":[{\"detail\":\"Its source, scope and review status stay visible.\",\"icon\":\"quote\",\"label\":\"Account A\",\"value\":\"A sourced assertion\"},{\"detail\":\"Retain disagreement until its grounds are reviewed.\",\"icon\":\"quote\",\"label\":\"Account B\",\"value\":\"Another sourced assertion\"}],\"title\":\"A claim is a record you can inspect\"}},{\"id\":\"extend-responsibly\",\"text\":\"7. Reuse, profile or extend: make the choice explicit\",\"type\":\"heading\"},{\"headers\":[\"Your need\",\"A reusable approach\"],\"rows\":[[\"The existing definition fits\",\"Use the published term and retain its declared semantics.\"],[\"Your collection requires a narrower record\",\"Create a versioned application SHACL profile with documented requirements.\"],[\"Your subject has a concept the network does not express\",\"Use a project-owned namespace and document the extension; keep its scope clear.\"],[\"You link another ontology or classification scheme\",\"Publish a separately owned, versioned mapping. Avoid unsupported equivalence or owl:sameAs claims.\"],[\"You publish a revised research record\",\"Retain source assertions, decisions and snapshot identity; do not overwrite the earlier account.\"]],\"type\":\"table\"},{\"text\":\"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.\",\"type\":\"p\"},{\"items\":[{\"detail\":\"Four visual lessons on identity, membership, context and checking.\",\"href\":\"/notebooks/ontologies/graph-lab/\",\"label\":\"Practice these graph decisions\"},{\"detail\":\"Move from the generic fixture to the released source record.\",\"href\":\"/notebooks/ontologies/cuntz/\",\"label\":\"Review a real Cuntz observation\"},{\"detail\":\"Keep versions, fixity, rights, evidence and report scope together.\",\"href\":\"/notebooks/standards/reuse-checklist/\",\"label\":\"Release-readiness checklist\"}],\"type\":\"links\"}],\"intro\":\"Use the released ontology to distinguish an instrument from its representation, attach accountable evidence, and validate a small graph. Start with a real, runnable fixture and extend it only when your research question needs more.\",\"slug\":\"reuse\",\"sources\":[{\"detail\":\"Terms, governed vocabularies, versioned shapes and interpretation guide.\",\"href\":\"https://doi.org/10.5281/zenodo.22126086\",\"label\":\"MODAVIS Ontology Network 0.1.0 · immutable release\"},{\"detail\":\"\",\"href\":\"https://github.com/modavis-project/modavis-ontology-network/blob/0.1.0/docs/INTERPRETATION_GUIDE.md\",\"label\":\"MODAVIS 0.1.0 interpretation guide\"},{\"detail\":\"\",\"href\":\"https://github.com/modavis-project/modavis-ontology-network/blob/0.1.0/examples/valid/violin.ttl\",\"label\":\"Released non-organ example: violin\"},{\"detail\":\"\",\"href\":\"https://github.com/modavis-project/modavis-ontology-network/blob/0.1.0/examples/valid/event-assertion.ttl\",\"label\":\"Released assertion and context example\"},{\"detail\":\"Specification, schemas, reference tools and fixtures. Use this exact standard version for the exercises.\",\"href\":\"https://doi.org/10.5281/zenodo.22214248\",\"label\":\"VAO Standard 0.5.0 · immutable release\"},{\"detail\":\"The real observation and model used for the Cuntz examples. Its content version differs from VAO formatVersion 0.5.0.\",\"href\":\"https://doi.org/10.5281/zenodo.22151203\",\"label\":\"Cuntz Positiv · content release 0.5.0-rc.2\"}],\"title\":\"Reuse MODAVIS: build a small evidence graph\"},\"date\":\"2026-10-09\",\"edition\":\"2026-10-reading\",\"figures\":{}}",
"payload": {
"edition": "2026-10-reading",
"date": "2026-10-09",
"book": {
"slug": "ontologies",
"title": "Ontologies & vocabularies",
"number": "07"
},
"chapter": {
"slug": "reuse",
"title": "Reuse MODAVIS: build a small evidence graph",
"intro": "Use the released ontology to distinguish an instrument from its representation, attach accountable evidence, and validate a small graph. Start with a real, runnable fixture and extend it only when your research question needs more.",
"sources": [
{
"label": "MODAVIS Ontology Network 0.1.0 · immutable release",
"href": "https://doi.org/10.5281/zenodo.22126086",
"detail": "Terms, governed vocabularies, versioned shapes and interpretation guide."
},
{
"label": "MODAVIS 0.1.0 interpretation guide",
"href": "https://github.com/modavis-project/modavis-ontology-network/blob/0.1.0/docs/INTERPRETATION_GUIDE.md",
"detail": ""
},
{
"label": "Released non-organ example: violin",
"href": "https://github.com/modavis-project/modavis-ontology-network/blob/0.1.0/examples/valid/violin.ttl",
"detail": ""
},
{
"label": "Released assertion and context example",
"href": "https://github.com/modavis-project/modavis-ontology-network/blob/0.1.0/examples/valid/event-assertion.ttl",
"detail": ""
},
{
"label": "VAO Standard 0.5.0 · immutable release",
"href": "https://doi.org/10.5281/zenodo.22214248",
"detail": "Specification, schemas, reference tools and fixtures. Use this exact standard version for the exercises."
},
{
"label": "Cuntz Positiv · content release 0.5.0-rc.2",
"href": "https://doi.org/10.5281/zenodo.22151203",
"detail": "The real observation and model used for the Cuntz examples. Its content version differs from VAO formatVersion 0.5.0."
}
],
"blocks": [
{
"type": "note",
"title": "Your outcome",
"text": "A small RDF graph using actual MODAVIS 0.1.0 terms, a successful exchange-profile check, an intentionally failing comparison, and a query you can adapt. Allow about 30–45 minutes. You need Python and the ontology release’s dependencies; prior RDF experience is helpful but not required."
},
{
"type": "heading",
"id": "graph-question",
"text": "1. Begin with a question, then identify the things"
},
{
"type": "p",
"text": "Ask a small question: “Which digital representation refers to this instrument?” Give the instrument and representation separate stable identifiers. RDF 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."
},
{
"type": "visual",
"visual": {
"layout": "compare",
"title": "Two subjects, one explicit relation",
"nodes": [
{
"label": "Instrument IRI",
"value": "ex:instrument",
"detail": "MusicalInstrument: the research subject.",
"icon": "compass"
},
{
"label": "Representation IRI",
"value": "ex:model",
"detail": "DigitalRepresentation: a separate digital resource.",
"icon": "cube"
}
],
"caption": "Read the triple as “ex:model representationOf ex:instrument”. Never merge the two identities with owl:sameAs."
}
},
{
"type": "p",
"text": "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."
},
{
"type": "file",
"id": "reuse-starter-kit",
"title": "Download the reuse starter kit",
"format": "ZIP",
"src": "/examples/modavis-learning-kit-f287c5bae8d77293.zip",
"sha256": "f287c5bae8d772937c74677e98c869c6ad387d443b193c3fef92ebf6a2b656b3",
"byteSize": 7547,
"description": "A small, attributed VAO 0.5.0 workspace fixture, a generic MODAVIS graph, an intentionally invalid graph, a SPARQL query and a local validation helper. The fixture is not the Cuntz dataset; the full normative tools come from the linked releases."
},
{
"type": "heading",
"id": "choose-modules",
"text": "2. Reuse the modules your question needs"
},
{
"type": "visual",
"visual": {
"layout": "flow",
"title": "Choose meaning by responsibility",
"nodes": [
{
"label": "Describe the subject",
"value": "Core · Instrument · Organ",
"detail": "Labels, instrument identity, states and components; organ specialization only when appropriate.",
"icon": "compass"
},
{
"label": "Explain the claim",
"value": "Evidence · Assertion · Context",
"detail": "Sources, attributable statements and explicit applicability.",
"icon": "network"
},
{
"label": "Describe the digital resource",
"value": "Media · Provenance",
"detail": "Representation status, exact resources and processing lineage.",
"icon": "cube"
}
],
"caption": "The full network has fourteen modules. You can learn with a small graph while the validator loads the released hierarchy required by its profiles."
}
},
{
"type": "p",
"text": "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 Instrument separates playable instruments, products, versions and packages. Heritage governs contextual recognition and knowledge snapshots; Vocab supplies reviewed SKOS concepts. Reuse the term whose definition fits your subject instead of choosing by a familiar name alone."
},
{
"type": "heading",
"id": "write-first-triples",
"text": "3. Read the complete first graph"
},
{
"type": "code",
"label": "Turtle · complete generic teaching graph",
"text": "# Teaching adaptation of MODAVIS Ontology Network 0.1.0 examples.\n# Author: Dominik Ukolov / MODAVIS. Source terms and fixtures: CC BY 4.0.\n# This generic learning graph does not assert historical facts about Cuntz.\n@prefix ex: .\n@prefix modavis: .\n@prefix modinst: .\n@prefix modmedia: .\n@prefix insttype: .\n@prefix repstatus: .\n\nex:instrument a modinst:MusicalInstrument ;\n modavis:canonicalLabel \"Learning organ\"@en ;\n modinst:instrumentType insttype:pipe-organ .\n\nex:model a modmedia:DigitalRepresentation ;\n modavis:canonicalLabel \"Illustrative model\"@en ;\n modmedia:representationOf ex:instrument ;\n modmedia:representationStatus repstatus:authored .\n"
},
{
"type": "table",
"headers": [
"Notation",
"Read it as"
],
"rows": [
[
"@prefix modmedia: …",
"Use a short name for the released Media term namespace."
],
[
"a modinst:MusicalInstrument",
"The resource is declared to be a musical instrument."
],
[
"\"Learning organ\"@en",
"A readable label whose language is English."
],
[
"modmedia:representationOf ex:instrument",
"This separate representation depicts the identified instrument."
],
[
"repstatus:authored",
"A governed representation status for this deliberately authored teaching example."
]
]
},
{
"type": "p",
"text": "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."
},
{
"type": "example",
"id": "cuntz-identity",
"title": "Is the 3D model the Cuntz organ?",
"concept": "An ontology is an explicit agreement about the kinds of things we describe and the relationships between them. Its first useful distinction here is between an instrument and a representation of it.",
"scenario": "The physical Cuntz positive organ is identified as mXp 4010243. The release also contains a geometric model and audio files. They concern the instrument, but each has its own identity.",
"steps": [
{
"title": "Name the physical subject",
"text": "Use the instrument identity for claims about the organ itself. Its record can link to the museum and to documentary evidence."
},
{
"title": "Name each representation",
"text": "Give a model, a recording and a playable software product separate identities. A relationship such as “represents this instrument” connects them without declaring them the same thing."
},
{
"title": "Follow a change",
"text": "Compressing the model changes its digital realization. It does not rebuild the museum instrument. Repairing a physical component is a different event and needs its own evidence."
}
],
"takeaway": "An identity answers “which thing?”; a representation relationship answers “what is this about?”.",
"boundary": "The displayed model is a derived visualization with an unverified physical scale. Being about the Cuntz organ does not make every visible detail a measured historical fact.",
"sources": [
{
"label": "Cuntz Positiv · VAO 0.5.0-rc.2",
"href": "https://doi.org/10.5281/zenodo.22151203",
"detail": "Published manifest: identities, measurement observations, realization digests, profiles and rights. Exact examples checked against this release."
},
{
"label": "MODAVIS Ontology Network 0.1.0",
"href": "https://doi.org/10.5281/zenodo.22126086",
"detail": "Identity, state, configuration, evidence, assertions, context and provenance. Teaching examples explain its distinctions without inventing new normative properties."
}
],
"visual": {
"layout": "compare",
"title": "A representation keeps its own identity",
"nodes": [
{
"label": "Physical subject",
"value": "Cuntz positive organ",
"detail": "The instrument the research concerns.",
"icon": "compass"
},
{
"label": "Digital representation",
"value": "The GLB model",
"detail": "A file representing selected visible features.",
"icon": "cube"
}
],
"caption": "“Represents” connects these identities; high visual fidelity does not make them identical."
},
"expanded": false
},
{
"type": "heading",
"id": "validate-graph",
"text": "4. Validate with the pinned release hierarchy"
},
{
"type": "p",
"text": "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."
},
{
"type": "links",
"items": [
{
"label": "MODAVIS Ontology Network 0.1.0 · immutable release",
"href": "https://doi.org/10.5281/zenodo.22126086",
"detail": "Terms, governed vocabularies, versioned shapes and interpretation guide."
}
]
},
{
"type": "code",
"label": "Ontology 0.1.0 source/ root · environment setup",
"text": "python3 -m venv .venv\n. .venv/bin/activate\npython -m pip install --require-hashes -r requirements-dev.txt"
},
{
"type": "p",
"text": "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 profile, whose additional requirements concern publication resources. It fetches no remote imports and runs no general inference."
},
{
"type": "code",
"label": "Ontology source/ root · positive and negative checks",
"text": "python /path/to/modavis-learning-kit/verify-graph.py --release . --data /path/to/modavis-learning-kit/learning-instrument.ttl\npython /path/to/modavis-learning-kit/verify-graph.py --release . --data /path/to/modavis-learning-kit/invalid-self-representation.ttl"
},
{
"type": "visual",
"visual": {
"layout": "compare",
"title": "Read the two reports side by side",
"nodes": [
{
"label": "Separate identities",
"value": "Conforms: True",
"detail": "The generic model represents the distinct instrument.",
"icon": "check"
},
{
"label": "Self-representation",
"value": "Conforms: False",
"detail": "The invalid variant makes the model represent itself.",
"icon": "reset"
}
],
"caption": "The negative graph should report a representation cycle and return exit code 1. That failure is the intended learning result, not a broken installation."
}
},
{
"type": "p",
"text": "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."
},
{
"type": "heading",
"id": "query-the-connection",
"text": "5. Query the question you started with"
},
{
"type": "code",
"label": "SPARQL · which representation refers to which subject?",
"text": "PREFIX modavis: \nPREFIX modmedia: \nSELECT ?representation ?label ?subject WHERE {\n ?representation modmedia:representationOf ?subject ;\n modavis:canonicalLabel ?label .\n}"
},
{
"type": "code",
"label": "Python · execute the query over the kit graph",
"text": "from pathlib import Path\nfrom rdflib import Graph\nkit = Path('/path/to/modavis-learning-kit')\ngraph = Graph().parse(kit / 'learning-instrument.ttl', format='turtle')\nfor row in graph.query((kit / 'representations.rq').read_text()):\n print(row.representation, row.label, row.subject)"
},
{
"type": "p",
"text": "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."
},
{
"type": "heading",
"id": "grow-evidence-graph",
"text": "6. Grow through qualified records, not invented shortcuts"
},
{
"type": "visual",
"visual": {
"layout": "network",
"title": "A qualified claim remains connected to its grounds",
"nodes": [
{
"label": "Source fragment",
"value": "An inspectable passage",
"detail": "A selector locates evidence in a fixed source snapshot.",
"icon": "book"
},
{
"label": "Evidence relation",
"value": "How the source bears on it",
"detail": "Supporting, opposing or another governed role.",
"icon": "network"
},
{
"label": "Assertion",
"value": "An attributable claim",
"detail": "Subject, predicate, value, status and generating activity.",
"icon": "quote"
}
],
"caption": "Context bindings qualify the assertion’s applicability; provenance describes the record’s production. These are additional links, not a single undifferentiated date field.",
"relations": [
"is used by an evidence relation",
"is evaluated by that relation"
]
}
},
{
"type": "p",
"text": "For a source-backed claim, study the released event-assertion.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."
},
{
"type": "p",
"text": "Keep context separate from provenance. 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 state. No context binding means unqualified or unknown applicability, not validity for all time."
},
{
"type": "visual",
"visual": {
"layout": "network",
"title": "A component’s role is an identified assignment",
"nodes": [
{
"label": "Instrument",
"value": "A violin",
"detail": "The generic released example works beyond organs.",
"icon": "compass"
},
{
"label": "Component",
"value": "Its string",
"detail": "A component identity is distinct from membership.",
"icon": "wave"
},
{
"label": "Assigned role",
"value": "Sound generator",
"detail": "A FunctionalRoleAssignment carries the role.",
"icon": "network"
}
],
"caption": "Use ComponentMembership when instrument, parent, type or scope matters. The direct hasComponent link is a discovery shortcut.",
"relations": [
"has a component record",
"has a role assignment"
]
}
},
{
"type": "p",
"text": "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."
},
{
"type": "example",
"id": "cuntz-assertions",
"title": "How can two accounts disagree without corrupting the database?",
"concept": "An assertion is an attributable claim. A review decision records how that claim is interpreted; a projection is a selected view of the reviewed knowledge.",
"scenario": "The Cuntz thesis description and the digital inventory present different register counts. Treating the latest imported count as an unconditional replacement would erase the question the discrepancy raises.",
"steps": [
{
"title": "Store both claims with their scope",
"text": "Retain the four-register physical description and the five-label digital configuration, including their sources and intended subjects."
},
{
"title": "Review the relationship",
"text": "Ask whether the accounts concern comparable states and counting units. The missing Regal 8′ mapping remains an explicit review issue rather than an invented explanation."
},
{
"title": "Publish an understandable view",
"text": "A catalogue summary can show a selected statement and its qualification, while an evidence view exposes the other assertion and the reason the relationship remains unresolved."
}
],
"takeaway": "A clean interface can present an editorial decision without deleting the evidence behind competing interpretations.",
"boundary": "This is a teaching application of the assertion model, not a claim that a new authoritative review of the historical register mapping has been completed.",
"sources": [
{
"label": "Cuntz Positiv · VAO 0.5.0-rc.2",
"href": "https://doi.org/10.5281/zenodo.22151203",
"detail": "Published manifest: identities, measurement observations, realization digests, profiles and rights. Exact examples checked against this release."
},
{
"label": "MODAVIS Ontology Network 0.1.0",
"href": "https://doi.org/10.5281/zenodo.22126086",
"detail": "Identity, state, configuration, evidence, assertions, context and provenance. Teaching examples explain its distinctions without inventing new normative properties."
},
{
"label": "Dominik Ukolov · Musikinstrumente im virtuellen Raum (2026)",
"detail": "Submitted dissertation, 11 September 2026; §§8.2.2.1 and 8.4.1, printed pp. 264–265 and 275–276. The historical description and digital inventory require a resolved mapping; the manuscript is not redistributed here."
}
],
"visual": {
"layout": "compare",
"title": "A claim is a record you can inspect",
"nodes": [
{
"label": "Account A",
"value": "A sourced assertion",
"detail": "Its source, scope and review status stay visible.",
"icon": "quote"
},
{
"label": "Account B",
"value": "Another sourced assertion",
"detail": "Retain disagreement until its grounds are reviewed.",
"icon": "quote"
}
],
"caption": "Two assertions can coexist. A reviewed display must explain its selection instead of deleting the alternative."
},
"expanded": false
},
{
"type": "heading",
"id": "extend-responsibly",
"text": "7. Reuse, profile or extend: make the choice explicit"
},
{
"type": "table",
"headers": [
"Your need",
"A reusable approach"
],
"rows": [
[
"The existing definition fits",
"Use the published term and retain its declared semantics."
],
[
"Your collection requires a narrower record",
"Create a versioned application SHACL profile with documented requirements."
],
[
"Your subject has a concept the network does not express",
"Use a project-owned namespace and document the extension; keep its scope clear."
],
[
"You link another ontology or classification scheme",
"Publish a separately owned, versioned mapping. Avoid unsupported equivalence or owl:sameAs claims."
],
[
"You publish a revised research record",
"Retain source assertions, decisions and snapshot identity; do not overwrite the earlier account."
]
]
},
{
"type": "p",
"text": "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."
},
{
"type": "links",
"items": [
{
"label": "Practice these graph decisions",
"href": "/notebooks/ontologies/graph-lab/",
"detail": "Four visual lessons on identity, membership, context and checking."
},
{
"label": "Review a real Cuntz observation",
"href": "/notebooks/ontologies/cuntz/",
"detail": "Move from the generic fixture to the released source record."
},
{
"label": "Release-readiness checklist",
"href": "/notebooks/standards/reuse-checklist/",
"detail": "Keep versions, fixity, rights, evidence and report scope together."
}
]
}
]
},
"figures": {}
}
}