# Media and image specification

This page is the normative human-readable media contract for zentra Property Feed v1.0. Enforceable structure lives in the XSD and the `ZPF-MEDIA-*` semantic rules.

## Ordering and identity

Each item has a provider-stable `id`, a unique positive `order` inside its property, and one role: `photo`, `hero`, `floorplan`, `site_plan`, `brochure`, or `document`. The lowest order is processed first. Use exactly one `hero` when a preferred lead image exists. IDs and ordering must remain deterministic across unchanged exports.

The v1 hard limit is 200 media items per property. The limit is based on the observed production maximum of 176 image rows on 2026-08-22, with bounded growth room. Keep normal property sets at or below 50 where practical. Kyero v3.9 accepts the first 50 photos and documents 1280 by 960 pixels as its baseline; those are compatibility notes, not zentra's hard limit.

## URLs and transport

URLs must be absolute HTTPS URLs, publicly fetchable without cookies, expiring signatures, interactive login, or IP allow-listing. Redirect chains must contain at most three hops and stay on HTTPS. Servers must return a successful status and a content type matching `mime_type`. Tracking pixels, HTML error pages, placeholder images, and “photo coming soon” assets are invalid.

The audit client follows redirects, sends a descriptive user agent, limits connect and response time, reads headers first, and never downloads more than 20 MiB. Feed providers must permit bounded `HEAD` or ranged `GET` requests.

## Formats, dimensions, and size

Accepted raster types are JPEG, PNG, and WebP. PDF is accepted only for `brochure` and `document`. SVG, animated formats, archives, and executable content are rejected. A raster property image should be at least 1280 by 960 pixels and the recommended source is 2400 pixels or more on its longest edge. Floorplans may use portrait or landscape ratios; photos should normally stay between 4:5 and 21:9. Never upscale a small original merely to satisfy metadata.

The maximum payload is 20 MiB per item. The recommended target is below 5 MiB for photos and 10 MiB for PDFs. Report accurate optional `width`, `height`, and `bytes` values when known. If supplied, a checksum must be lowercase SHA-256 in `sha256:<hex>` form.

## Captions, duplicates, and privacy

Captions are plain text and may repeat once per locale. They should describe the asset, not repeat search keywords. Remove EXIF location, device, author, and other unnecessary metadata before publication. Do not expose an exact address or floorplan when the seller, occupant, or local law requires location privacy.

Duplicate checks use checksum first and normalised final URL second. Repeated bytes, duplicate media IDs, and duplicate order values are errors. A repeated URL with a distinct role is still considered a duplicate unless the rendered content is intentionally different.

Video and virtual-tour URLs belong under `links`, not `media`. They must be stable public HTTPS pages from an approved provider, free from auto-downloads or credential prompts, and suitable for embedding under the receiving platform's content-security policy.