Skip to content

Validation Schemas

David Zhang edited this page Dec 5, 2018 · 4 revisions

Location: https://github.com/alexa/alexa-smarthome/tree/master/validation_schemas

This directory contains JSON schema for all possible Alexa Smart Home messages sent by a skill to Alexa. For now, it's all in one JSON schema file. Use this schema to validate your messages before sending to Alexa, both from your Lambda function and your async messaging service.

NOTE: This schema is used to validate Smart Home skills only. It does not validate related skills such as those using the Video Skills API. If that is a concern for you, please post in Issues, thanks!

Overview

You may have seen the previously released v2 Validation Package. If you're not familiar with it, please read this blog post. It contains a lot of context for why we built the package, how it's used, and why it is valuable. It is being used by current Smart Home skills.

For the next evolution of our API, we've provided something similar. Instead of programmatically validating Lambda responses, which is programming language dependent, we decided to provide you with JSON schemas, which are language agnostic and can be used with any JSON validator that is complaint with JSON Schema Draft 6.

How to Use

We've been able to write one JSON schema file that describes all types of vNext messages you can send. You can test this out immediate by using an online JSON schema validator, such as JSON Schema Validator.

  1. Open JSON Schema Validator in a new browser window
  2. Ensure that you are using "draft-06" on the drop down menu on the top-left side.
  3. Copy the entire alexa_smart_home_message_schema.json schema into the left "Schema" text box. You should see a message below that says "Schema is valid according to draft-06". This means the schema is valid
  4. Now navigate to the Sample Messages directory and copy any "response" JSON file contents into the right "Document" text box. You should see a message below that says "Document validates against the schema, spec version draft-06". This means the JSON message is valid

Using this method, you can quickly validate, for example, the responses you generate from your Lambda when handling Smart Home directives from Alexa.

How to Implement Runtime Validation

As with the existing Validation Package, this tool is most useful when you can validate your messages to Alexa in real-time. We show a way to do this with our Sample Lambda written in Python. Here are the steps we took to the schema validation:

  1. From json-schema.org/software, we found jsonschema, a Python implementation of JSON Schema Draft 6. We cloned this implementation and followed instructions to add to our lambda.py
  2. Copy the latest alexa_smart_home_message_schema.json schema file into the same directory tree as the Lambda file
  3. If you've used the v2 Validation Package, you'll notice that the code to call the JSON schema validator is very similar, i.e. validate(request, response) before returning the response to Alexa
  4. If the response fails validation, the error is clearly visible in the CloudWatch logs

You can take the same approach for whatever language or platform you're using.

Remember to Validate Async Messages

With the introduction of proactive state reporting and async messages, you should also implement runtime validation for when you send async messages to Alexa.

You can’t perform that action at this time.