v1.6.0: the media manifest

[foadshafighi]

What this release adds

A record gains an optional pointer-only media[] array naming the visual assets that document the product: product photographs, application photographs, and dimensional drawings, each referenced by filename, IANA media type, and SHA-256 content hash. Entries are pointers, never bytes: no image data enters a record.

Cutsheets carry photographs and dimensional drawings, and until now a record had no home to reference them by content hash.

Schema

• New optional top-level array media, entries defined by the new $defs/MediaAsset. Each entry requires role, reference (a standard FileReference, so filename and sha256 are required and url is optional), and media_type. Optional descriptors: primary, alt_text, caption, language, width_px, height_px, size_bytes, rights, credit, extracted_from_ref, and configuration_refs.
• Two new closed taxonomy enums. MediaRole carries four tokens (product_photo, application_photo, dimensional_drawing, other) that map one-to-one to GLDF's image types, so a crosswalk between the two formats is mechanical. MediaType carries four RFC 6838 image-format tokens (image/jpeg, image/png, image/svg+xml, image/webp).
• The manifest admits image formats only. A PDF is a document, not a picture, and belongs in source_files, so the media manifest and the source-file list share no format and list placement is decided by format rather than by judgement.
• A media entry carries no SourceFileType token by design, so a photograph can never serve as the provenance source for a measured value.
• Every constraint this release adds lives inside the new definition, and media joins no required set, so no previously-valid record is affected.

Validator

• The byte-verification walk covers media[].reference with the default policy: a local hash mismatch is an ERROR, an unreadable file a WARNING, a locally absent file an INFO. The site registry, the validate help text, and the validator README all name the new site.
• Media findings reuse the established file-reference finding codes, which are a stable public contract; the finding's JSON Pointer names the media site, for example /media/0/reference.

Inert by construction

No grading change, no achievements change, and no index change. BuilderVersion stays 0.7.0, so no stored record needs re-stamping. All 8 example records, every golden file, and the validate and scope outputs are byte-identical against pre-change baselines, exit codes included.

Deliberately not in this release

• No example record changes. The repository's real-data rule (ROADMAP.md, CONTRIBUTING.md) forbids fabricating values, so shipped examples gain media entries when their manufacturers supply real imagery with written usage rights.
• No workbook columns and no converter change. ulc from-sheet gains no media columns here; workbook authoring for media arrives with the first example records that carry real imagery, designed against real files. No template or mapping guide changes.
• No index projection. A projection of the roles present would bump the builder version and mark every stored record's index stale, so it is held until a real facet or search consumer needs it (recorded in ROADMAP.md).
• No new structural advisories. Locally checkable incoherences (more than one primary per role, duplicate role and hash pairs, an extension inconsistent with media_type, a dangling extracted_from_ref) are schema-valid by design and stay deferred until real media-bearing records exist to design them against.

Governance

Proposed as a Schema Change Proposal in #55, opened alongside this PR.

[github-actions]

Codex Automated Code Review

Code Review Summary

PR: Adds the v1.6 pointer-only media manifest, taxonomy, documentation, and hash verification.

P0 - Critical Issues (Must Fix)

None found.

P1 - High Priority Issues (Should Fix)

• schema/ulc.schema.json:555 — caption is optional even when role is other, although the taxonomy and documentation say the caption identifies what an other asset is. Add an if/then condition requiring caption for role: other, with a corresponding rejection test.

• schema/ulc.schema.json:546 — The specification says there may be at most one primary: true asset per role, but the schema accepts multiple primaries. This leaves consumer selection dependent on document order despite claiming a uniqueness rule. Either enforce uniqueness through a suitable media structure/custom validator, or consistently describe this as authoring guidance rather than a constraint. Related claims occur at docs/authoring-patterns.md:114 and CHANGELOG.md:37.

P2 - Medium Priority Issues (Consider Fixing)

• schema/ulc.schema.json:560 — language claims to be a BCP 47 language tag but accepts every non-empty string. Add an appropriate validation mechanism and tests, or soften the description to state that BCP 47 is an authoring convention rather than an enforced format.

P3 - Low Priority Issues (Optional)

None found.

Positive Observations

• The enum/structure split is preserved correctly.
• Media references reuse FileReference, retaining mandatory SHA-256 hashes.
• The validator registry, policy tests, schema tests, documentation, and release notes were updated consistently.
• No generated-index, workflow, paid-standard-text, dual-unit, or research/ violations were introduced.

The Go test suite could not be executed because the review environment is entirely read-only and Go could not create its build cache.

---

Automated review by OpenAI Codex

[github-actions]

Codex Automated Code Review

Code Review Summary

PR: Adds a pointer-only media manifest and media hash verification for ULC 1.6.0.

P0 - Critical Issues (Must Fix)

None found.

P1 - High Priority Issues (Should Fix)

• schema/ulc.schema.json:529: The schema permits {"role":"other"} without a caption, although the schema, taxonomy, documentation, and changelog all state that other is qualified/described by its caption. Add an if/then requiring caption when role is other, plus rejection coverage in schema_test.go.

• docs/authoring-patterns.md:116: The documentation claims the schema mechanically ensures that media entries are images, but the schema only validates the declared media_type. A PDF can be referenced as image/png, and the validator at tools/validator/internal/validate/references.go:58 verifies only its hash. Either validate the referenced bytes against media_type or soften the claims that documents “can never” be declared there.

P2 - Medium Priority Issues (Consider Fixing)

• schema/ulc.schema.json:560: language is described as a BCP 47 language tag but accepts every non-empty string. Add an appropriate BCP 47 constraint/format supported by the reference validator, or describe it as an unconstrained language identifier.

