Skip to content

Commit 2240d80

Browse files
jeromevdljeromevdl
committed
documentation
1 parent af05320 commit 2240d80

File tree

1 file changed

+30
-92
lines changed

1 file changed

+30
-92
lines changed

‎docs/utilities/validation.md

+30-92
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,12 @@ This utility provides JSON Schema validation for payloads held within events and
88
**Key features**
99

1010
* Validate incoming events and responses
11-
* Built-in validation for most common events (API Gateway, SNS, SQS, ...)
11+
* Built-in validation for most common events (API Gateway, SNS, SQS, ...) and support for partial batch failures (SQS, Kinesis)
1212
* JMESPath support validate only a sub part of the event
1313

1414
## Install
15-
Depending on your version of Java (either Java 1.8 or 11+), the configuration slightly changes.
1615

17-
=== "Maven Java 11+"
16+
=== "Maven"
1817
```xml hl_lines="3-7 16 18 24-27"
1918
<dependencies>
2019
...
@@ -58,52 +57,7 @@ Depending on your version of Java (either Java 1.8 or 11+), the configuration sl
5857
</build>
5958
```
6059

61-
=== "Maven Java 1.8"
62-
63-
```xml hl_lines="3-7 16 18 24-27"
64-
<dependencies>
65-
...
66-
<dependency>
67-
<groupId>software.amazon.lambda</groupId>
68-
<artifactId>powertools-validation</artifactId>
69-
<version>{{ powertools.version }}</version>
70-
</dependency>
71-
...
72-
</dependencies>
73-
...
74-
<!-- configure the aspectj-maven-plugin to compile-time weave (CTW) the aws-lambda-powertools-java aspects into your project -->
75-
<build>
76-
<plugins>
77-
...
78-
<plugin>
79-
<groupId>org.codehaus.mojo</groupId>
80-
<artifactId>aspectj-maven-plugin</artifactId>
81-
<version>1.14.0</version>
82-
<configuration>
83-
<source>1.8</source>
84-
<target>1.8</target>
85-
<complianceLevel>1.8</complianceLevel>
86-
<aspectLibraries>
87-
<aspectLibrary>
88-
<groupId>software.amazon.lambda</groupId>
89-
<artifactId>powertools-validation</artifactId>
90-
</aspectLibrary>
91-
</aspectLibraries>
92-
</configuration>
93-
<executions>
94-
<execution>
95-
<goals>
96-
<goal>compile</goal>
97-
</goals>
98-
</execution>
99-
</executions>
100-
</plugin>
101-
...
102-
</plugins>
103-
</build>
104-
```
105-
106-
=== "Gradle Java 11+"
60+
=== "Gradle"
10761

10862
```groovy hl_lines="3 11"
10963
plugins {
@@ -123,27 +77,6 @@ Depending on your version of Java (either Java 1.8 or 11+), the configuration sl
12377
targetCompatibility = 11 // or higher
12478
```
12579

126-
=== "Gradle Java 1.8"
127-
128-
```groovy hl_lines="3 11"
129-
plugins {
130-
id 'java'
131-
id 'io.freefair.aspectj.post-compile-weaving' version '6.6.3'
132-
}
133-
134-
repositories {
135-
mavenCentral()
136-
}
137-
138-
dependencies {
139-
aspect 'software.amazon.lambda:powertools-validation:{{ powertools.version }}'
140-
}
141-
142-
sourceCompatibility = 1.8
143-
targetCompatibility = 1.8
144-
```
145-
146-
14780
## Validating events
14881

