Skip to main content

Middleware SEO Enablement

Status: catalogue discovery is implemented through the existing paginated OVP browse contract. A dedicated feed remains conditional on measured scale, freshness, or availability requirements that the current contract cannot meet.

Provider decision: Record uses JWX as its OVP. New SEO work must not extend the legacy Brightcove webhook or model path.

The original plan proposed a new middleware feed. Record middleware now exposes queryless, paginated catalogue browsing by asset type, so Web can enumerate the currently supported public detail types without adding another endpoint.

Data ownership​

record-web owns presentation and request context:

  • canonical URLs;
  • robots metadata;
  • Open Graph and Twitter metadata;
  • JSON-LD serialization;
  • sitemap XML rendering.

record-mw and JWX own source facts:

  • the set of published assets;
  • stable IDs and public route inputs;
  • publication and availability windows;
  • modification timestamps;
  • region availability;
  • provider events, if JWX exposes a supported event mechanism.

Current record-mw deployment configuration sets DEFAULT_API_KEY_OVP: JWX. The OVP registry still contains a legacy Brightcove provider, but that is not authorization to design new Record features around it.

Priority and launch impact​

Work itemPriorityLaunch impact
Existing cached OVP catalogue browseDeliveredSupplies concrete Movie, Show, Podcast, Channel, and Radio URLs
Dedicated JWX SEO feedConditionalAdd only if measured requirements exceed the existing browse contract
Real modification timestampP1Omit lastModified until available
Availability and regional indexabilityP1Required when unavailable assets would otherwise enter the feed
JWX-driven invalidationP2Freshness enhancement after a supported event source is confirmed
Sitemap segmentationConditionalRequired before any sitemap exceeds 50,000 URLs or 50 MB uncompressed

1. Concrete catalogue discovery​

Problem​

Control exposes route templates such as /movie/:assetId; those are routing instructions, not content URLs. record-web therefore combines Control routes with the existing OVP catalogue browse contract.

Contract​

The current implementation uses the existing read-only endpoint:

GET /v1/ovp/search?assetType={type}&pageSize=50&pageNumber={page}

Contract requirements:

  • asset IDs and types are converted to concrete absolute paths beginning with / by Web;
  • query strings, fragments, route placeholders, and domains are rejected;
  • pagination uses explicit pageSize and pageNumber values and stops at the first empty page; totalCount is informational because it can change while the catalogue is being enumerated;
  • unknown asset types are omitted;
  • response size and caching use the existing OVP provider controls.

The Web OVP provider caches catalogue pages for five minutes. Web caps pagination at two concurrent requests, retries each failed page once, limits output to the sitemap protocol maximum, and retains completed pages if a later request fails. Do not introduce infrastructure solely for SEO.

Web consumption​

record-web validates every entry again before rendering:

  • allowed public type;
  • non-empty encoded asset identifier;
  • concrete safe path;
  • duplicate removal.

The existing Control routes remain useful for Home, Category, and Listing pages. Catalogue browsing adds detail URLs; it does not replace Control navigation.

2. Modification timestamps​

Expose the actual JWX update timestamp when its semantics are confirmed. Map it to an optional normalized ISO 8601 field.

Rules:

  • do not fall back to request, build, publish, or ingestion time unless that is the actual modification event being represented;
  • omit invalid and unknown dates;
  • render sitemap lastModified only when the value exists;
  • test that unchanged assets keep the same timestamp across source requests.

3. Availability and region​

The feed should derive indexable from documented product rules:

  • published and currently available;
  • not expired;
  • public in the target Brazil experience;
  • not a private, transactional, or playback-only entity.

Do not reuse entitlement or subscription access as an automatic SEO exclusion. A paywalled detail page may still be publicly indexable when it exposes the approved logged-out content.

Detail endpoints need a machine-readable distinction between:

  • unknown asset;
  • permanently gone asset;
  • temporarily unavailable upstream;
  • authenticated playback restriction.

record-web can then select 404, 410, 503, or a normal indexable detail page without turning outages into soft 404 pages.

4. JWX-driven freshness​

On-demand revalidation is optional until both conditions hold:

  1. sitemap or page freshness misses a measured product target;
  2. JWX provides a supported publication/update event source.

Do not extend apps/webhook-gateway merely because it currently contains Brightcove-specific code. First choose the supported JWX integration:

  • provider webhook;
  • queue event;
  • scheduled delta poll;
  • cache TTL only.

If a push integration is selected:

  • authenticate requests with a server-only secret;
  • rate limit and deduplicate events;
  • invalidate the feed cache;
  • revalidate the affected canonical path and sitemap;
  • retry safely without logging credentials or full provider payloads.

5. Scale​

Google sitemap limits apply per sitemap. Before reaching them:

  • segment entries deterministically;
  • emit a sitemap index;
  • ensure an asset appears in exactly one child sitemap;
  • keep every URL absolute and canonical;
  • test cursor and segment boundaries.

Do not build segmentation before catalogue measurements justify it.

Out of scope​

ItemOwner
Canonical constructionrecord-web
Meta robots, Open Graph, Twitterrecord-web
JSON-LD serialization and injection safetyrecord-web
Search Console ownershipRelease or SEO operations
Legacy Brightcove webhook extensionNot an approved Record SEO design

Required tests​

record-mw:

  • JWX mapping and supported asset types;
  • availability and region decisions;
  • timestamp normalization;
  • pagination and cache behavior;
  • provider failure and stale-cache behavior;
  • no credentials or sensitive payloads in logs.

record-web:

  • invalid and placeholder catalogue paths are rejected;
  • duplicates are removed;
  • optional valid timestamps render correctly;
  • unavailable entries are absent;
  • Control listing URLs and JWX detail URLs combine predictably;
  • segmentation when enabled.

Definition of done​

  • The work is tracked under the existing RECORD SEO epic without duplicate tickets.
  • The contract is reviewed by Web and MW owners.
  • The implementation uses JWX and contains no new Brightcove dependency.
  • The production OVP browse contract enumerates the currently supported Movie, Show, Podcast, Channel, and Radio detail URLs.
  • Sitemap output is valid, canonical, complete, and within protocol limits.
  • Modification and availability values are source-backed.
  • Unit, integration, contract, and failure-path tests pass in both repositories.