• Client Profiles
  • Creating your profiles
  • Accessing Client Profiles
  • A note for publishers
    • Excluding content from a client
      • Example Exclusion
  • Using client profiles

Client Profiles

A “client profile” is a profile that is created, maintained, and managed by a single CDS retrieval client; these are different from the “common profiles” that are built into CDS.

A client profile is used by a retrieval client to mark and retrieve a subset of CDS documents that meet the client’s determined specifications. These allow clients to specify requirements on documents in addition to those defined by CDS’ built-in common profiles. This also gives publishers insight into what requirements are needed by a client in order to utilize a document.

A good example is the client profile used by NPR One applications. Publishers who are expecting their content to appear in NPR One can look at that client profile and make sure they have the required document structure. Furthermore, a publisher can specifically exclude a client profile from their document; this is useful if a document has everything that NPR One requires, but editorially it was decided that this isn’t a good story to appear in NPR One.

Creating your profiles

The NPR Team is happy to help you create your client profiles! So don’t worry if you are not a JSON schema expert.

That said, client profiles are JSON schema documents just like the common profiles and they are subject to the following restrictions:

• The profile ID MUST be of the form “/v1/client-profiles/"; the last part of the profile (the "name") must be unique within the set of all CDS profiles, including common profiles.
• Client profiles MUST NOT reference other client profiles.

Once the client profile is ready to go, the NPR Team will review it. Once approved, it will be added to the CDS where it will be available for querying and validation.

Accessing Client Profiles

Client profiles are stored in CDS, and will be accessible via the get client profile endpoint.

A note for publishers

Publishers do not need to (and in fact can not!) add client profiles to their documents on publish as they do common profiles.

Instead the CDS will compare the document when it is published with all the client profiles and add them to a meta section of the document automatically. New client profiles added after the document was published will also be applied if there is a match.

Excluding content from a client

If a publisher wants to keep content out of a specific client, they can use the attribute profileExclusions described in the common publishable profile. This optional attribute will be an array of client profiles that the publisher does not wish to be validated against. This prevents the client profile from being added to the document’s meta section and if the client searches using that profile it will not be returned. It should be noted that any document added to the CDS can be accessed by any client, regardless of exclusions. Profile exclusions allow publishers to keep the client profile off their document, but a client can choose to query for documents without using that client profile.

Example Exclusion

"profileExclusions": [
     {
         "href": "/v1/client-profiles/has-transcript"
     }
  ]

When a document is validated against client profiles, it will not be validated against profiles listed in the profileExclusions array. This way a publisher can have some control of where their content appears.

Using client profiles

When a client wants to retrieve content based on their client profile, they can use the profile name (the last part of the ID) in the profileIds query. This can be combined with common profiles to create more complex queries as needed.

See filtering under the query documentation for more details.