File Structure

This page describes the current version of the file formats for the Jargon Platform SDK.

All Jargon Platform SDK files are in JSON format. The structure of the JSON files are described below using Typescript syntax.

File location

All files live in a single file system directory, referred to as the resource directory. The default location for the resource directory is ./resources (relative to the working directory of the hosting application). You can configure the Platform SDK to use a different directory via an initialization option.

Manifest file

The resource directory must contain a file named jargon-manifest.json. That file contains a single root object with the following structure:

interface ReleaseManifestV1 {
  // Defines the structure of the manifest file itself
  manifestFormat: ManifestFormat
  // Defines the structure of the release package file layout
  packageFormat: PackageFormat

  // The following three members are optional to support direct
  // use of the Jargon SDK without an associated project. These values
  // will always be present for Jargon Platform generated releases.

  // The Jargon project the release is for
  projectID?: string
  // The ID of the release this package corresponds to
  releaseID?: string
  // When the release was generated
  generated?: Date

  // Locales present in this package
  locales: string[]
}

type ManifestFormat = 1
type PackageFormat = 1

Example

{
  "manifestFormat": 1,
  "packageFormat": 1,
  "locales":["en-us", "fr-fr"]
}

Locale content files

The content for each locale is placed in a separate file, named after the locale (e.g., en-us.json). A locale file contains a single root object:

interface LocaleContentV1 {
  __jmd: LocaleContentMetadata
  responses?: Record<string, ResponseContent>
  strings?: Record<string, StringContent>
  objects?: Record<string, ObjectContent>
}

interface LocaleContentMetadata {
  format: LocaleContentFormat
  locale: string
}

type LocaleContentFormat = 1

The structure for each type of content (response, string, or object) is similar. The top level field (e.g., responses) is an object with user-provided keys to identify each item of content. The keys can be complex strings, but cannot contain the colon (':') character. The structure of the values is based on the following Typescript definitions:

interface VariadicContent<T extends Variant, CM extends ContentMetadata = ContentMetadata> {
  __jmd?: CM
  variants: VariantRecord<T>
}

interface ObjectContent extends VariadicContent<ObjectVariant> { }
interface ResponseContent extends VariadicContent<ResponseVariant> { }
interface StringContent extends VariadicContent<StringVariant> { }

interface ContentMetadata {
}

interface Variant {
  __jmd?: VariantMetadata
}

interface VariantMetadata {
  platforms?: [Platform]
}

interface VariantRecord<T extends Variant> extends Record<string, T> {
}

interface ResponseVariant extends Variant {
  speech?: StringResource
  reprompt?: StringResource
  alexaCard?: AlexaCardResource
  // Actions on Google rich response types coming soon
}

type StringVariant = Variant & StringResource
type ObjectVariant = Variant & ObjectResource

interface Resource<T, RM extends ResourceMetadata = ResourceMetadata> {
  __jmd?: RM
  content: T
}

interface ResourceMetadata {
}

type StringFormat = 'ssml' | 'plain' | 'apl' | 'html'
interface StringResourceMetadata extends ResourceMetadata {
  format?: StringFormat
}

interface StringResource extends Resource<string, StringResourceMetadata> {
}

interface ObjectResourceMetadata extends ResourceMetadata {
}

interface ObjectResource extends Resource<object, ObjectResourceMetadata> {
}

type AlexaCardType = 'Simple' | 'Standard'
type AlexaCard = AlexaSimpleCard | AlexaStandardCard

interface AlexaSimpleCard {
  type: 'Simple'
  title: string
  content: string
}

interface AlexaStandardCard {
  type: 'Standard'
  title: string
  text: string
  image?: AlexaCardImages
}

interface AlexaCardImages {
  smallImageUrl?: string
  largeImageUrl?: string
}

interface AlexaCardResourceMetadata extends ResourceMetadata {

}

interface AlexaCardResource extends Resource<AlexaCard, AlexaCardResourceMetadata> {
}

An example item of content (in this case, a response) looks like:

{
  "__jmd": {
    "format": 1,
    "locale": "en-US"
  },
  "responses": {
    "examples/basic response": {
      "variants": {
        "variant 1": {
          "speech": {
            "content": "Speech SSML content"
          },
        }
      }
    }
  }
}

Here we have a single response item with the key examples/minimal response, containing a single variant variant 1. That variant contains a speech resource, with the content "Speech SSML content".

The file format is very explicit with respect to placing data into well-typed containers and keeping user-provided names (item keys and variant names) separate from other fields. While this results a degree of additional nesting, that nesting helps with forward compatibility, as it avoids the risk of new fields conflicting with user-provided names.

The various optional metadata data fields (named __jmd) in the above definitions are mainly intended to support future functionality without requiring revisions to the file format. The SDK Core documentation describes metadata that impacts the variant selection or rendering process.