Validation Schemas

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

This directory contains an early preview of machine generated JSON schema Draft-04 for Alexa Smart Home messages sent by a skill to Alexa. This schema is used to validate Smart Home skills only and is not applicable to related skills such as those using the Video Skills API. This includes schemas for the following capabilities: readme.md. We will be continuing to add additional schemas.

Note: This is an updated version from the original JSON Draft-06 schema posted. The prior version can be found here.

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 04.

How to Use

We've been able to write one JSON schema file that describes all types of messages you can send. You can test this out immediately 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-04" 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-04". 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-04". 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 04. 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.