Validation
This utility provides JSON Schema validation for events and responses, including JMESPath support to unwrap events before validation.
Key features¶
- Validate incoming event and response
- JMESPath support to unwrap events before validation applies
- Built-in envelopes to unwrap popular event sources payloads
Getting started¶
Using JSON Schemas for the first time?
Check this step-by-step tour in the official JSON Schema website.
You can validate inbound and outbound events using validator
decorator.
You can also use the standalone validate
function, if you want more control over the validation process such as handling a validation error.
We support any JSONSchema draft supported by fastjsonschema library.
Warning
Both validator
decorator and validate
standalone function expects your JSON Schema to be a dictionary, not a filename.
Validator decorator¶
Validator decorator is typically used to validate either inbound or functions' response.
It will fail fast with SchemaValidationError
exception if event or response doesn't conform with given JSON Schema.
1 2 3 4 5 6 7 |
|
1 2 3 4 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 |
|
Note
It's not a requirement to validate both inbound and outbound schemas - You can either use one, or both.
Validate function¶
Validate standalone function is typically used within the Lambda handler, or any other methods that perform data validation.
You can also gracefully handle schema validation errors by catching SchemaValidationError
exception.
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
1 2 3 4 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 |
|
Unwrapping events prior to validation¶
You might want to validate only a portion of your event - This is where the envelope
parameter is for.
Envelopes are JMESPath expressions to extract a portion of JSON you want before applying JSON Schema validation.
Here is a sample custom EventBridge event, where we only validate what's inside the detail
key:
We use the envelope
parameter to extract the payload inside the detail
key before validating.
1 2 3 4 5 6 7 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 |
|
This is quite powerful because you can use JMESPath Query language to extract records from arrays, slice and dice, to pipe expressions and function expressions, where you'd extract what you need before validating the actual payload.
Built-in envelopes¶
This utility comes with built-in envelopes to easily extract the payload from popular event sources.
1 2 3 4 5 6 7 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 |
|
Here is a handy table with built-in envelopes along with their JMESPath expressions in case you want to build your own.
Envelope name | JMESPath expression |
---|---|
API_GATEWAY_REST | "powertools_json(body)" |
API_GATEWAY_HTTP | "powertools_json(body)" |
SQS | "Records[*].powertools_json(body)" |
SNS | "Records[0].Sns.Message |
EVENTBRIDGE | "detail" |
CLOUDWATCH_EVENTS_SCHEDULED | "detail" |
KINESIS_DATA_STREAM | "Records[*].kinesis.powertools_json(powertools_base64(data))" |
CLOUDWATCH_LOGS | "awslogs.powertools_base64_gzip(data) |
Advanced¶
Validating custom formats¶
New in 1.10.0
JSON Schema DRAFT 7 has many new built-in formats such as date, time, and specifically a regex format which might be a better replacement for a custom format, if you do have control over the schema.
JSON Schemas with custom formats like int64
will fail validation. If you have these, you can pass them using formats
parameter:
1 2 3 4 5 6 |
|
For each format defined in a dictionary key, you must use a regex, or a function that returns a boolean to instruct the validator on how to proceed when encountering that type.
1 2 3 4 5 6 7 8 9 10 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 |
|
Built-in JMESPath functions¶
You might have events or responses that contain non-encoded JSON, where you need to decode before validating them.
You can use our built-in JMESPath functions within your expressions to do exactly that to decode JSON Strings, base64, and uncompress gzip data.
Info
We use these for built-in envelopes to easily to decode and unwrap events from sources like Kinesis, CloudWatch Logs, etc.
powertools_json function¶
Use powertools_json
function to decode any JSON String.
This sample will decode the value within the data
key into a valid JSON before we can validate it.
1 2 3 4 5 6 7 8 9 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 |
|
powertools_base64 function¶
Use powertools_base64
function to decode any base64 data.
This sample will decode the base64 value within the data
key, and decode the JSON string into a valid JSON before we can validate it.
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 |
|
powertools_base64_gzip function¶
Use powertools_base64_gzip
function to decompress and decode base64 data.
This sample will decompress and decode base64 data, then use JMESPath pipeline expression to pass the result for decoding its JSON string.
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 |
|
Bring your own JMESPath function¶
Warning
This should only be used for advanced use cases where you have special formats not covered by the built-in functions.
This will replace all provided built-in functions such as powertools_json
, so you will no longer be able to use them.
For special binary formats that you want to decode before applying JSON Schema validation, you can bring your own JMESPath function and any additional option via jmespath_options
param.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 |
|