Profiles

A profile is a set of validation constraints that restricts the structure of a document. Currently, CDS uses JSON schema to define its profiles, but may use additional validation constraints in the future.

There are two types of profiles: common profiles and client profiles.

Common Profiles

Common profiles define attributes, assets and required fields for constructing documents. Publishers place common profiles on documents (in the profiles, defined in the document profile), which are then validated by CDS. By placing a profile on a document, publishers and retrieval clients gain a shared understanding of the document structures and semantics.

Common profiles are stored internally to CDS, and managed by the NPR CDS team. A list of common profiles is in the left side bar, and at the bottom of this page; each common profile has a documentation page describing its basic usage and structure.

Common profile basics

In every publishable CDS document, there is a profiles array listing the applicable profiles for a document. If a document from CDS shows a list of profiles, each profile listed indicates:

  • This document adheres to this profile; that is, it was published and validated against the requirements for this profile
  • The document can be expected to contain content defined by this profile

An example: story

Consider the story profile:

{
  "$schema": "https://json-schema.org/draft/2019-09/schema#",
  "$id": "/v1/profiles/story",
  "title": "Story",
  "description": "A publishable story document",
  "type": "object",
  "properties": {
    "editorialMajorUpdateDateTime": {
      "description": "The date and time at which the content of this story received significant editorial updates",
      "type": "string",
      "format": "date-time"
    }
  }
}

This profile specifies a number of constraints, particularly around the editorialMajorUpdateDateTime attribute:

  • This attribute must be a string
  • This attribute must be a date-time format in RFC3339 format set in UTC time (ex: 2021-11-04T08:49:00Z)
  • This attribute is optional

A document might list this profile in the following way:

"profiles": [
  {
    "href": "/v1/profiles/story"
  }
]

Listing this profile means two things:

  • When publishing, this document will be validated against the story profile. If its format is invalid (say, if editorialMajorUpdateDateTime is an integer, not a string), then the document will be rejected from CDS.
  • When retrieving, this document can be assumed to be valid against the story profile.

Common profile composition

A document will (almost always) contain multiple profile links in its profiles array. These profiles are applied in composition, meaning that the document’s structure must be valid against all listed profiles. If any of the profiles do not validate against the document, the document as a whole is rejected.

Profile validation

All CDS documents must list the document profile, which defines basic underlying structure. Standalone documents must also list the publishable profile.

Client Profiles

Client profiles are created and managed by the retrieval clients who are retrieving documents from CDS so they can add their own special requirements. Client profiles are applied to CDS on publication; this means that if a document conforms to a client profile, it gets it without the publisher adding it. This will allow retrieval clients to efficiently retrieve the documents that fit their needs.

Publishers SHOULD NOT set these profiles in their documents on publish; the CDS will manage the application of client profiles. But client profiles allow publishers to know what content each retrieval client needs so they can tailor their documents accordingly if they so desire. See the section on client profiles for more details. It should be noted that changing a client profile is not considered a breaking change for any application but the retrieval client itself and therefore a retrieval client can change its client profiles whenever they feel it is necessary.

Common profile documentation

The following is a list of all common profiles currently available via CDS, along with their documentation.

© 2024 npr