Models and validation
Change models at their maintained source and select the right validation evidence.
Repository review: . Public operational reference; acceptance remains to be recorded by the receiving owner.
Change models at their maintained source
Schema-derived ontology
Read the relevant ODR, generator input definitions and Makefile before changing the committed Turtle corpus. tools/opda-gen/README.md retains a historical “Phase 2 — Substrate” status and stub descriptions; use it for background, and check the current commands and implementation under tools/opda-gen/src/opda_gen/ for supported behaviour. Keep derivation, provenance, documentary annotations and permitted inference behaviour intact. Fix the generator or maintained inputs, regenerate and compare the output; editing only a generated reference page creates drift.
make ontology-test
make ci-ontology
make build-data
make ci-ontology-doc
make ci-ontology-graph make ci-ontology covers unit/round-trip, profile, declaration, construct, coverage and provenance contracts, then proves regeneration byte identity. make build-data starts Fuseki, clears and reloads the local dataset, refreshes the committed model and graph, builds the site and stops its owned service. Stop any owned make serve-data session first; these commands must not compete for the same port or data directory. Review changes to src/data/ontology-model.json and public/data/ontology-graph-elements.json alongside the model inputs. Use make ci-ontology-model with a running local Fuseki when checking that extraction independently.
make jena-load clears and reloads the selected local dataset. Confirm the target before using it. make api and make ontology-model expect a running local Fuseki; they do not administer production.
Property Pack candidate
The maintained catalogue and contextual rules live under src/data/property-pack/. Catalogue fragments in properties/ generate required-properties.json and validation-report.json. The separate candidate-model/ definitions consume that JSON through the catalogue_path and catalogue_sha256 pin in candidate-model/manifest.toml. Candidate generation does not regenerate the catalogue. Preserve the accepted 451-item evidence scope and item-to-model traceability; a count comparison alone does not establish semantic equivalence.
Complete the Python/Jena setup first. Before regenerating a curated catalogue change, obtain both source/04-governance-bodies/working-groups/regulator/PDTF base schema.xlsx and source/03-standards/schemas/src/schemas/v3/pdtf-transaction.json, matching the evidence hashes in src/data/property-pack/catalogue.toml. A clone alone does not supply both. The check command can use a frozen reconciliation receipt when both sources are absent; that is not a fresh source comparison.
# After an intentional catalogue TOML change, with matching source evidence
pnpm run property-pack:generate
pnpm run property-pack:check Review the catalogue JSON and validation-report diff. If the intended catalogue change alters the JSON hash, review and deliberately update catalogue_sha256 in the candidate manifest to bind the candidate to that exact input. Do not update source-evidence hashes or the candidate pin merely to silence a mismatch. Record any authorised source-version or scope decision before continuing.
# After a reviewed catalogue/pin change or candidate-model-only change
make property-pack-candidate
# Non-publishing validation and deterministic regeneration
pnpm run property-pack:check
make ci-property-pack-candidate
make test-model
make test
make build The candidate gates validate RDF, SHACL, SPARQL, coverage and byte identity. They do not sign off the model. Use the Property Pack workspace and review and release record to keep open questions, reviewer dispositions and the exact candidate version linked to the eventual determination. Any unresolved required-field counting or source-version discrepancy needs an explicit crosswalk and decision.
Semantic review
Keep six outputs aligned: business glossary, data dictionary, taxonomies, controlled vocabularies, resources and relationships. Record a resource's contextual home, source version, rights, definition, examples, counterexamples and competency questions. Domain practitioners own domain meaning; interoperability work owns the limited shared boundary and qualified mappings. Proposals, objections, validations and human decisions must remain distinguishable.
Choose and preserve the right validation evidence
There is no lint script. The Makefile is the task entry point. Always run make test after code changes and make build for website changes; use make build-data when ontology inputs change. Add the affected model, operational or interface checks rather than treating every change as equivalent.
| Change | Additional evidence |
|---|---|
| Ordinary content or route | Inspect status/provenance and internal links, validate the changed built route and verify the page with the approved Chrome connection. |
| Shared interface | Focused consumer contracts, make check-design-system, accessible light/dark and narrow-viewport review. Use the shared component and update its consumers. |
| ADR | Read the status enum and format in docs/adr/README.md; run make gen-adr and make check-adr. Check publication eligibility before building. |
| Schema or ontology | make ci-ontology, relevant schema reproducibility gates, model/document/graph drift checks and regenerated-output review. |
| Property Pack | pnpm run property-pack:check, make ci-property-pack-candidate, make test-model and human review of the catalogue pin, affected definitions and traceability. |
| AWS or participant services | Focused boundary tests, infrastructure workflow validation and an authorised live acceptance check that avoids unintended participant effects. |
| Marketing or NotebookLM | make marketing-check or the local notebook receipt verifier, then human content/authority/rights review. |
The release workflow classifies changed paths into editorial, application, ontology, infrastructure and tooling lanes. Common checks include design/ADR drift, governed test ownership and stable release contracts. Application changes add focused behaviour checks; ontology changes provision the model toolchain and upstream pinned schema. Changed-route checks and critical browser journeys run against the built candidate before publication.
Broader whole-site, accessibility, responsive and visual assurance is scheduled separately; external-link checks run weekly. Scheduled assurance does not deploy. make ci remains a comprehensive local path. Repository browser commands describe CI's Playwright suite; local browser interaction must follow AGENTS.md and use the authorised existing Chrome session. If that connection is unavailable, report the exact missing browser evidence rather than claiming a visual pass.
Keep validation outputs with the relevant commit or release record. Passing syntax, machine validation or AI review does not prove source rights, standards approval, operational activation or transfer of ownership.