[igrigorik]

The released Media shape is image-oriented: one URL and one pair of dimensions cannot describe alternate encodings and sizes of an image, alternate renditions or adaptive-streaming manifests of a video, device-specific 3D formats, a poster still, or a video that exists only inside a third-party player. This PR extends the open Media type — one schema, discriminated by type — following the schema.org MediaObject family while preserving the released wire contract.

• Adds sources on every media item: alternate renditions of the resource at url — image encodings and sizes, video renditions and HLS/DASH manifests, 3D file formats — each with mime_type, format, dimensions, and filesize.
• Adds preview, a poster or thumbnail still, and name, a title distinct from accessibility-oriented alt_text.
• Adds duration in seconds for time-based media.
• Adds external_video as a well-known type for a video presented through a third-party player. Its url is the player; video.url is always a playable rendition.
• Adds per-type description schemas (media_image, media_video, media_external_video, media_model_3d) selected by open if/then composition. Every field is defined once on media.json; the per-type files refine descriptions only, so generated types are complete.
• A Platform MAY refuse to load or embed a media URL that does not use the https scheme.
• A Platform that embeds an external_video player MUST isolate it so that it cannot navigate the top-level document or otherwise act as the Platform; the web mechanism (a sandboxed, credentialless iframe) is illustrated, not mandated.
• Keeps type open. A Platform MUST NOT reject a product or response for an unrecognized media type; it MAY present the item from preview and name, or omit it. Platforms SHOULD treat the first media item they present as featured.

Image with alternate encodings

{
  "type": "image",
  "url": "https://cdn.example.com/products/runner-pro-blue.jpg",
  "alt_text": "Runner Pro in Blue",
  "width": 1600,
  "height": 1600,
  "sources": [
    { "url": "https://cdn.example.com/products/runner-pro-blue.avif", "mime_type": "image/avif", "width": 1600, "height": 1600 },
    { "url": "https://cdn.example.com/products/runner-pro-blue.jpg", "mime_type": "image/jpeg", "width": 1600, "height": 1600 }
  ]
}

Video

url is a playable rendition and appears in sources; a manifest lets the Platform stream adaptively.

{
  "type": "video",
  "url": "https://cdn.example.com/video-720.mp4",
  "name": "Product demonstration",
  "duration": 24,
  "width": 1280,
  "height": 720,
  "preview": { "url": "https://cdn.example.com/video-poster.jpg", "width": 1280, "height": 720 },
  "sources": [
    { "url": "https://cdn.example.com/video-720.mp4", "mime_type": "video/mp4", "width": 1280, "height": 720 },
    { "url": "https://cdn.example.com/video.m3u8", "mime_type": "application/vnd.apple.mpegurl" }
  ]
}

External video

The video exists only inside a third-party player, so url is the player and there are no renditions. A Platform that does not embed third-party players presents preview or omits the item.

{
  "type": "external_video",
  "url": "https://videos.example.com/embed/123",
  "name": "Runner Pro trail review",
  "duration": 212,
  "preview": { "url": "https://cdn.example.com/review-poster.jpg", "width": 1280, "height": 720 }
}

3D model

{
  "type": "model_3d",
  "url": "https://cdn.example.com/product.glb",
  "preview": { "url": "https://cdn.example.com/product-poster.jpg" },
  "sources": [
    { "url": "https://cdn.example.com/product.glb", "mime_type": "model/gltf-binary" },
    { "url": "https://cdn.example.com/product.usdz", "mime_type": "model/vnd.usdz+zip" }
  ]
}

Backward compatibility

Additive for conforming uses of the released Media contract:

• The required set remains type and url; no field is removed, renamed, or retyped; all new fields are optional; unknown type values remain valid.
• url keeps its released meaning — the media resource the Platform renders, now stated per type — and width/height keep their released meaning as intrinsic pixel dimensions.
• Media URLs carry no scheme constraint, matching every other content URL in UCP today. A Platform MAY refuse non-https media. Requiring https on content URLs is a breaking change and is proposed separately as a protocol-wide sweep of every URL a Platform renders, links, or embeds.

Also in this PR: schema_fields (docs macro) renders a description-only per-type refinement with the type and requirement of the base field it refines, instead of any / Optional; the idiom is documented in schema-authoring.md under Per-Value Field Semantics.

---

Checklist

• Capability: New schemas (Discovery, Cart, etc.) or extensions. (Requires Maintainer approval)
• Documentation: Updates to README, or documentations regarding schema or capabilities.
• I have followed the Contributing Guide
• I have updated the documentation (if applicable).
• My changes pass all local linting and formatting checks.

[igrigorik]

@amithanda thanks, great feedback! Addressed, and with benefit of fresh eyes, caught a few additional issues. PTAL.

[amithanda]

Thanks for the quick turnaround, the updates address all three of my threads (verified locally: http:, javascript:, and data: URLs are now rejected on url, preview.url, and sources[].url, and unknown type values still validate).

One thing to reconcile before merge: the PR description still reflects the first revision. It describes externally hosted video as type: "video" plus embed_url, says "a Platform must ignore media types it does not recognize", and the Backward compatibility section says "existing payloads continue to validate." With the ^https:// pattern on the released url, a payload carrying an http:// media URL that validated against 2026-08-25 will now fail. Since the description is likely to become the squash commit message, could we update it to match the current design (external_video, image sources, https requirement, MUST NOT reject)?

On classification: I agree the practical impact is probably near zero, and the security rationale is sound. But since this tightens validation on an existing field, should we either mark it feat(media)!: per versioning.md, or have TC explicitly record that it's treated as non-breaking security hardening? Either is fine with me, I'd just like the call made explicitly rather than implied by an "additive" description.

[igrigorik]

@amithanda updated PR description. You're right on the ! as it was specced, but I think we should walk that back: added a ~platform may ignore / not load to make it backwards compatible — I'd like to enable this on 08-25, not wait for next release. We can land the stronger and breaking requirement for media and other resources in followup PR.

[maximenajim]

Thanks, Ilya. Thanks for putting this together. I left just one comment for you to consider.

[amithanda]

Approving! Please take a look at the open comment from @maximenajim before merging.