• schema/ulc.schema.json:595: configuration_refs permits duplicates and an empty array, despite representing a set of specific order codes. Add minItems: 1 and uniqueItems: true so empty or repeated references do not carry ambiguous semantics.

P3 - Low Priority Issues (Optional)

None found.

Positive Observations

• Taxonomy enums remain correctly isolated in schema/taxonomy.schema.json.
• Every media entry reuses the mandatory SHA-256 FileReference shape.
• The verifier registry, policy tests, schema tests, docs, changelog, and roadmap were updated consistently.
• The addition is fixture-relevant, additive, ungraded, and leaves the generated index untouched.
• JSON syntax and cross-file references are valid; no restricted standards text, dual-unit regression, workflow risk, or generated-index violation was introduced.

---

Automated review by OpenAI Codex

[greptile-apps]

Greptile Summary

The PR introduces the optional pointer-only media manifest, closed role and image-format taxonomies, and default validator hash verification for media references.

• Adds MediaAsset, MediaRole, and MediaType schema definitions.
• Registers media references in the validator’s default verification walk and expands its tests.
• Updates release, authoring, validator, and project documentation for v1.6.0.

Confidence Score: 4/5

The PR appears safe to merge from a runtime and schema-compatibility perspective, but its supported authoring guidance should be updated to cover the new media surface.

The schema addition is optional and the validator consistently verifies its references, while the remaining issue is a non-blocking cross-file propagation gap in mappings and templates.

Files Needing Attention: schema/ulc.schema.json, mappings/pim/salsify.md, templates/workbook/

Important Files Changed

Filename	Overview
schema/ulc.schema.json	Adds the optional media manifest and MediaAsset definition; the schema is additive, but the new authoring surface was not propagated to mappings or templates.
schema/taxonomy.schema.json	Adds closed MediaRole and MediaType enums with references resolving from MediaAsset.
tools/validator/internal/validate/references.go	Registers media[].reference under the established default file-verification policy using the shared traversal implementation.
tools/validator/internal/validate/references_test.go	Extends registry, policy, default-run, and per-site outcome coverage to the media reference site.
tools/validator/internal/validate/schema_test.go	Covers required media members, taxonomy rejection, FileReference requirements, and representative optional constraints.
CHANGELOG.md	Documents v1.6.0 and its media behavior, including the intentional omission of workbook authoring support.

Prompt To Fix All With AI

### Issue 1
schema/ulc.schema.json:179-183
**Media authoring paths remain stale**

The new `media[]` surface is absent from the PIM mappings and workbook template, so authors following the supported integration guidance cannot emit the manifest and can incorrectly route visual assets through `source_files[]` or omit them.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "docs(release): date the 1.6.0 section to..." | Re-trigger Greptile}

[greptile-apps]

Media authoring paths remain stale

The new media[] surface is absent from the PIM mappings and workbook template, so authors following the supported integration guidance cannot emit the manifest and can incorrectly route visual assets through source_files[] or omit them.

Rule Used: Field added/renamed/removed in schema/** must prop... (source)

Prompt To Fix With AI

This is a comment left during a code review.
Path: schema/ulc.schema.json
Line: 179-183

Comment:
**Media authoring paths remain stale**

The new `media[]` surface is absent from the PIM mappings and workbook template, so authors following the supported integration guidance cannot emit the manifest and can incorrectly route visual assets through `source_files[]` or omit them.

**Rule Used:** Field added/renamed/removed in schema/** must prop... ([source](greptile.json))

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[foadshafighi]

Thanks both. Each finding was checked against the shipped schema and validator source. No changes for this release; the reasoning is below so the decisions are on the record rather than implicit.

Requiring caption when role is other. The schema, the taxonomy, the docs, and the changelog all describe the caption as what identifies an other asset. None of them states it as a requirement, so the text and the constraint set do not disagree. Making it conditionally required is a design change rather than a correction, and this release ships no conditional constraints inside MediaAsset on purpose. It stays a candidate for the first release that carries real media-bearing records, where the rule can be designed against actual authoring behavior.

More than one entry with primary: true. This is stated as authoring guidance with a defined consumer fallback rather than as a constraint: "At most one entry per role should set it true; consumers encountering more than one fall back to document order." The record stays unambiguous when the guidance is not followed, which is why it is not enforced. It is one of four locally checkable structural conditions that are schema-valid by design here (several primaries in one role, duplicate role and hash pairs, a filename extension inconsistent with media_type, and a dangling extracted_from_ref or configuration_refs), all named as future validator candidates. An advisory written now would be designed against zero records, since no shipped example can carry media under the repository's real-data rule.

"a document format can never be declared there". The claim is scoped to declaration, which is exactly what the schema enforces: MediaType is a closed set of four image tokens, so application/pdf is rejected at /media/<i>/media_type. It does not claim the bytes are inspected, and no ULC tool sniffs content type. ulc validate hashes the referenced file and compares it against the declared SHA-256, nothing more. A mislabelled file, a PDF declared as image/png, is a different condition from a document format being declarable, and it is one of the four structural conditions listed above.

A BCP 47 pattern on language. Left unconstrained beyond a non-empty string for this release, on the same reasoning.

Media absent from the PIM mapping guides and the workbook template. Intentional, and stated in the release notes: ulc from-sheet gains no media columns here, and no template or mapping guide changes. The authoring path arrives with the first records that carry real imagery, so the columns are designed against real files rather than guessed. Until then the workbook cannot author media at all, which is the honest state to ship.