14982
You can validate inbound and outbound events using `@Validation` annotation.
@@ -157,10 +90,15 @@ We support JSON schema version 4, 6, 7 and 201909 (from [jmespath-jackson librar
15790
`@Validation` annotation is used to validate either inbound events or functions' response.
15891

15992
It will fail fast if an event or response doesn't conform with given JSON Schema. For most type of events a `ValidationException` will be thrown.
93+
16094
For API gateway events associated with REST APIs and HTTP APIs - `APIGatewayProxyRequestEvent` and `APIGatewayV2HTTPEvent` - the `@Validation`
16195
annotation will build and return a custom 400 / "Bad Request" response, with a body containing the validation errors. This saves you from having
16296
to catch the validation exception and map it back to a meaningful user error yourself.
16397

98+
For SQS and Kinesis events - `SQSEvent` and `KinesisEvent`- the `@Validation` annotation will add the invalid messages
99+
to the batch item failures list in the response, respectively `SQSBatchResponse` and `StreamsEventResponse`
100+
and removed from the event so that you do not process them within the handler.
101+
164102
While it is easier to specify a json schema file in the classpath (using the notation `"classpath:/path/to/schema.json"`), you can also provide a JSON String containing the schema.
165103

166104
=== "MyFunctionHandler.java"
@@ -217,31 +155,31 @@ For the following events and responses, the Validator will automatically perform
217155

218156
** Events **
219157

220-
Type of event | Class | Path to content |
221-
------------------------------------------------- | ------------------------------------------------- | -------------------------------------------------
222-
API Gateway REST | APIGatewayProxyRequestEvent | `body`
223-
API Gateway HTTP | APIGatewayV2HTTPEvent | `body`
224-
Application Load Balancer | ApplicationLoadBalancerRequestEvent | `body`
225-
Cloudformation Custom Resource | CloudFormationCustomResourceEvent | `resourceProperties`
226-
CloudWatch Logs | CloudWatchLogsEvent | `awslogs.powertools_base64_gzip(data)`
227-
EventBridge / Cloudwatch | ScheduledEvent | `detail`
228-
Kafka | KafkaEvent | `records[*][*].value`
229-
Kinesis | KinesisEvent | `Records[*].kinesis.powertools_base64(data)`
230-
Kinesis Firehose | KinesisFirehoseEvent | `Records[*].powertools_base64(data)`
231-
Kinesis Analytics from Firehose | KinesisAnalyticsFirehoseInputPreprocessingEvent | `Records[*].powertools_base64(data)`
232-
Kinesis Analytics from Streams | KinesisAnalyticsStreamsInputPreprocessingEvent | `Records[*].powertools_base64(data)`
233-
SNS | SNSEvent | `Records[*].Sns.Message`
234-
SQS | SQSEvent | `Records[*].body`
158+
| Type of event | Class | Path to content |
159+
|---------------------------------|-------------------------------------------------|----------------------------------------------|
160+
| API Gateway REST | APIGatewayProxyRequestEvent | `body` |
161+
| API Gateway HTTP | APIGatewayV2HTTPEvent | `body` |
162+
| Application Load Balancer | ApplicationLoadBalancerRequestEvent | `body` |
163+
| Cloudformation Custom Resource | CloudFormationCustomResourceEvent | `resourceProperties` |
164+
| CloudWatch Logs | CloudWatchLogsEvent | `awslogs.powertools_base64_gzip(data)` |
165+
| EventBridge / Cloudwatch | ScheduledEvent | `detail` |
166+
| Kafka | KafkaEvent | `records[*][*].value` |
167+
| Kinesis | KinesisEvent | `Records[*].kinesis.powertools_base64(data)` |
168+
| Kinesis Firehose | KinesisFirehoseEvent | `Records[*].powertools_base64(data)` |
169+
| Kinesis Analytics from Firehose | KinesisAnalyticsFirehoseInputPreprocessingEvent | `Records[*].powertools_base64(data)` |
170+
| Kinesis Analytics from Streams | KinesisAnalyticsStreamsInputPreprocessingEvent | `Records[*].powertools_base64(data)` |
171+
| SNS | SNSEvent | `Records[*].Sns.Message` |
172+
| SQS | SQSEvent | `Records[*].body` |
235173

236174
** Responses **
237175

238-
Type of response | Class | Path to content (envelope)
239-
------------------------------------------------- | ------------------------------------------------- | -------------------------------------------------
240-
API Gateway REST | APIGatewayProxyResponseEvent} | `body`
241-
API Gateway HTTP | APIGatewayV2HTTPResponse} | `body`
242-
API Gateway WebSocket | APIGatewayV2WebSocketResponse} | `body`
243-
Load Balancer | ApplicationLoadBalancerResponseEvent} | `body`
244-
Kinesis Analytics | KinesisAnalyticsInputPreprocessingResponse} | `Records[*].powertools_base64(data)``
176+
| Type of response | Class | Path to content (envelope) |
177+
|-----------------------|---------------------------------------------|---------------------------------------|
178+
| API Gateway REST | APIGatewayProxyResponseEvent} | `body` |
179+
| API Gateway HTTP | APIGatewayV2HTTPResponse} | `body` |
180+
| API Gateway WebSocket | APIGatewayV2WebSocketResponse} | `body` |
181+
| Load Balancer | ApplicationLoadBalancerResponseEvent} | `body` |
182+
| Kinesis Analytics | KinesisAnalyticsInputPreprocessingResponse} | `Records[*].powertools_base64(data)`` |
245183

246184
## Custom events and responses
247185

0 commit comments

Comments
 (0)