Phase 3 — Structured Data

Status: not implemented. Design is blocked by JWX field confirmation and the product decision about the logged-out playback experience.

Goal: add structured data only where the rendered page and source data satisfy the applicable search-engine requirements.

---

Eligibility before implementation

Google's Video structured-data guidance applies to watch pages where users can watch a prominent embedded video. A detail page that exposes only artwork, description, and a login CTA must not automatically emit VideoObject.

Before coding:

1. Confirm whether logged-out Movie, Show, and Event pages include an embedded playable trailer, preview, or paywalled player.
2. Confirm the available JWX fields and their semantics:
   • stable media ID;
   • title and description;
   • thumbnail URL;
   • publication or upload date;
   • duration in seconds;
   • content or embed URL;
   • live start/end and publication state where relevant.
3. Resolve OQ-4: index Live/Event pages during the live window, after VOD conversion, or both.
4. Confirm that each selected page is indexable, canonical, and available to a logged-out crawler.

References:

• Google Video structured data
• Google Video SEO best practices
• Google supported structured-data features
• Next.js JSON-LD guidance

---

Schema scope

VideoObject

Implement only for an eligible watch page. Required properties and eligibility must be derived from the current Google documentation at implementation time. Return no JSON-LD object when a required value is absent or invalid.

Do not infer:

• upload date from the current time;
• duration from formatted display text;
• a playable URL from a detail-page canonical;
• Live publication windows before OQ-4 is resolved.

Show and Series pages

TVSeries is a valid Schema.org type, but Google does not currently document a standalone TVSeries rich-result feature in its Search gallery. It may help general entity understanding, but the implementation must not promise Google rich-result eligibility or a dedicated Search Console enhancement report.

Validate Schema.org conformance separately from Google feature eligibility.

---

Implementation shape

Keep serialization pure and presentation-owned:

• src/utils/jsonld.ts
  • pure builders;
  • ISO 8601 duration conversion;
  • required-field validation;
  • no provider calls or React dependencies.
• src/utils/jsonldMappers.ts
  • explicit JWX/Record model mapping;
  • no guessed property names;
  • no fabricated defaults.
• eligible detail view
  • obtains the already-loaded asset data;
  • builds the canonical URL;
  • renders one native <script type="application/ld+json">;
  • omits the script when the builder returns null.

Do not use next/script for static JSON-LD. Serialize with JSON.stringify only after escaping < as \u003c or applying an equivalent trusted sanitizer:

const serializeJsonLd = (value: object): string =>
  JSON.stringify(value).replace(/</g, '\\u003c');

This prevents a provider-controlled string containing </script> from terminating the script element.

---

Duration conversion

The duration builder receives finite non-negative seconds and emits a valid ISO 8601 duration:

Seconds	Result
0	PT0S
45	PT45S
65	PT1M5S
3723	PT1H2M3S

Reject or omit negative, non-finite, and unknown values. Ensure zero does not produce the invalid string PT.

---

Test requirements

Unit tests must cover:

• every required-field omission;
• zero, minute, and hour duration boundaries;
• invalid timestamps and URLs;
• HTML/script injection characters in every provider-controlled string;
• explicit omission when a page is not an eligible watch page;
• Movie, Show, and Live mappings using confirmed JWX fixtures;
• no JSON-LD on private, error, and unavailable pages.

Integration or rendered-output tests must parse the emitted JSON and prove that only one valid script exists per page.

---

Validation

• Use the Google Rich Results Test only for types and pages Google documents as eligible.
• Use Schema Markup Validator for generic Schema.org types such as TVSeries.
• Validate production-equivalent rendered HTML, not just builder output.
• Attach the tested URL and result to the Jira issue.

---

Definition of done

• JWX field mapping is confirmed with real fixtures.
• Logged-out playback and Live indexing decisions are documented.
• Builders omit incomplete or ineligible payloads.
• JSON-LD serialization is safe against script termination.
• Automated tests cover validation, mapping, serialization, and omission.
• Production-equivalent rendered pages pass the applicable validator.
• Documentation distinguishes Schema.org validity from Google rich-result eligibility.