Link Objects

Links in CDS are always represented by a JSON object conforming to the link schema. The link schema defines the following:

Name Type Required? Explanation
embed object No The embed object is only present when CDS is returning a document with transcluded attributes. The embed object should never be supplied by publishers; if present, it will be stripped.
href string Yes The string URL of the linked file itself
rels string array No A set of strings describing the relationship between the current document and the linked document
type string No The expected RFC6838 compliant media type of the linked file (ex: audio/wav)

Note that links in CDS can conform to more than just this schema! For example, an audio enclosure link could additionally specify a fileSize attribute.

rels

In CDS, the rels array is used to describe the relationship between the current document containing the link and the document linked (in this context, “document” doesn’t have to mean CDS document; the linked document could be from anywhere).

In almost every case, the rels available to place on a link are restricted down to a small set of values. Check the documentation for the profile you’re implementing to determine which rels can be used and what they mean. In general, all rels must be compliant with the rules for link relations found in RFC8288.

There are three types of links in CDS documents: internal, external, and fragments.

External links designate a link to a resource that is hosted externally to CDS itself. Some examples would be:

  • links to organization data
  • links to media hosted on a CDN
  • links to the NPR.org website

All external links in CDS should be represented as a full URL.

Internal links designate a link to a document hosted by CDS. Some examples are:

  • links to other CDS documents (/v1/documents/1111)
  • links to CDS profiles (/v1/profiles/text)
  • links to CDS schemas (/v1/schemas/link)

All internal links in CDS can be represented as either a full URL containing the CDS domain, or as relative links (path-only). CDS will interpret all relative links as relative to itself.

Fragments

Link fragments specify a link to a piece of the current document. While URL syntax allows for a fragment appended to the end of a URL (e.g. https://npr.org/#home), CDS does not currently support this, and will only evaluate fragments given alone.

A fragment is commonly used to link to assets embedded within the current document. Consider the following:

{
  "id": "1111",
  "assets": {
    "2222": {
      "id": "2222"
    }
  },

  "layout": [
    {
      "href": "#/assets/2222"
    }
  ]
}

In the above example, #/assets/2222 is a fragment used to link to the 2222 asset embedded in the assets object.

CDS assets link fragments should be in JSON Pointer syntax, as defined by RFC6901. All fragments in CDS are interpreted as being relative to the document that contains them.

Extension links

“Extension links” are a way of linking a CDS document to another CDS document that produces notifications for the linking document whenever the linked document is modified.

To explain further, let’s look at the “normal” CDS document publishing process:

The “normal” publishing flow

In “normal” CDS documents, a link on a document does not affect downstream notifications. That’s to say: on publish, one doc produces one notification (as long as it’s changed; documents that haven’t changed produce no notifications). Even though that document may be linked to by other CDS documents (and vice versa), this has no affect on notifications; it’s the client’s responsibility to determine how its data should change based on the linkages it knows about.

An example of this is diagrammed below:

Publishing without an extension link

In the above example, notifications are only sent for Document B. Because Document B has “no knowledge” of Document A (or any other document linking to it), downstream clients won’t cache kill for Document A. This can be a problem for documents like transcripts.

Story documents can link to transcript documents via the transcriptLink attribute on the audio asset profile. When rendering these pages, the transcript may be included in the story content itself. However, if the transcript is updated, a notification is sent for the transcript document only. Downstream clients won’t update their caches for the story page, and old content is served.

An extension link is an internal document link on a CDS document with the extension rel:

"link": {
  "href": "/v1/documents/1111",
  "rels": [
    "extension"
  ]
}

When CDS receives an update to a document, it will send notifications for it and any document containing an extension link to it. This is diagrammed below:

Publishing with an extension link

In the above example, a notification is sent for both Documents A and B, because A contains an extension link to B. This happens even though Document A has not changed.

© 2024 npr