$schema: http://json-schema.org/draft-04/schema#
definitions: {}
id: label
type: object
description:
  A label can be named anything.  When the user does not have an established state, the first label is the first to be evaluated.
properties:
  speak:
    $ref: speech.yml
    description:
      This is the simplest way to add speech to your skill response.  
      Any text provided can include SSML.  You can either provide a 
      plain string, or you can provide an object with keys for different
      localizations.
  ask: 
    $ref: speech.yml
    description:
      An ask is almost exactly the same as `speak:` except it tells the 
      Alexa-enabled device to wait for a user response.  This prevents 
      other label keys, such as `utterances:`, `events:`, and `condition:`
      from evaluating until the user has responded.  It is separate from 
      `speak:` because it is the default reprompt speech in case `reprompt:`
      is not specified.  Takes a string or a SPEECH object.
  reprompt:
    $ref: speech.yml
    description:
      Again, similar to `speak:` and `ask:`, but is used when the 
      Alexa-enabled device waited for the user to say something and said 
      user didn't respond.
  error speech:
    $ref: speech.yml
    description:
      If something really goes wrong(i.e. an application error occurs),
      this is the speech that gets sent to the Alexa-enabled device.  
      It overrides any other speech that may have been specified as part 
      of the label or from labels that executed previously.
  go to:
    type: string
    description:
      Navigates to a different label once the evaluation of the current 
      label has completed.  May be overridden by label keys such as 
      `utterances:`, `events:`, or `condition:` if they contain their own
      `go to:` keys that get evaluated.  Is deferred until the user responds
      if an `ask:` key is specified in the label.  When no navigation 
      occurs, execution stops at this label until a new request is made.
  swallow pill:
    type: string
    description:
      This is like `go to:`, but navigates to a pill.  The string provided
      should match the file name of the pill sans the ".yml" part.  When used,
      this overrides `go to:` and defaults the current label state to the 
      first label in the specified pill.
  assign:
    $ref: assignment.yml
    description:
      This is how values are stored during a session.  They are kept as session attributes.
  temp:
    $ref: assignment.yml
    description:
      Similar to `assign:`, but stores temporary values that only last for the
      duration of the current request and do not persist for the rest of the 
      session.  If a variable specified in `temp:` matches one specified in 
      `assign:`, it will override the value from `assign:` until it gets cleared.
      This can get confusing, so it's a good idea to not have variable names 
      overlap between `assign:` and `temp:`.
  events:
    $ref: events.yml
    description:
      An event is currently synonmymous with the type of skill request being 
      received.  For example, you may want to have something different happen 
      when there is a LaunchRequest versus a SessionEndedRequest.  An EVENTS 
      object shares some basic functionality with the LABEL object, such as 
      `go to:`, to facilitate navigation.  
  utterances:
    $ref: utterances.yml
    description:
      This is where you define how the skill reacts to speech from the user.  As
      with the EVENTS object, the UTTERANCES object shares some basic functionality
      with the LABEL object so that different speech from the user can facilitate 
      specific navigation through skill states.  
  web request:
    $ref: web-request.yml
    description:
      Make HTTPS requests to external resources by providing either a string with 
      a URL or a WEB REQUEST object with more options.  This is always executed 
      before all the other keys when a label is evaluated.  It always expects a 
      JSON response.  If you need to request something other than JSON(e.g. XML), 
      you should probably make a separate service to translate what you need into 
      JSON.  For example, you could write an AWS Lambda function that makes the 
      initial API request and serves JSON to your skill.  However, it's recommended
      to not use crappy APIs to begin with.  The result of the request is assigned
      to the `webResponse` variable, and any top-level keys in the JSON response 
      are assigned to variables in the current scope.  
  card:
    $ref: card.yml
    description:
      Allows you to return a card as part of the skill response.
  audio:
    $ref: audio.yml
    description:
      Adds an audio directive to the skill response so that the Alexa-enabled device
      will play the specified audio file.  Simply providing a URL to an audio file 
      as a string will tell the Alexa-enabled device to clear the queue(REPLACE_ALL)
      and play the audio.  To stop the currently playing audio, you can provide 
      "stop" as a string and a stop directive will be added to the request.  
      Similarly you can "clear enqueued" or "clear all".  The `audio:` key can also 
      take an AUDIO object, which allows greater finesse of the audio directive.
  condition:
    $ref: condition.yml
    description:
      The equivalent of "if, then, else".  Use this for basic logic switching for 
      modifying attributes or for navigating.
  restore:
    type: string
    description:
      Restores session data from the previous session.  This will only work if a
      database such as DynamoDB or CouchDB is configured to persist session data.
      Providing 'session' as the value will restore both the state(current pill
      and label) and attributes, whereas providing 'attributes' will only restore
      saved attributes and not the pill/label state.