Jargon Platform SDK Concepts

The Jargon Platform SDK makes it easy to access for a voice application to access the content authored in the Jargon Platform when constructing responses to be sent back to users. It allows your voice application to obtain fully constructed, multi-component content (via responses, described below), along with individual content items (resources).

Architecture

The Jargon Platform SDK is built in a layered approach. At the lowest level is the SDK core. The SDK core is responsible for loading content from the file system or Jargon's content distribution servers (depending on how your application is configured), locating individual content items, and rendering content into its final form, taking into account the data passed in from the application.

Above the SDK core are adapters for voice application frameworks, such as the Alexa Skill Kit for Node.js. The platform specific adapters provide easy integration with the underlying framework, and handle the details of managing the lower-level structures for each request (including, among other things, determining the locale to use) and routing Jargon content into the correct location of the framework response object.

Content variations

In voice applications it's critical to have multiple ways of phrasing the same content, to avoid repetition and create a more engaging user experience. The Jargon Platform includes support for such variations throughout the product, making it easy to add multiple variations from the start. In the future, you will be able to specify rules for when a variation is eligible for use, furthering the ability of your application to provide responses that are tuned to the current user and their context.

Types of content

The Jargon Platform divides content into structured responses and standalone resources.

Structured Responses

A response has multiple sub-components, including speech items such as "speak" and "reprompt", and visual items like an application card. Multi-component responses allow your application to focus on business logic and determining the logical response to return; the Jargon Platform SDK takes care of the necessary plumbing to place each component in the voice platform's response structure.

Standalone Resources

Standalone resources -- strings and objects -- are for content that your application needs outside of a structured response. You can also incorporate standalone string resources into other content via a cross-reference.

Incorporating runtime data into content

Jargon managed content can contain variables; at runtime the Jargon Platform SDK uses information from your voice application to render the final content. The values that your applications provides for variables are called parameters in the SDK interfaces and documentation.

Within your content you can control the process of rendering variables using ICU Message Format constructs. Beyond simple substitution, ICU Message Format helps you to author content that's grammatically correct when dealing with such things as pluralization, gender, or formality.

Named variables

This example expects a string variable, name.

"Hello {name}"

Plural forms

This example expects a numerical variable, count.

"{count, plural, =0 {You have zero items} =1 {You have one item} other {You have # items}}.

The 'other' case (used when count is neither 0 nor 1) inserts the value of count at '#'."

Gendered forms

This example expects a string variable gender.

"{gender, select, female {She did it!} male {He did it!} other {It did it!}}"

Cross-references

A cross-reference allows a piece of content to incorporate a different piece of content. Cross references are denoted via one of the following formats:

  • Cross-reference to a string item: [string:<key>]
  • Cross-reference to a specific variant of a string item: [string:<key>:<variant>]
  • Cross-reference to a specific variant and component of a response item: [response:<key>:<variant>:<component>]

For a response the component must refer to a string component, such as "speech" or "reprompt".