{ "title": "Reuse VAO: your first validated package — Virtual Acoustic Objects", "text": "MODAVIS (2026). Reuse VAO: your first validated package — Virtual Acoustic Objects. Research notebooks, October 2026 · Illustrated reuse and learning edition. https://modavis.org/editions/2026-10-learning/vao/reuse/", "bibtex": "@misc{modavis_vao_reuse_2026_10_learning,\n author = {{MODAVIS}},\n title = {Reuse VAO: your first validated package — Virtual Acoustic Objects},\n year = {2026},\n month = {10},\n version = {2026-10-learning},\n url = {https://modavis.org/editions/2026-10-learning/vao/reuse/},\n note = {Content SHA-256: a64ac9e5d759116c4480eba0fe066cb1c38e58df1479dfd4d21064b85386c8eb}\n}", "url": "https://modavis.org/editions/2026-10-learning/vao/reuse/", "sha256": "a64ac9e5d759116c4480eba0fe066cb1c38e58df1479dfd4d21064b85386c8eb", "edition": "2026-10-learning", "date": "2026-10-09", "canonicalPayload": "{\"book\":{\"number\":\"01\",\"slug\":\"vao\",\"title\":\"Virtual Acoustic Objects\"},\"chapter\":{\"blocks\":[{\"text\":\"A validated practice workspace, a deterministic .vao carrier, an understanding of the manifest-to-file bindings, and a plan for adapting the standard to your own subject. Allow about 30–45 minutes for the first run, including environment setup. You need Python 3.11 or newer; no account, database or 3D software is needed.\",\"title\":\"What you will leave with\",\"type\":\"note\"},{\"type\":\"visual\",\"visual\":{\"caption\":\"A successful practice carrier gives you a working method. Your actual publication still needs its own sources, rights, identifiers and review.\",\"layout\":\"flow\",\"nodes\":[{\"detail\":\"Use the versioned release and an isolated working copy.\",\"icon\":\"book\",\"label\":\"Start small\",\"value\":\"A known-good fixture\"},{\"detail\":\"Trace a resource to the bytes and check its contract.\",\"icon\":\"search\",\"label\":\"Inspect & validate\",\"value\":\"Understand the report\"},{\"detail\":\"Replace identities, sources and capabilities as a coherent new release.\",\"icon\":\"compass\",\"label\":\"Adapt deliberately\",\"value\":\"Your research object\"}],\"relations\":[\"learn what the fields do\",\"carry the method forward\"],\"title\":\"Your first successful reuse loop\"}},{\"id\":\"choose-your-start\",\"text\":\"Choose a starting point you can finish\",\"type\":\"heading\"},{\"text\":\"Begin with one well-documented object and one resource. A museum catalogue note, a measured component, a recording or an attributed model can be a useful first focus. You do not need to build an acoustic simulator before using VAO. The envelope can preserve connections among familiar file formats while your project grows.\",\"type\":\"p\"},{\"type\":\"visual\",\"visual\":{\"caption\":\"You can learn either part first. VAO defines its own versioned mapping to MODAVIS; the ontology does not import the package format.\",\"layout\":\"compare\",\"nodes\":[{\"detail\":\"Describe exact resources and carry them together or selectively.\",\"icon\":\"layers\",\"label\":\"Package & delivery\",\"value\":\"VAO Standard\"},{\"detail\":\"Describe what subjects, claims and source relationships mean.\",\"icon\":\"network\",\"label\":\"Meaning & evidence\",\"value\":\"Ontology Network\"}],\"title\":\"Choose the contract that solves your problem\"}},{\"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\":\"install-release\",\"text\":\"1. Open the exact release and prepare the tools\",\"type\":\"heading\"},{\"text\":\"Download and extract VAO Standard 0.5.0 from its version DOI. Open a terminal in the extracted vao-standard-0.5.0 directory. The following commands create a local Python environment and install the release’s pinned dependencies. Use the source release that contains Docs/, Tools/, Schemas/ and Fixtures/.\",\"type\":\"p\"},{\"items\":[{\"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 commands here follow this fixed release, rather than a separately versioned client archive.\",\"href\":\"https://github.com/modavis-project/vao-standard/blob/v0.5.0/README.md\",\"label\":\"Installation and fixture commands\"}],\"type\":\"links\"},{\"label\":\"VAO 0.5.0 release root · environment setup\",\"text\":\"python3 -m venv .venv\\n. .venv/bin/activate\\npython -m pip install --require-hashes -r requirements-lock.txt\\npython Tools/vao05.py validate Fixtures/VAO05/workspaces/minimal\",\"type\":\"code\"},{\"text\":\"The final command should report VALID. If it does not, keep the diagnostic and confirm the working directory, Python environment and release version before changing the fixture. This establishes a known-good baseline for the tools, not a result about your own instrument.\",\"type\":\"p\"},{\"id\":\"inspect-workspace\",\"text\":\"2. Inspect the resource-to-file connection\",\"type\":\"heading\"},{\"type\":\"visual\",\"visual\":{\"caption\":\"The root also contains the exact mimetype entry. A carrier is a transport of one semantic release, not a replacement for WAV, GLB, images or research data.\",\"layout\":\"flow\",\"nodes\":[{\"detail\":\"Identified entities, resources, profiles and their relations.\",\"icon\":\"network\",\"label\":\"Semantic contract\",\"value\":\"vao-manifest.json\"},{\"detail\":\"Manifest pin and exact embedded member mapping.\",\"icon\":\"layers\",\"label\":\"Transport contract\",\"value\":\"vao-carrier.json\"},{\"detail\":\"The original formats and exact file bytes stay identifiable.\",\"icon\":\"database\",\"label\":\"Realizations\",\"value\":\"payload/…\"}],\"relations\":[\"binds this transport\",\"maps the embedded members\"],\"title\":\"What travels inside a VAO carrier?\"}},{\"text\":\"Extract the starter kit to a new learning folder. Its vao-workspace/ directory is an unchanged copy of the release’s minimal fixture. The manifest identifies one logical asset, one 69-byte text realization and one complete bootstrap group. The carrier descriptor maps that realization to payload/evidence/source.txt. Inspect the source note itself: it is a teaching resource, not a Cuntz measurement.\",\"type\":\"p\"},{\"label\":\"From the VAO release root · inspect the supplied fixture\",\"text\":\"python - <<'PY'\\nimport hashlib, json\\nfrom pathlib import Path\\nw = Path('Fixtures/VAO05/workspaces/minimal')\\nm = json.loads((w / 'vao-manifest.json').read_text())\\nc = json.loads((w / 'META-INF/vao-carrier.json').read_text())\\nmember = c['embeddedRealizations'][0]\\nr = next(item for item in m['realizations'] if item['id'] == member['realizationId'])\\nb = (w / member['path']).read_bytes()\\nprint('Format:', m['formatVersion'])\\nprint('Member:', member['path'])\\nprint('Bytes:', len(b), 'expected:', r['byteSize'])\\nprint('SHA-256:', hashlib.sha256(b).hexdigest())\\nprint('Recorded:', r['contentDigests'][0]['value'])\\nPY\",\"type\":\"code\"},{\"text\":\"You should see format 0.5.0, the source.txt member, byte length 69, and matching computed and recorded SHA-256 values. Notice how the path is discovered through the descriptor; the name alone is not the realization identity. This inspection script illustrates the binding. The reference validator performs the wider conformance checks.\",\"type\":\"p\"},{\"boundary\":\"The smaller web derivative has not been retroactively inserted into the published VAO manifest.\",\"concept\":\"A logical asset names a role in the research object. A realization identifies one exact encoding of that asset. A distribution says where a realization can be obtained.\",\"expanded\":false,\"id\":\"cuntz-asset\",\"scenario\":\"The Cuntz manifest groups the 4010243_segmented_03b2 FBX source and GLB runtime model under one logical model asset. Their byte sizes, formats and digests differ.\",\"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\":\"The standard contract is separate from the Cuntz dataset content version 0.5.0-rc.2.\",\"href\":\"https://doi.org/10.5281/zenodo.22214248\",\"label\":\"VAO Standard 0.5.0\"}],\"steps\":[{\"text\":\"The asset groups representations serving the named model role. It supplies the connection that a filename alone cannot guarantee.\",\"title\":\"Identify the shared asset\"},{\"text\":\"The FBX source is 61,745,100 bytes; the released GLB is 115,416,448 bytes. The GLB is marked derived, with a model-conversion activity. Each has an independent SHA-256.\",\"title\":\"Inspect each realization\"},{\"text\":\"The smaller model served by this notebook is another derived file. Its caption and file identity distinguish it from both published realizations, and its provenance leads back to the released GLB.\",\"title\":\"Identify the notebook derivative separately\"}],\"takeaway\":\"“Same asset” expresses a relationship; “same bytes” is a separate, testable claim.\",\"title\":\"How can two model files represent one asset?\",\"type\":\"example\",\"visual\":{\"caption\":\"Changing an encoding changes realization identity even when it serves the same logical asset.\",\"layout\":\"flow\",\"nodes\":[{\"detail\":\"Its intellectual role and subject are identified.\",\"icon\":\"cube\",\"label\":\"Logical asset\",\"value\":\"The model as a resource\"},{\"detail\":\"A particular byte sequence and digest.\",\"icon\":\"database\",\"label\":\"Realization\",\"value\":\"One exact GLB\"},{\"detail\":\"A location must resolve to the promised bytes.\",\"icon\":\"external\",\"label\":\"Distribution\",\"value\":\"A way to acquire it\"}],\"relations\":[\"has an exact encoding\",\"is available through\"],\"title\":\"One role can have more than one encoding\"}},{\"id\":\"pack-and-verify\",\"text\":\"3. Pack a carrier, then check what you produced\",\"type\":\"heading\"},{\"label\":\"From the VAO release root · pack into a new output path\",\"text\":\"python Tools/vao05.py pack Fixtures/VAO05/workspaces/minimal learning-output/first.vao\\npython Tools/vao05.py validate learning-output/first.vao\\npython Tools/vao05.py validate-release Fixtures/VAO05/companions/release.example.json Fixtures/VAO05/workspaces/minimal/vao-manifest.json\",\"type\":\"code\"},{\"text\":\"The packed carrier and the supplied release-descriptor check should report VALID. Packing refuses to overwrite an existing output, so use a new filename on a later practice run. To validate the downloaded starter workspace instead, replace Fixtures/VAO05/workspaces/minimal with its local vao-workspace/ path. Keep all source fixture files intact.\",\"type\":\"p\"},{\"type\":\"visual\",\"visual\":{\"caption\":\"The fixture’s identity is deliberately retained for local practice. It is not a new object release to publish.\",\"layout\":\"flow\",\"nodes\":[{\"detail\":\"Manifest, descriptor and payload bindings agree.\",\"icon\":\"database\",\"label\":\"Input\",\"value\":\"A valid workspace\"},{\"detail\":\"Writes the deterministic carrier structure.\",\"icon\":\"layers\",\"label\":\"Operation\",\"value\":\"Reference packer\"},{\"detail\":\"Check the actual archive, not just the input folder.\",\"icon\":\"check\",\"label\":\"Output\",\"value\":\"A validated .vao\"}],\"relations\":[\"pack the identified members\",\"validate the archive\"],\"title\":\"Packing is another checkable transformation\"}},{\"id\":\"adapt-own-object\",\"text\":\"4. Adapt the method to your own research object\",\"type\":\"heading\"},{\"headers\":[\"Replace or review\",\"What to decide before publication\"],\"rows\":[[\"Subject and identifiers\",\"Assign identities for your object, its scoped states and components. Keep the practice fixture identifiers out of your real release.\"],[\"Logical assets and realizations\",\"Describe what each resource is about. Record its actual byte size, SHA-256 and representation status.\"],[\"Evidence and rights\",\"Identify sources, accountable activities, creators, reuse terms and unresolved qualifications.\"],[\"Profiles and groups\",\"Core and Dynamic Delivery are mandatory in 0.5.0. Add only profiles supported by your data and capability claims; follow dependencies.\"],[\"Manifest and carrier pins\",\"Editing or reserializing the manifest changes its exact bytes. Recompute descriptor size and digest bindings for the new release.\"],[\"Release descriptor and repository\",\"Give the new object its own version identity and ensure published carrier and member bindings agree.\"]],\"type\":\"table\"},{\"text\":\"Do not turn a fixture into your publication by changing only its title. Build one coherent record: a logical asset references its realizations; realizations reference the correct asset; groups contain the required realizations; and descriptors pin the exact manifest and embedded members. Use the field-by-field schema reference while editing, and run validation after each small coherent change.\",\"type\":\"p\"},{\"boundary\":\"No acoustics profile or calibrated acoustic response is inferred from the presence of an organ model.\",\"concept\":\"A profile names a set of requirements for a capability. A client’s support describes what an application can do with the object; the two declarations must be compared.\",\"expanded\":false,\"id\":\"cuntz-profiles\",\"scenario\":\"The Cuntz manifest declares Core, Dynamic Delivery, Playable, Physical Instrument, Scientific, Multimodal, Spatial and Zenodo Repository profiles under VAO 0.5.0.\",\"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\":\"The standard contract is separate from the Cuntz dataset content version 0.5.0-rc.2.\",\"href\":\"https://doi.org/10.5281/zenodo.22214248\",\"label\":\"VAO Standard 0.5.0\"}],\"steps\":[{\"text\":\"The object contains information for several uses, including physical topology, scientific observations and sampled interaction. These requirements describe the package contract.\",\"title\":\"Read the object’s declarations\"},{\"text\":\"The notebook loads a GLB display derivative and provides camera controls. It does not import the full VAO manifest, evaluate its scientific records or execute its keyboard and stop behavior.\",\"title\":\"State the viewer’s operation\"},{\"text\":\"To test sampled playback or synchronized controls, choose a client whose documented version supports the relevant format, profiles and resources. Record the tested operation separately from successful visual loading.\",\"title\":\"Choose another client when the task changes\"}],\"takeaway\":\"A working 3D preview proves that the chosen model can be displayed; it does not establish complete VAO conformance or playability.\",\"title\":\"Does showing the organ in 3D mean the VAO is playable?\",\"type\":\"example\",\"visual\":{\"caption\":\"This notebook viewer displays a model. It does not claim to play the Cuntz organ or implement a VAO runtime.\",\"layout\":\"compare\",\"nodes\":[{\"detail\":\"A GLB renderer lets you inspect geometry.\",\"icon\":\"cube\",\"label\":\"Visual inspection\",\"value\":\"Model preview\"},{\"detail\":\"Needs appropriate data, profiles and an implementing client.\",\"icon\":\"wave\",\"label\":\"Playable experience\",\"value\":\"Declared runtime capability\"}],\"title\":\"Displaying geometry and playing sound need different support\"}},{\"id\":\"reuse-next\",\"text\":\"Continue with a small, useful outcome\",\"type\":\"heading\"},{\"items\":[\"For a catalogue or collection: begin with identity, source evidence and a small discovery carrier.\",\"For a recording: include signal identity, acquisition context and the exact master or derivative realization.\",\"For a 3D representation: retain the source, processing lineage, rights and the limits of scale or reconstruction.\",\"For a playable experience: use the declared profiles and a client that implements the required runtime; a visible mesh alone is insufficient.\"],\"type\":\"list\"},{\"items\":[{\"detail\":\"Four illustrated exercises and an optional Three.js package-layer view.\",\"href\":\"/notebooks/vao/package-lab/\",\"label\":\"Practice the package decisions\"},{\"detail\":\"Build a small graph using actual released terms.\",\"href\":\"/notebooks/ontologies/reuse/\",\"label\":\"Model the meanings with MODAVIS\"},{\"detail\":\"A practical checklist, failure recovery and a report template.\",\"href\":\"/notebooks/standards/reuse-checklist/\",\"label\":\"Prepare a reusable release\"}],\"type\":\"links\"}],\"intro\":\"Start with a tiny working example, inspect its exact files, and pack a carrier you can validate. Then use the same method to plan a representation of your own instrument.\",\"slug\":\"reuse\",\"sources\":[{\"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\":\"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\":\"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\"},{\"detail\":\"\",\"href\":\"https://github.com/modavis-project/vao-standard/blob/v0.5.0/Docs/VAO_CONFORMANCE_0.5.0.md\",\"label\":\"VAO 0.5.0 conformance specification\"},{\"detail\":\"\",\"href\":\"https://github.com/modavis-project/vao-standard/blob/v0.5.0/Docs/VAO_SCHEMA_REFERENCE_0.5.0.md\",\"label\":\"VAO 0.5.0 schema reference\"}],\"title\":\"Reuse VAO: your first validated package\"},\"date\":\"2026-10-09\",\"edition\":\"2026-10-learning\",\"figures\":{}}", "payload": { "edition": "2026-10-learning", "date": "2026-10-09", "book": { "slug": "vao", "title": "Virtual Acoustic Objects", "number": "01" }, "chapter": { "slug": "reuse", "title": "Reuse VAO: your first validated package", "intro": "Start with a tiny working example, inspect its exact files, and pack a carrier you can validate. Then use the same method to plan a representation of your own instrument.", "sources": [ { "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": "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": "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." }, { "label": "VAO 0.5.0 conformance specification", "href": "https://github.com/modavis-project/vao-standard/blob/v0.5.0/Docs/VAO_CONFORMANCE_0.5.0.md", "detail": "" }, { "label": "VAO 0.5.0 schema reference", "href": "https://github.com/modavis-project/vao-standard/blob/v0.5.0/Docs/VAO_SCHEMA_REFERENCE_0.5.0.md", "detail": "" } ], "blocks": [ { "type": "note", "title": "What you will leave with", "text": "A validated practice workspace, a deterministic .vao carrier, an understanding of the manifest-to-file bindings, and a plan for adapting the standard to your own subject. Allow about 30–45 minutes for the first run, including environment setup. You need Python 3.11 or newer; no account, database or 3D software is needed." }, { "type": "visual", "visual": { "layout": "flow", "title": "Your first successful reuse loop", "nodes": [ { "label": "Start small", "value": "A known-good fixture", "detail": "Use the versioned release and an isolated working copy.", "icon": "book" }, { "label": "Inspect & validate", "value": "Understand the report", "detail": "Trace a resource to the bytes and check its contract.", "icon": "search" }, { "label": "Adapt deliberately", "value": "Your research object", "detail": "Replace identities, sources and capabilities as a coherent new release.", "icon": "compass" } ], "caption": "A successful practice carrier gives you a working method. Your actual publication still needs its own sources, rights, identifiers and review.", "relations": [ "learn what the fields do", "carry the method forward" ] } }, { "type": "heading", "id": "choose-your-start", "text": "Choose a starting point you can finish" }, { "type": "p", "text": "Begin with one well-documented object and one resource. A museum catalogue note, a measured component, a recording or an attributed model can be a useful first focus. You do not need to build an acoustic simulator before using VAO. The envelope can preserve connections among familiar file formats while your project grows." }, { "type": "visual", "visual": { "layout": "compare", "title": "Choose the contract that solves your problem", "nodes": [ { "label": "Package & delivery", "value": "VAO Standard", "detail": "Describe exact resources and carry them together or selectively.", "icon": "layers" }, { "label": "Meaning & evidence", "value": "Ontology Network", "detail": "Describe what subjects, claims and source relationships mean.", "icon": "network" } ], "caption": "You can learn either part first. VAO defines its own versioned mapping to MODAVIS; the ontology does not import the package format." } }, { "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": "install-release", "text": "1. Open the exact release and prepare the tools" }, { "type": "p", "text": "Download and extract VAO Standard 0.5.0 from its version DOI. Open a terminal in the extracted vao-standard-0.5.0 directory. The following commands create a local Python environment and install the release’s pinned dependencies. Use the source release that contains Docs/, Tools/, Schemas/ and Fixtures/." }, { "type": "links", "items": [ { "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": "Installation and fixture commands", "href": "https://github.com/modavis-project/vao-standard/blob/v0.5.0/README.md", "detail": "The commands here follow this fixed release, rather than a separately versioned client archive." } ] }, { "type": "code", "label": "VAO 0.5.0 release root · environment setup", "text": "python3 -m venv .venv\n. .venv/bin/activate\npython -m pip install --require-hashes -r requirements-lock.txt\npython Tools/vao05.py validate Fixtures/VAO05/workspaces/minimal" }, { "type": "p", "text": "The final command should report VALID. If it does not, keep the diagnostic and confirm the working directory, Python environment and release version before changing the fixture. This establishes a known-good baseline for the tools, not a result about your own instrument." }, { "type": "heading", "id": "inspect-workspace", "text": "2. Inspect the resource-to-file connection" }, { "type": "visual", "visual": { "layout": "flow", "title": "What travels inside a VAO carrier?", "nodes": [ { "label": "Semantic contract", "value": "vao-manifest.json", "detail": "Identified entities, resources, profiles and their relations.", "icon": "network" }, { "label": "Transport contract", "value": "vao-carrier.json", "detail": "Manifest pin and exact embedded member mapping.", "icon": "layers" }, { "label": "Realizations", "value": "payload/…", "detail": "The original formats and exact file bytes stay identifiable.", "icon": "database" } ], "caption": "The root also contains the exact mimetype entry. A carrier is a transport of one semantic release, not a replacement for WAV, GLB, images or research data.", "relations": [ "binds this transport", "maps the embedded members" ] } }, { "type": "p", "text": "Extract the starter kit to a new learning folder. Its vao-workspace/ directory is an unchanged copy of the release’s minimal fixture. The manifest identifies one logical asset, one 69-byte text realization and one complete bootstrap group. The carrier descriptor maps that realization to payload/evidence/source.txt. Inspect the source note itself: it is a teaching resource, not a Cuntz measurement." }, { "type": "code", "label": "From the VAO release root · inspect the supplied fixture", "text": "python - <<'PY'\nimport hashlib, json\nfrom pathlib import Path\nw = Path('Fixtures/VAO05/workspaces/minimal')\nm = json.loads((w / 'vao-manifest.json').read_text())\nc = json.loads((w / 'META-INF/vao-carrier.json').read_text())\nmember = c['embeddedRealizations'][0]\nr = next(item for item in m['realizations'] if item['id'] == member['realizationId'])\nb = (w / member['path']).read_bytes()\nprint('Format:', m['formatVersion'])\nprint('Member:', member['path'])\nprint('Bytes:', len(b), 'expected:', r['byteSize'])\nprint('SHA-256:', hashlib.sha256(b).hexdigest())\nprint('Recorded:', r['contentDigests'][0]['value'])\nPY" }, { "type": "p", "text": "You should see format 0.5.0, the source.txt member, byte length 69, and matching computed and recorded SHA-256 values. Notice how the path is discovered through the descriptor; the name alone is not the realization identity. This inspection script illustrates the binding. The reference validator performs the wider conformance checks." }, { "type": "example", "id": "cuntz-asset", "title": "How can two model files represent one asset?", "concept": "A logical asset names a role in the research object. A realization identifies one exact encoding of that asset. A distribution says where a realization can be obtained.", "scenario": "The Cuntz manifest groups the 4010243_segmented_03b2 FBX source and GLB runtime model under one logical model asset. Their byte sizes, formats and digests differ.", "steps": [ { "title": "Identify the shared asset", "text": "The asset groups representations serving the named model role. It supplies the connection that a filename alone cannot guarantee." }, { "title": "Inspect each realization", "text": "The FBX source is 61,745,100 bytes; the released GLB is 115,416,448 bytes. The GLB is marked derived, with a model-conversion activity. Each has an independent SHA-256." }, { "title": "Identify the notebook derivative separately", "text": "The smaller model served by this notebook is another derived file. Its caption and file identity distinguish it from both published realizations, and its provenance leads back to the released GLB." } ], "takeaway": "“Same asset” expresses a relationship; “same bytes” is a separate, testable claim.", "boundary": "The smaller web derivative has not been retroactively inserted into the published VAO manifest.", "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": "VAO Standard 0.5.0", "href": "https://doi.org/10.5281/zenodo.22214248", "detail": "The standard contract is separate from the Cuntz dataset content version 0.5.0-rc.2." } ], "visual": { "layout": "flow", "title": "One role can have more than one encoding", "nodes": [ { "label": "Logical asset", "value": "The model as a resource", "detail": "Its intellectual role and subject are identified.", "icon": "cube" }, { "label": "Realization", "value": "One exact GLB", "detail": "A particular byte sequence and digest.", "icon": "database" }, { "label": "Distribution", "value": "A way to acquire it", "detail": "A location must resolve to the promised bytes.", "icon": "external" } ], "caption": "Changing an encoding changes realization identity even when it serves the same logical asset.", "relations": [ "has an exact encoding", "is available through" ] }, "expanded": false }, { "type": "heading", "id": "pack-and-verify", "text": "3. Pack a carrier, then check what you produced" }, { "type": "code", "label": "From the VAO release root · pack into a new output path", "text": "python Tools/vao05.py pack Fixtures/VAO05/workspaces/minimal learning-output/first.vao\npython Tools/vao05.py validate learning-output/first.vao\npython Tools/vao05.py validate-release Fixtures/VAO05/companions/release.example.json Fixtures/VAO05/workspaces/minimal/vao-manifest.json" }, { "type": "p", "text": "The packed carrier and the supplied release-descriptor check should report VALID. Packing refuses to overwrite an existing output, so use a new filename on a later practice run. To validate the downloaded starter workspace instead, replace Fixtures/VAO05/workspaces/minimal with its local vao-workspace/ path. Keep all source fixture files intact." }, { "type": "visual", "visual": { "layout": "flow", "title": "Packing is another checkable transformation", "nodes": [ { "label": "Input", "value": "A valid workspace", "detail": "Manifest, descriptor and payload bindings agree.", "icon": "database" }, { "label": "Operation", "value": "Reference packer", "detail": "Writes the deterministic carrier structure.", "icon": "layers" }, { "label": "Output", "value": "A validated .vao", "detail": "Check the actual archive, not just the input folder.", "icon": "check" } ], "caption": "The fixture’s identity is deliberately retained for local practice. It is not a new object release to publish.", "relations": [ "pack the identified members", "validate the archive" ] } }, { "type": "heading", "id": "adapt-own-object", "text": "4. Adapt the method to your own research object" }, { "type": "table", "headers": [ "Replace or review", "What to decide before publication" ], "rows": [ [ "Subject and identifiers", "Assign identities for your object, its scoped states and components. Keep the practice fixture identifiers out of your real release." ], [ "Logical assets and realizations", "Describe what each resource is about. Record its actual byte size, SHA-256 and representation status." ], [ "Evidence and rights", "Identify sources, accountable activities, creators, reuse terms and unresolved qualifications." ], [ "Profiles and groups", "Core and Dynamic Delivery are mandatory in 0.5.0. Add only profiles supported by your data and capability claims; follow dependencies." ], [ "Manifest and carrier pins", "Editing or reserializing the manifest changes its exact bytes. Recompute descriptor size and digest bindings for the new release." ], [ "Release descriptor and repository", "Give the new object its own version identity and ensure published carrier and member bindings agree." ] ] }, { "type": "p", "text": "Do not turn a fixture into your publication by changing only its title. Build one coherent record: a logical asset references its realizations; realizations reference the correct asset; groups contain the required realizations; and descriptors pin the exact manifest and embedded members. Use the field-by-field schema reference while editing, and run validation after each small coherent change." }, { "type": "example", "id": "cuntz-profiles", "title": "Does showing the organ in 3D mean the VAO is playable?", "concept": "A profile names a set of requirements for a capability. A client’s support describes what an application can do with the object; the two declarations must be compared.", "scenario": "The Cuntz manifest declares Core, Dynamic Delivery, Playable, Physical Instrument, Scientific, Multimodal, Spatial and Zenodo Repository profiles under VAO 0.5.0.", "steps": [ { "title": "Read the object’s declarations", "text": "The object contains information for several uses, including physical topology, scientific observations and sampled interaction. These requirements describe the package contract." }, { "title": "State the viewer’s operation", "text": "The notebook loads a GLB display derivative and provides camera controls. It does not import the full VAO manifest, evaluate its scientific records or execute its keyboard and stop behavior." }, { "title": "Choose another client when the task changes", "text": "To test sampled playback or synchronized controls, choose a client whose documented version supports the relevant format, profiles and resources. Record the tested operation separately from successful visual loading." } ], "takeaway": "A working 3D preview proves that the chosen model can be displayed; it does not establish complete VAO conformance or playability.", "boundary": "No acoustics profile or calibrated acoustic response is inferred from the presence of an organ model.", "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": "VAO Standard 0.5.0", "href": "https://doi.org/10.5281/zenodo.22214248", "detail": "The standard contract is separate from the Cuntz dataset content version 0.5.0-rc.2." } ], "visual": { "layout": "compare", "title": "Displaying geometry and playing sound need different support", "nodes": [ { "label": "Visual inspection", "value": "Model preview", "detail": "A GLB renderer lets you inspect geometry.", "icon": "cube" }, { "label": "Playable experience", "value": "Declared runtime capability", "detail": "Needs appropriate data, profiles and an implementing client.", "icon": "wave" } ], "caption": "This notebook viewer displays a model. It does not claim to play the Cuntz organ or implement a VAO runtime." }, "expanded": false }, { "type": "heading", "id": "reuse-next", "text": "Continue with a small, useful outcome" }, { "type": "list", "items": [ "For a catalogue or collection: begin with identity, source evidence and a small discovery carrier.", "For a recording: include signal identity, acquisition context and the exact master or derivative realization.", "For a 3D representation: retain the source, processing lineage, rights and the limits of scale or reconstruction.", "For a playable experience: use the declared profiles and a client that implements the required runtime; a visible mesh alone is insufficient." ] }, { "type": "links", "items": [ { "label": "Practice the package decisions", "href": "/notebooks/vao/package-lab/", "detail": "Four illustrated exercises and an optional Three.js package-layer view." }, { "label": "Model the meanings with MODAVIS", "href": "/notebooks/ontologies/reuse/", "detail": "Build a small graph using actual released terms." }, { "label": "Prepare a reusable release", "href": "/notebooks/standards/reuse-checklist/", "detail": "A practical checklist, failure recovery and a report template." } ] } ] }, "figures": {} } }