Skip to main content

Middleware SEO Enablement

Status: not implemented.

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

The original plan grouped all middleware work into an optional post-launch Phase 5. The implementation audit found one exception: a concrete catalogue feed is a launch dependency when the sitemap acceptance criterion requires all Movie, Show, and Event detail URLs to be discoverable.

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
Concrete cached JWX SEO feedP0Required if launch demands catalogue-complete sitemap discovery
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 JWX SEO feed​

Problem​

Control exposes route templates such as /movie/:assetId; those are routing instructions, not content URLs. record-web cannot enumerate the catalogue from getDynamicRoutes().

Contract​

Add a lean read-only endpoint in record-mw, for example:

GET /v1/ovp/seo-feed

Return only public sitemap facts:

{
  "entries": [
    {
      "id": "abc123",
      "type": "movie",
      "path": "/movie/abc123",
      "modifiedDate": "2026-07-25T10:30:00.000Z",
      "indexable": true
    }
  ],
  "nextCursor": null
}

Contract requirements:

  • paths are concrete, absolute-path values beginning with /;
  • no query strings, fragments, route placeholders, or domains;
  • only publicly indexable assets are returned;
  • pagination or cursor behaviour is deterministic;
  • modifiedDate is optional and never fabricated;
  • unknown asset types are omitted or mapped by an explicit versioned rule;
  • response size and caching are observable.

Cache the feed for a short measured TTL. Use the cache facilities already approved for record-mw; do not introduce infrastructure solely for SEO.

Web consumption​

record-web validates every entry again before rendering:

  • allowed public type;
  • concrete safe path;
  • indexable === true;
  • valid optional timestamp;
  • duplicate removal.

The existing Control routes remain useful for Home, Category, and Listing pages. The JWX feed 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 feed 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 behaviour;
  • provider failure and stale-cache behaviour;
  • no credentials or sensitive payloads in logs.

record-web:

  • invalid and placeholder feed 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.
  • A production-equivalent feed enumerates every in-scope detail URL.
  • 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.