On this page
- Start smallA known-good fixtureUse the versioned release and an isolated working copy.learn what the fields do
- Inspect & validateUnderstand the reportTrace a resource to the bytes and check its contract.carry the method forward
- Adapt deliberatelyYour research objectReplace identities, sources and capabilities as a coherent new release.
Choose a starting point you can finish
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.
- Package & deliveryVAO StandardDescribe exact resources and carry them together or selectively.
- Meaning & evidenceOntology NetworkDescribe what subjects, claims and source relationships mean.
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.
1. Open the exact release and prepare the tools
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/.
Technical detail · VAO 0.5.0 release root · environment setup
python3 -m venv .venv
. .venv/bin/activate
python -m pip install --require-hashes -r requirements-lock.txt
python Tools/vao05.py validate Fixtures/VAO05/workspaces/minimalThe 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.
2. Inspect the resource-to-file connection
- Semantic contractvao-manifest.jsonIdentified entities, resources, profiles and their relations.binds this transport
- Transport contractvao-carrier.jsonManifest pin and exact embedded member mapping.maps the embedded members
- Realizationspayload/…The original formats and exact file bytes stay identifiable.
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.
Technical detail · From the VAO release root · inspect the supplied fixture
python - <<'PY'
import hashlib, json
from pathlib import Path
w = Path('Fixtures/VAO05/workspaces/minimal')
m = json.loads((w / 'vao-manifest.json').read_text())
c = json.loads((w / 'META-INF/vao-carrier.json').read_text())
member = c['embeddedRealizations'][0]
r = next(item for item in m['realizations'] if item['id'] == member['realizationId'])
b = (w / member['path']).read_bytes()
print('Format:', m['formatVersion'])
print('Member:', member['path'])
print('Bytes:', len(b), 'expected:', r['byteSize'])
print('SHA-256:', hashlib.sha256(b).hexdigest())
print('Recorded:', r['contentDigests'][0]['value'])
PYYou 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.
How can two model files represent one asset?
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.
- Logical assetThe model as a resourceIts intellectual role and subject are identified.has an exact encoding
- RealizationOne exact GLBA particular byte sequence and digest.is available through
- DistributionA way to acquire itA location must resolve to the promised bytes.
Work through the example 3 STEPS
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.
Identify the shared asset
The asset groups representations serving the named model role. It supplies the connection that a filename alone cannot guarantee.
Inspect each realization
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.
Identify the notebook derivative separately
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.
- Cuntz Positiv · VAO 0.5.0-rc.2 ↗
Published manifest: identities, measurement observations, realization digests, profiles and rights. Exact examples checked against this release.
- VAO Standard 0.5.0 ↗
The standard contract is separate from the Cuntz dataset content version 0.5.0-rc.2.
The smaller web derivative has not been retroactively inserted into the published VAO manifest.
The useful distinction. “Same asset” expresses a relationship; “same bytes” is a separate, testable claim.
3. Pack a carrier, then check what you produced
Technical detail · From the VAO release root · pack into a new output path
python Tools/vao05.py pack Fixtures/VAO05/workspaces/minimal learning-output/first.vao
python Tools/vao05.py validate learning-output/first.vao
python Tools/vao05.py validate-release Fixtures/VAO05/companions/release.example.json Fixtures/VAO05/workspaces/minimal/vao-manifest.jsonThe 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.
- InputA valid workspaceManifest, descriptor and payload bindings agree.pack the identified members
- OperationReference packerWrites the deterministic carrier structure.validate the archive
- OutputA validated .vaoCheck the actual archive, not just the input folder.
4. Adapt the method to your own research object
| Replace or review | What to decide before publication |
|---|---|
| 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. |
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.
Does showing the organ in 3D mean the VAO is playable?
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.
- Visual inspectionModel previewA GLB renderer lets you inspect geometry.
- Playable experienceDeclared runtime capabilityNeeds appropriate data, profiles and an implementing client.
Work through the example 3 STEPS
The Cuntz manifest declares Core, Dynamic Delivery, Playable, Physical Instrument, Scientific, Multimodal, Spatial and Zenodo Repository profiles under VAO 0.5.0.
Read the object’s declarations
The object contains information for several uses, including physical topology, scientific observations and sampled interaction. These requirements describe the package contract.
State the viewer’s operation
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.
Choose another client when the task changes
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.
- Cuntz Positiv · VAO 0.5.0-rc.2 ↗
Published manifest: identities, measurement observations, realization digests, profiles and rights. Exact examples checked against this release.
- VAO Standard 0.5.0 ↗
The standard contract is separate from the Cuntz dataset content version 0.5.0-rc.2.
No acoustics profile or calibrated acoustic response is inferred from the presence of an organ model.
The useful distinction. A working 3D preview proves that the chosen model can be displayed; it does not establish complete VAO conformance or playability.
Continue with a small, useful outcome
- 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.