content-model: media-library - Finalise the asset catalogue schema #289

Content Modelling Summary

Design and implement the final asset catalogue schema based on audit findings and pilot validation.

Current status — 19 October 2026

Backlog; assigned to Ash. Schema, model, catalogue and validation tooling exist, but a consistent approved contract validated against recovered samples is not established.

Envelope/field naming differs between schema and catalogue, and the referenced metadata-rules contract is absent.

Models / Taxonomies

The audit produced a sample catalogue schema (SAMPLE-CATALOGUE.json) with full metadata structure. Finalise the schema using recovered-asset validation and reconciled inventory coverage—not an assumed fixed asset count.

Acceptance Criteria

• Reconcile sample fields with the initial model and pilot findings.
• Deliver consistent catalogue JSON, TypeScript interface and examples.
• Define required, optional and unknown-value rules; validate representative recovered assets and reconciled coverage.
• Record storage, versioning and maintenance decisions.
• Obtain project-owner approval.

Dependencies

• Blocked by: bug: assets - Restore original Figma artwork #7 (asset validation results)
• Blocks: design: media-library - Design the import and reference-migration workflow #281 (migration script needs finalized schema)

Deliverables

• Final catalogue schema JSON (TypeScript interface + example)
• Validation rules documentation
• Catalogue maintenance guide
• Storage location decision (with rationale)

References

• Sample Catalogue: .github/reports/toa-media-library/SAMPLE-CATALOGUE.json
• Strategy Report § 4: .github/reports/toa-media-library/MEDIA-LIBRARY-STRATEGY-REPORT.md

Definition of Ready (DoR)

• Intended deliverables and approval requirement are documented.
• Initial model, validation findings, coverage, assignee and reviewer are confirmed.

Definition of Done (DoD)

• Schema, interface, examples and evidence agree without fabricated metadata.
• Approved schema is handed to implementation; applicable repository requirements are met.

Immediate next steps

Agree the canonical envelope, naming, required/optional/unknown-value rules and validation boundary. Reconcile schema, catalogue, interface, validator and examples; address the missing contract.

Evidence required

Consistent schema/interface/examples, executed recovered-sample validation, exception handling and project-owner approval. Existing files alone do not establish acceptance.

Specification references

• Specification
• Plan
• Tasks

Draft specification/planning references at revision 02aee367; not evidence of approval, completed recovery or implementation. Task correspondences below describe relevant scope, not exclusive ownership or completed work.

Relevant requirements: US2, FR-006–009. T016–T025 and T044 support schema definition and consistency checks, overlapping initial modelling. TypeScript interface, storage/versioning decisions and owner approval are not fully covered.

Branch instructions

• Repository: lightspeedwp/ThisOneTimeOnAcidCom.
• Implementing target: this final-catalogue-contract issue. The bounded first contribution below settles the contract and maintenance decisions; TypeScript interfaces, executable validation, consumer compatibility and recovered-sample acceptance remain later gated work.
• Parent context: retain existing coordination hierarchy. Do not include parent identifiers or links in branches, PRs or coding prompts while association effects remain unverified. Never use the parent as a native development or closing target.
• Allowed closing targets: none for this partial contribution. Contract documentation alone does not satisfy the issue’s whole outcome.
• Branch state: proposed new branch, not created. No matching branch found in the refreshed 38-branch listing; repeat collision and related-PR checks before implementation.
• Proposed branch: schema/media-library-catalogue-contract.
• Base: develop, checked at 4ecdb26d9655a48bf000a7c89da2f70383edce87.
• Naming evidence: local guide, local validator and organisation strategy. schema/ is authorised for contract work; the Linear classification does not prescribe a branch prefix. Naming inspected, not executed.
• Existing work: PR296 merged mixed testing/audit work; its surviving fix/toa-media-library-coderabbit-findings branch is not verified as an active, issue-specific contract implementation. No automatic reuse, rename, reset, cherry-pick or force-push.
• PR template: shared route map maps schema/ to the feature template. The local router lacks a schema route and falls back to default/type:task. Obtain maintainer disposition before PR creation; automatic loading is unverified. Do not change routes, templates or labels as a workaround. PR title/body and any issue associations require separate review; no closing syntax authorised.
• Constraints: description planning only. No branch, PR, repository, execution, extraction, upload, asset replacement, merge or deployment actions authorised.

Expected file changes

Provisional contract-first subset, not permission to implement or a complete plan for the whole issue. D = 4ecdb26d9655a48bf000a7c89da2f70383edce87. These existing paths were inspected at D; existence does not approve edits.

No moves or deletions. Do not migrate catalogue records or change consumers in this first subset. Any executable interface, validator, test, dependency or catalogue migration work requires a subsequent bounded compatibility plan before implementation; do not declare the changed contract operationally adopted until that work is verified.

Decisions before implementation

• Formal schema requires catalogueVersion and snake_case fields; current catalogues use catalogueMetadata, catalogueId and nested camelCase. Agree a canonical contract and reversible mapping; preserve stable identifier values.
• Existing readers/updaters and extraction manifests use camelCase. Document the compatibility boundary; do not silently convert data while leaving consumers incompatible.
• Recovery states differ between schema and consumers. Agree evidence-based mappings; pending is not automatically not_attempted, failed is not automatically unrecoverable, and fallback is not recovery of an original.
• Reconcile nullability, dimension units and required relationship targets. Proposed example correction: add "target_type": "asset" to the original-to-derivative example, then validate examples after separate execution approval.
• Unknown dimensions, rights, attribution, original/derivative status and print readiness must remain explicitly unverified. Recommended PPI or valid JSON does not prove suitability or licensing.
• Existing illustrative/selection records are not recovered samples. Reconcile inventory coverage and retain recovered-sample validation and project-owner approval as outstanding acceptance gates. Counts were not independently recounted during this audit.
• Agree storage/versioning, reviewer and validation engine. Zod is declared but no direct JSON Schema validator dependency was found; do not rely on a transitive dependency or add packages without a revised plan.

Serialise shared schema/model work with initial modelling and validation-design contributions. Do not change Spec 002 task markers, quickstart or checklist as incidental cleanup. Historical completion/print/count claims require separate reconciliation, not assumed acceptance.

Preserve images, figma asset references, protected fallback component, Supabase utilities, attribution, changelog, task-list, deployment/environment files and managed workflows. Locked governance/templates/taxonomy remain human-controlled. Changelog disposition requires a maintainer decision; no exemption label is added automatically.

No tests, builds, validators, recovery or other commands were run. This plan grants no implementation authority. Stop for revised scope and approval before adding paths, executable changes, migration, dependencies or broader cleanup.