Profile: highlight

Profile Schema

The highlight profile represents a network-curated reference to a station-owned content document. It is intended to be used as a type profile, allowing NPR or other network curators to surface station content in national aggregations and queries without modifying the original station document or creating a fully redundant renderable story object.

A highlight is a lightweight editorial object — it carries enough metadata for national curation (title, branding, a promo image) but does not replicate heavy media assets. Clients MUST follow the documentLink to retrieve audio, video, and other media from the original station document.

Motivation

Without highlights, the only way to place a station story into a network aggregation is to ask the station to add the aggregation ID to their own document’s collections array. This requires station participation for every curation decision and does not scale for high-volume events with national coverage.

Highlights allow NPR aggregation editors to independently curate station content into national feeds. A highlight is owned by the curating party (e.g. s1) and can be added to any aggregation the curating party controls, leaving the original station document untouched.

Structure

The highlight profile requires the following profiles to also be present on the document:

publishable — enforces title, owners, and brandings
internal-link — enforces documentLink

In addition, the highlight profile itself specifies the following attributes:

Name	Type	Required?	Explanation
`webPages`	Link[]	Yes	Must include at least one link with a `canonical` rel pointing to the station-owned URL; see webPages below.
`relatedItems`	Link[]	Yes	Must include at least one link with an `equivalent` rel pointing to the original station-owned document; see relatedItems below.

Document ID

The id of a highlight document must end with the -highlight suffix (e.g. g-s1-g-s252-100-highlight). This distinguishes the highlight from the original station document it references and prevents ID collisions in CDS.

owners and brandings

The owners array MUST contain the curating party’s service link (e.g. s1). It might include the station that owns the original document. The owners field controls how the highlight surfaces in ownership-filtered queries; including the station’s service ID here exposes the highlight in station-scoped and localized experiences.

The brandings array should reflect the branding of the source story — typically the originating station’s service ID — so that the highlight is presented with the correct visual identity when rendered.

documentLink

The documentLink field (required via the internal-link profile) must point to the original station-owned CDS document being highlighted. It drives two behaviors:

Ingest-time profile copy — see Ingest-time behavior below.
Client navigation — retrieval clients should follow documentLink to access the full story, including media assets not present on the highlight.

webPages

The webPages array must contain at least one link with a canonical rel. For a highlight, this should be the station-owned URL where the original content is rendered, providing a link back to the source station page. See the webPages section of the publishable profile for valid rels and link structure.

relatedItems

The relatedItems array must contain at least one link with an equivalent rel pointing to the original station-owned CDS document (typically the same document referenced by documentLink). This explicit link relationship signals to clients that the highlight is a curatorial stand-in for the linked document, not an independent piece of content. See the relatedItems section of the publishable profile for valid rels and link structure.

Images

A highlight may optionally carry a promo image by adding the has-images profile and an images entry with a primary rel. The curating party is responsible for ensuring any image used on the highlight respects the copyright and distribution rights of the source material; the upstream CMS should substitute alternative images when licensing requires it.

collections

A highlight is added to aggregations via its own collections array, just like any other CDS document. This is the primary reason highlights exist: a curator adds the highlight to a network aggregation without touching the original station document.

Optional editorial assets

The document structure supports optional editorial assets such as Notes and Corrections (via the has-notes and has-corrections profiles), though these do not have a planned national presentation at this time.

Ingest-time behavior

When a highlight document is ingested, CDS copies the profiles array of the document referenced by documentLink into meta.profiles on the highlight. This populates the meta profileIds search filter with the linked document’s profile identifiers.

For example, if the linked station document has has-audio or listenable in its profiles, those profile IDs are reflected in the highlight’s .meta.profiles search index entry. This allows queries targeting documents with specific capability profiles — such as audio playback eligibility — to return the highlight alongside its source document. CDS automatically updates highlight document meta profiles when the source linked document is re-published.

This behavior respects the highlight document’s profileExclusions field. Any profiles listed there will be omitted from the copied set, allowing curators to suppress specific source profiles from the highlight.

Example highlight document

This document is presented as an example without assets.

{
    "id": "g-s1-g-s252-100-highlight",
    "profiles": [
        {
            "href": "/v1/profiles/highlight",
            "rels": ["type"]
        },
        {
            "href": "/v1/profiles/document"
        },
        {
            "href": "/v1/profiles/publishable"
        },
        {
            "href": "/v1/profiles/internal-link"
        },
        {
            "href": "/v1/profiles/has-images"
        }
    ],

    "title": "Curation Highlight: Texas Election 2026",
    "teaser": "An essential look at Hill Country local midterm races...",

    "owners": [{ "href": "https://organization.api.npr.org/v4/services/s1" }],
    "brandings": [{ "href": "https://organization.api.npr.org/v4/services/s252" }],

    "collections": [
        {
            "href": "/v1/documents/national-midterms-collection",
            "rels": ["topic"]
        }
    ],

    "webPages": [
        {
            "href": "https://kut.org/g-s252-100",
            "rels": ["canonical"]
        }
    ],

    "relatedItems": [
        {
            "href": "/v1/documents/g-s252-100",
            "rels": ["equivalent"]
        }
    ],

    "documentLink": {
        "href": "/v1/documents/g-s252-100"
    },

    "images": [
        {
            "href": "#/assets/g-s1-999",
            "rels": ["primary"]
        }
    ]
}