content-model: media-library - Define the asset catalogue and provenance model #279

Content Modelling Summary

Define the asset catalogue for the TOA media library, informed by recovered Figma assets.

Current status — 19 October 2026

In Progress. A data model, schema draft and 56-record catalogue exist. Recovery remains pending with zero dimensions; photographer, rights and print-ready assertions are unverified.

The formal schema’s snake_case fields and catalogueVersion/assets envelope disagree with the catalogue’s camelCase fields and catalogueMetadata envelope.

Linked Stories/Tasks/PRs/Epic

Parent: #267. Asset recovery remains in #7. No implementation PR specified.

Milestones & Timeline

Not set. Use recovered Figma assets to inform the model.

Models / Taxonomies

Specify stable asset IDs and source/reference mappings. Define filenames, dimensions, format, page/component or chapter usage, captions and alt text. Distinguish originals from rendered derivatives.

Use Cases

Support asset provenance and usage across the TOA website and book publishing workflows.

Acceptance Criteria

• Define stable IDs, Figma sources and website-reference mappings.
• Define filenames, dimensions, formats, website/chapter usage, captions and alt text.
• Model originals, derivatives, verified rights/credits and explicit unknowns.
• Record reversible assumptions and hand recovered-asset refinements to schema finalisation; initial modelling need not await recovery.

Additional Context

No reviewer specified. This issue defines the catalogue model, not asset recovery or migration execution.

Definition of Ready (DoR)

• Initial modelling purpose and recovery relationship are documented.
• Recovery evidence, reviewer and finalisation boundary are agreed.

Definition of Done (DoD)

• Reviewed model and examples satisfy the criteria; gaps are handed to schema finalisation.
• Applicable repository requirements are met without implying recovery or migration completion.

Immediate next steps

Agree the field dictionary, stable identity, provenance, original/derivative relationships and explicit unknown-value rules. Record the contract choices for schema finalisation.

Evidence required

Reviewed field definitions, source-traceable examples, envelope/naming decisions and explicit unknowns. Initial modelling is distinct from final validation against recovered assets.

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: US1–US2, FR-006–009. T011–T018, T020–T023 and T025 support model, schema and provenance definition. Their boundary with final schema validation requires agreement.

Branch instructions

• Repository: lightspeedwp/ThisOneTimeOnAcidCom.
• Implementing target: this issue’s initial asset catalogue and provenance model, not final schema implementation; counterpart GitHub issue 279.
• Parent context: existing media-library coordination parent only. Retain hierarchy. Do not copy parent identifiers/URLs into branch names, PR titles/bodies or implementation prompts while association effects remain unverified. Never use the parent as a native development or closing target.
• Allowed closing targets: none authorised. A future association requires reviewed evidence that this issue’s entire modelling outcome is satisfied; partial clarification is insufficient.
• Branch state: proposed new branch, subject to separate implementation authorisation and a fresh collision check.
• Branch: docs/media-library-catalogue-model.
• Base: develop, checked at 4ecdb26d9655a48bf000a7c89da2f70383edce87.
• Naming policy: local guide, validator and organisation strategy. docs/ fits the written-model contribution; the Linear title prefix does not prescribe a branch prefix. No validator execution claimed.
• PR template: verified shared documentation template. Actual inherited/named-template loading remains unverified; select explicitly rather than assume routing loads content. No local templates proposed.
• Existing work: merged audits and the surviving mixed-scope findings branch are not verified matches for reuse. No branch reuse or rename proposed.
• Constraints: planning only; preserve unrelated work. No branch creation/switching, force-push, merge, deployment or association change authorised.

Expected file changes

Provisional, documentation-only plan. Proposed edits are not approved or completed implementation.

Operation	Path	Intended change	Evidence/revision	Approval or dependency
Edit	.github/specs/002-media-library/data-model.md	Initial field dictionary, stable identity, source/reference and filename mappings, usage contexts, original/derivative relationships, evidence-backed unknown-value rules, competing envelope/naming options and reversible handoff. Examples must be labelled illustrative, not recovered-asset claims.	Read at 4ecdb26d9655a48bf000a7c89da2f70383edce87; blob 8544d5a089bfb825a6b56e74116dc261aedfc5a2; existing plan/tasks identify this deliverable	Exact file-scope approval; maintainer review; agree finalisation boundary before choosing canonical contract

Dependencies: the existing schema requires catalogueVersion and snake_case fields, while FULL-CATALOGUE.json uses catalogueMetadata and camelCase. Sampled entries retain pending recovery, null dimensions and unsupported rights/print-readiness assertions. Treat values as unverified inputs, not facts.

Keep the schema contract, full/sample catalogues, validators and TypeScript-interface implementation unchanged here. Final reconciliation belongs to the separately scoped schema-finalisation work. Do not create the absent metadata-rules contract without agreed ownership, verified destination and revised approval.

Serialise edits to the model document with recovery assessment and schema finalisation; task parallel markers do not authorise simultaneous conflicting edits. Handoff the reviewed dictionary before dependent validation guidance is finalised.

Planned review: field/source/unknown mapping, relationship examples and links. Recovered-sample validation is separate; nothing executed. Reviewer and contract decisions remain unresolved. CODEOWNERS names ashley; reviewer eligibility has not been verified. Preserve protected images/references, attribution, changelog, centrally managed workflows and human-controlled locked configuration. Do not absorb unrelated stale-guidance repairs. Stop for revised scope and approval before additional files or operations.