{ "title": "Working with the standard — Virtual Acoustic Objects", "text": "MODAVIS (2026). Working with the standard — Virtual Acoustic Objects. Research notebooks, September 2026 · Connected evidence edition. https://modavis.org/editions/2026-09-r6/vao/implementation/", "bibtex": "@misc{modavis_vao_implementation_2026_09_r6,\n author = {{MODAVIS}},\n title = {Working with the standard — Virtual Acoustic Objects},\n year = {2026},\n month = {09},\n version = {2026-09-r6},\n url = {https://modavis.org/editions/2026-09-r6/vao/implementation/},\n note = {Content SHA-256: 58547fe5aaaabd22cb04decc6352e6a7de84f08add4ad1c3446a5833a563a725}\n}", "url": "https://modavis.org/editions/2026-09-r6/vao/implementation/", "sha256": "58547fe5aaaabd22cb04decc6352e6a7de84f08add4ad1c3446a5833a563a725", "edition": "2026-09-r6", "date": "2026-09-26", "canonicalPayload": "{\"book\":{\"number\":\"01\",\"slug\":\"vao\",\"title\":\"Virtual Acoustic Objects\"},\"chapter\":{\"blocks\":[{\"items\":[{\"detail\":\"A continuous worked example: readable explanations, exact records and the limits of each claim.\",\"href\":\"/notebooks/standards/cuntz/\",\"label\":\"Learn this through the Cuntz organ\"}],\"type\":\"links\"},{\"items\":[\"Read the final 0.5.0 specification and the profiles relevant to your object.\",\"Keep original measurements and source evidence separate from derived representations.\",\"Record rights for each resource; a package does not erase third-party restrictions.\",\"Validate the workspace and release bindings before packing a carrier.\",\"Verify the carrier and publish it with its version identifier and checksums.\"],\"type\":\"list\"},{\"id\":\"validation\",\"text\":\"Reference validation\",\"type\":\"heading\"},{\"label\":\"From the VAO 0.5.0 source checkout\",\"text\":\"python Tools/vao05.py validate path/to/workspace\\npython Tools/vao05.py pack path/to/workspace output.vao\",\"type\":\"code\"},{\"text\":\"The release includes schemas, conformance fixtures, reference tools and migration guidance. Use the environment and installation instructions distributed with that release rather than assuming that an unrelated tool version implements the same contract.\",\"type\":\"p\"},{\"text\":\"Conformance checks structure, semantics, declared profiles and file integrity. It does not certify the scientific truth of a measurement, attribution or interpretation.\",\"title\":\"What validation establishes\",\"type\":\"note\"},{\"id\":\"implementation-decisions\",\"text\":\"Decide the contract before building the viewer\",\"type\":\"heading\"},{\"headers\":[\"Decision\",\"Why it matters\"],\"rows\":[[\"Object and historical state\",\"Determines which subjects the resources and claims refer to.\"],[\"Profiles and required capabilities\",\"Determines the responsibilities a conforming implementation must satisfy.\"],[\"Exact realizations and provenance\",\"Distinguishes captured material from conversions, derivations and simulations.\"],[\"Delivery and dependencies\",\"Determines which groups must be present before an experience can run.\"]],\"type\":\"table\"},{\"text\":\"For final VAO 0.5.0, Core and Dynamic Delivery are mandatory. Additional profiles express further requirements; they are not decorative labels. An implementation that can display metadata but cannot satisfy a required playback capability should report that limitation. It may still provide useful lower-level inspection without claiming full support for the playable profile.\",\"type\":\"p\"},{\"id\":\"validation-levels\",\"text\":\"Validate at more than one level\",\"type\":\"heading\"},{\"text\":\"Start with a workspace whose manifest and resource paths can be inspected locally. Check the manifest’s references and declared profiles, then verify the exact payload realizations. After packaging, check the carrier mapping and release bindings as well. A structurally valid manifest does not establish that a published carrier contains the bytes it promises.\",\"type\":\"p\"},{\"text\":\"Keep a small fixture with a known result for each capability you implement. Include an unsupported-profile case and an intentionally altered payload: these should produce clear limitations or validation failures, not silent substitution. Record the validator version with the result. This is practical implementation guidance; the versioned conformance specification remains the authority for required tests.\",\"type\":\"p\"},{\"text\":\"The VAO CLI, Unity importer, Blender extension and OrgRec have independent release histories. Consult the client comparison before assuming that an archived client accepts every final 0.5 package.\",\"title\":\"Choose a client by its supported contract\",\"type\":\"note\"},{\"items\":[{\"href\":\"/notebooks/software/clients/\",\"label\":\"Compare the VAO implementations\"}],\"type\":\"links\"},{\"items\":[{\"detail\":\"The versioned specification and reference tools.\",\"href\":\"https://doi.org/10.5281/zenodo.22214248\",\"label\":\"VAO Standard 0.5.0\"},{\"href\":\"https://w3id.org/modavis/vao/0.5.0/\",\"label\":\"VAO persistent entry point\"}],\"type\":\"links\"},{\"boundary\":\"The notebook’s JSON teaching excerpt is deliberately incomplete and is not presented as a complete, independently conforming VAO package.\",\"caseLabel\":\"Cuntz\",\"concept\":\"Conformance means meeting a specified contract. Different checks address parsing, structure, relationships, required capabilities and file identity.\",\"evidence\":\"Illustrative scenario\",\"expanded\":false,\"id\":\"cuntz-conformance\",\"scenario\":\"Take the published observation with value 1281 millimetres. A reader wants to know both whether its record is valid and whether the measurement answers a question about the pipe.\",\"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\":\"A schema can check that the result has the required form and that a numerical field contains a number. Semantic checks can verify that references point to appropriate records.\",\"title\":\"Check the structure\"},{\"text\":\"Resolve the pipe, measurement activity and workbook realization; verify the cited source bytes. These operations establish what the record says and which source it identifies.\",\"title\":\"Check the evidence links\"},{\"text\":\"The workbook timestamp still is not the measurement-session date. A valid record without a documented calibration uncertainty cannot support an uncertainty claim simply because its schema passed.\",\"title\":\"Assess fitness for the question\"}],\"takeaway\":\"Validation and scientific assessment complement one another; each needs an explicitly stated scope.\",\"title\":\"How can a file pass validation but support a limited conclusion?\",\"type\":\"example\"},{\"id\":\"implementation-sequence\",\"text\":\"A practical implementation sequence\",\"type\":\"heading\"},{\"items\":[\"Start from a pinned standard release and its minimal fixture. Confirm strict parsing and schema validation before adding capabilities.\",\"Add typed references and semantic checks, then implement the profiles needed by your use case. Keep unimplemented checks visible.\",\"Verify carrier descriptors and realization bytes before materializing resources. Preserve failure diagnostics and acquisition receipts.\",\"Test the claimed operation in the intended client. Metadata inspection, geometry import and runtime execution need different evidence.\"],\"type\":\"list\"},{\"items\":[{\"detail\":\"Reference commands and the meaning of each validation layer.\",\"href\":\"/notebooks/standards/conformance/\",\"label\":\"Layered validation guide\"},{\"detail\":\"Match standard version, application release and operation.\",\"href\":\"/notebooks/software/clients/\",\"label\":\"Client comparison\"}],\"type\":\"links\"}],\"intro\":\"Start with a pinned release, declare the capabilities you provide, and preserve exact file identities.\",\"slug\":\"implementation\",\"sources\":[{\"detail\":\"The versioned specification and reference tools.\",\"href\":\"https://doi.org/10.5281/zenodo.22214248\",\"label\":\"VAO Standard 0.5.0\"},{\"detail\":\"Normative standard, profile index, Dynamic Delivery Profile and conformance specification in the versioned release.\",\"href\":\"https://doi.org/10.5281/zenodo.22214248\",\"label\":\"VAO Standard 0.5.0\"}],\"title\":\"Working with the standard\"},\"date\":\"2026-09-26\",\"edition\":\"2026-09-r6\",\"figures\":{}}", "payload": { "edition": "2026-09-r6", "date": "2026-09-26", "book": { "slug": "vao", "title": "Virtual Acoustic Objects", "number": "01" }, "chapter": { "slug": "implementation", "title": "Working with the standard", "intro": "Start with a pinned release, declare the capabilities you provide, and preserve exact file identities.", "blocks": [ { "type": "links", "items": [ { "label": "Learn this through the Cuntz organ", "href": "/notebooks/standards/cuntz/", "detail": "A continuous worked example: readable explanations, exact records and the limits of each claim." } ] }, { "type": "list", "items": [ "Read the final 0.5.0 specification and the profiles relevant to your object.", "Keep original measurements and source evidence separate from derived representations.", "Record rights for each resource; a package does not erase third-party restrictions.", "Validate the workspace and release bindings before packing a carrier.", "Verify the carrier and publish it with its version identifier and checksums." ] }, { "type": "heading", "text": "Reference validation", "id": "validation" }, { "type": "code", "label": "From the VAO 0.5.0 source checkout", "text": "python Tools/vao05.py validate path/to/workspace\npython Tools/vao05.py pack path/to/workspace output.vao" }, { "type": "p", "text": "The release includes schemas, conformance fixtures, reference tools and migration guidance. Use the environment and installation instructions distributed with that release rather than assuming that an unrelated tool version implements the same contract." }, { "type": "note", "title": "What validation establishes", "text": "Conformance checks structure, semantics, declared profiles and file integrity. It does not certify the scientific truth of a measurement, attribution or interpretation." }, { "type": "heading", "text": "Decide the contract before building the viewer", "id": "implementation-decisions" }, { "type": "table", "headers": [ "Decision", "Why it matters" ], "rows": [ [ "Object and historical state", "Determines which subjects the resources and claims refer to." ], [ "Profiles and required capabilities", "Determines the responsibilities a conforming implementation must satisfy." ], [ "Exact realizations and provenance", "Distinguishes captured material from conversions, derivations and simulations." ], [ "Delivery and dependencies", "Determines which groups must be present before an experience can run." ] ] }, { "type": "p", "text": "For final VAO 0.5.0, Core and Dynamic Delivery are mandatory. Additional profiles express further requirements; they are not decorative labels. An implementation that can display metadata but cannot satisfy a required playback capability should report that limitation. It may still provide useful lower-level inspection without claiming full support for the playable profile." }, { "type": "heading", "text": "Validate at more than one level", "id": "validation-levels" }, { "type": "p", "text": "Start with a workspace whose manifest and resource paths can be inspected locally. Check the manifest’s references and declared profiles, then verify the exact payload realizations. After packaging, check the carrier mapping and release bindings as well. A structurally valid manifest does not establish that a published carrier contains the bytes it promises." }, { "type": "p", "text": "Keep a small fixture with a known result for each capability you implement. Include an unsupported-profile case and an intentionally altered payload: these should produce clear limitations or validation failures, not silent substitution. Record the validator version with the result. This is practical implementation guidance; the versioned conformance specification remains the authority for required tests." }, { "type": "note", "title": "Choose a client by its supported contract", "text": "The VAO CLI, Unity importer, Blender extension and OrgRec have independent release histories. Consult the client comparison before assuming that an archived client accepts every final 0.5 package." }, { "type": "links", "items": [ { "label": "Compare the VAO implementations", "href": "/notebooks/software/clients/" } ] }, { "type": "links", "items": [ { "label": "VAO Standard 0.5.0", "href": "https://doi.org/10.5281/zenodo.22214248", "detail": "The versioned specification and reference tools." }, { "label": "VAO persistent entry point", "href": "https://w3id.org/modavis/vao/0.5.0/" } ] }, { "type": "example", "id": "cuntz-conformance", "title": "How can a file pass validation but support a limited conclusion?", "concept": "Conformance means meeting a specified contract. Different checks address parsing, structure, relationships, required capabilities and file identity.", "scenario": "Take the published observation with value 1281 millimetres. A reader wants to know both whether its record is valid and whether the measurement answers a question about the pipe.", "steps": [ { "title": "Check the structure", "text": "A schema can check that the result has the required form and that a numerical field contains a number. Semantic checks can verify that references point to appropriate records." }, { "title": "Check the evidence links", "text": "Resolve the pipe, measurement activity and workbook realization; verify the cited source bytes. These operations establish what the record says and which source it identifies." }, { "title": "Assess fitness for the question", "text": "The workbook timestamp still is not the measurement-session date. A valid record without a documented calibration uncertainty cannot support an uncertainty claim simply because its schema passed." } ], "takeaway": "Validation and scientific assessment complement one another; each needs an explicitly stated scope.", "boundary": "The notebook’s JSON teaching excerpt is deliberately incomplete and is not presented as a complete, independently conforming VAO package.", "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." } ], "expanded": false, "caseLabel": "Cuntz", "evidence": "Illustrative scenario" }, { "type": "heading", "id": "implementation-sequence", "text": "A practical implementation sequence" }, { "type": "list", "items": [ "Start from a pinned standard release and its minimal fixture. Confirm strict parsing and schema validation before adding capabilities.", "Add typed references and semantic checks, then implement the profiles needed by your use case. Keep unimplemented checks visible.", "Verify carrier descriptors and realization bytes before materializing resources. Preserve failure diagnostics and acquisition receipts.", "Test the claimed operation in the intended client. Metadata inspection, geometry import and runtime execution need different evidence." ] }, { "type": "links", "items": [ { "label": "Layered validation guide", "href": "/notebooks/standards/conformance/", "detail": "Reference commands and the meaning of each validation layer." }, { "label": "Client comparison", "href": "/notebooks/software/clients/", "detail": "Match standard version, application release and operation." } ] } ], "sources": [ { "label": "VAO Standard 0.5.0", "href": "https://doi.org/10.5281/zenodo.22214248", "detail": "The versioned specification and reference tools." }, { "label": "VAO Standard 0.5.0", "href": "https://doi.org/10.5281/zenodo.22214248", "detail": "Normative standard, profile index, Dynamic Delivery Profile and conformance specification in the versioned release." } ] }, "figures": {} } }