Profile: publishable

Profile Schema

The publishable profile indicates that a document is a full, stand-alone publishable document. While the document profile is required for all documents, publishable distinguishes standalone documents separately from those intended to be assets (which only make sense in the context of a publishable document).

Structure

The publishable profile speficies the following attributes:

Name Type Required? Explanation
brandings Link[] Yes A list of links to organization data that should be used to brand this content when rendering it; see “Brandings and Owners” section below
owners Link[] Yes A list of links to organization data that represent the organization(s) this content should be associated with in search; see “Brandings and Owners” section below
title string Yes The title of this document
assets object No A JSON object containing all assets embedded in this document. These assets can be linked in various arrays using link fragments (e.g. #/assets/12345). See the “assets” section for more information.
bylines Link[] No A list of links to byline assets; see the byline profile documentation for more information
collections Link[] No A list of links to other CDS documents; this document is considered part of these collections. For more information on collections, see the “collections” section below.
contributionNotes string No A description of the content contributions for this document
corrections Link[] No A list of links to correction assets; see the correction profile documentation for more information
editorialLastModifiedDateTime date-time string No The date and time at which the content of this document last received editorial updates; this should be in RFC3339 format set in UTC time (ex: 2021-11-04T08:49:00Z) (ex: 2021-11-04T08:49:00Z). See our tutorial on UTC time for more help.
archivedDateTime date-time string No The date and time when this content became no longer actively updated in RFC3339 format that has to be in UTC time (ex: 2021-11-04T08:49:00Z). See our tutorial on UTC time for more help.
profileExclusions Link[] No When considering this document for client profiles, these profiles will NOT be considered. See the documentation on client profiles for more information.
publishDateTime date-time string No The editorially-determined publish date and time of this document in RFC3339 format that has to be in UTC time (ex: 2021-11-04T08:49:00Z). See our tutorial on UTC time for more help.
recommendUntilDateTime date-time string No The date and time after which this document should no longer be recommended to users; this should be in RFC3339 format but also UTC time (ex: 2021-11-04T08:49:00Z). See our tutorial on UTC time for more help.
relatedItems Link[] No A list of links to CDS documents related to this document; see the “relatedItems” section for more information
shortTeaser string No A shorter description than the teaser
subtitle string No An additional description of the document
socialTitle string No An additional description of the document, for social media
teaser string No A description of the content represented by this document
webPages Link[] No A list of link objects representing pages where more information about this document can be found; see the “webPages” section for more information.

assets

The assets object is key to the overall structure of CDS documents. It represents an object in which other documents can be embedded. These embedded documents (also called “subdocuments”, “assets”, or “resources”) are stored in the object using their IDs as a key and the document itself as a value:

"assets": {
  "1234": {
    "id": "1234",
    ...
  }
}

These subdocuments can be linked thoughout this main document using link fragments as the href value:

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

Assets can be reused in multiple places throughout the document (or remain unused completely). Each asset should have a unique ID within the scope of the document. Asset IDs should be treated just as IDs; although publishing clients may choose to name them in human-readable ways, retrieval clients SHOULD NOT rely on these IDs being consistently set, and SHOULD NOT parse information out of the ID itself.

collections

The collections array defines how documents are assigned to the unordered collections of other documents. For more information on how this works, see the “collections” documentation in Core Concepts.

The collections array must contain only internally-hosted CDS document links, meaning they must start with /v1/documents. The rels array determines the relationship this document has with its associated collection document; while many of these rels have the same name as CDS profiles, linked collection documents do not have to list that profile. For example, even though a document may have a collection link with topic in the rels array, the linked document does not have to list topic as a profile. In order to determine the profiles of collection documents, clients should retrieve them from CDS (or transclude them).

Valid rels for the collections array are:

  • blog
  • category
  • episode
  • genre
  • podcast-category
  • program
  • secondary
  • series
  • slug
  • superseries
  • theme
  • topic
  • byline
  • contributor
  • music-artist

A note on the idea of a primary collection

CDS does not currently offer a way to mark a collection as the primary collection in the rels array. Rather, we rest on a convention that the 0th item in the array for collections is in fact the primary collection.

This is not a convention that is baked in our API, but rather one that npr.org upholds.

The convention also applies more specifically to collections marked with a topic rel or any other type of rel. For example, in this collections array below:

"collections": [
{
  "href": "/v1/documents/1182407811",
  "rels": [
    "series"
  ]
},
{
   "href": "/v1/documents/12345",
  "rels": [
    "topic"
  ]
}
]

The primary topic would be the 12345 document, as that is the first collection link listed that has a topic in the rels array.

brandings and owners

The brandings and owners arrays define the relationship this document has with organizations. In both arrays, these relationships are expressed as links to representations of organizations hosted via another service (usually Org V4). These links must always be external links (meaning they utilize the http or https scheme) and cannot have rels.

An example of a link used in owners or brandings is below:

{
  "href": "https://organization.api.npr.org/v4/services/s1"
}

owners

The owners array contains links to organizations associated with this document from an ownership perspective. Outside of CDS, this relationship could involve producing, maintaining, or serving the content in this document. From a CDS perspective, owners defines how a document shows up in queries. When a document is ingested, CDS extracts the href values in the owners array. When a search is performed for ownerHrefs containing a matching href value, CDS will return the document in the results.

For example, say a document contains the following owners array:

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

This document will show up under the following searches:

- ownerHrefs=https://organization.api.npr.org/v4/services/s1
- ownerHrefs=https://organization.api.npr.org/v4/services/s305

brandings

The brandings array defines what organization’s branding should be applied to a document when rendering. Clients should use the linked organization data to determine the titles, logos, and links to apply to a document when it is presented to a user. Unlike the owners array, the links in brandings are not indexed or searchable.

webPages

The webPages array contains links to web pages where this information is rendered. Links in this array must be external links, meaning they must utilize the http or https scheme. The rel value of the link indicates the type of link represented. Valid rels for webPages are listed below; invalid rels will be rejected.

  • amazon-alexa - the Amazon Alexa representation of this content
  • apple-podcasts - the Apple Podcasts representation of this content
  • canonical - the link where the primary representation of this content is displayed
  • appears-on - a resource in which this document can be found represented in whole or part in a non-canonical way
  • google-podcasts - the Google Podcasts representation of this content
  • npr-one - the NPR One representation of this content
  • pocket-casts - the Pocket Casts representation of this content
  • spotify - the Spotify representation of this content
  • stitcher - the Stitcher representation of this content
  • amazon-music - The Amazon Music representation of this content
  • iheartradio - The iHeartRadio representation of this content
  • youtube-music - The YouTube Music representation of this content

relatedItems

The relatedItems array contains links to content that have a relationship with this document. The links in relatedItems should all be links to internally-hosted CDS documents; this means they must start with /v1/documents. The relationship this content has with the linked content is determined by the rel value of the link. Valid rel values for the relatedItems array are listed below; invalid rel values will be rejected.

  • equivalent - The linked content can be used in place of this content
  • next - The linked content should be presented after this content
  • previous - The linked content should be presented before this content
  • promotional - The linked content should be presented as a promotional item related to this content

Example publishable document 

{
  "id": "12345",
  "profiles": [
    {
      "href": "/v1/profiles/publishable",
      "rels": [
        "type"
      ]
    },
    {
      "href": "/v1/profiles/document"
    }
  ],

  "assets": {
    "1111": {
      "id": "1111",
      "profiles": [
        {
          "href": "/v1/profiles/byline",
          "rels": [
            "type"
          ]
        }
      ],

      "name": "Peter Parker"
    },

    "2222": {
      "id": "2222",
      "profiles": [
        {
          "href": "/v1/profiles/correction",
          "rels": [
            "type"
          ]
        }
      ],

      "text": "A previous version of this story attributed an image to 'Eddie Brock'.",
      "dateTime": "2021-01-02T08:00:00Z"
    }
  },

  "title": "Pictures of Spiderman",
  "subtitle": "A photo collection from junior photographer Peter Parker",
  "socialTitle": "See junior photographer Peter Parker's photo collection",
  "teaser": "Meet Peter Parker, the newest addition to the Daily Bugle. Known for his close-ups of the web-slinger, Peter shares his favorite pictures of New York's very own hero.",
  "shortTeaser": "Meet Peter Parker, and see his pictures of New York's very own hero.",
  "contributionNotes": "Prince produced the audio version of this story. A version of it originally published on December 31, 1999."
  "collections": [
    {
      "href": "/v1/documents/1111"
    },
    {
      "href": "/v1/documents/2222"
    },
    {
      "href": "/v1/documents/3333"
    }
  ],
  "brandings": [
    {
      "href": "https://npr-organization-host.org/organizations/4444"
    }
  ],
  "owners": [
    {
      "href": "https://npr-organization-host.org/organizations/4444"
    },
    {
      "href": "https://npr-organization-host.org/organizations/5555"
    }
  ],
  "publishDateTime": "2021-01-01T00:00:00Z",
  "bylines": [
    {
      "href": "#/assets/1111"
    }
  ],
  "corrections": [
    {
      "href": "#/assets/2222"
    }
  ],
  "webPages": [
    {
      "href": "https://npr.org/2021/01/01/pictures-of-spiderman",
      "rels": [
        "canonical"
      ]
    }
  ],
  "recommendUntilDateTime": "2022-01-01T00:00:00Z",
  "relatedItems": [
    {
      "href": "/v1/documents/7777",
      "rels": [
        "next"
      ]
    },
    {
      "href": "/v1/documents/8888",
      "rels": [
        "previous"
      ]
    },
    {
      "href": "/v1/documents/9999",
      "rels": [
        "equivalent"
      ]
    }
  ],
  "editorialLastModifiedDateTime": "2021-01-03T00:00:00Z",
  "profileExclusions": [
    {
      "href": "/v1/client-profiles/example-client-profile"
    }
  ]
}

© 2024 npr