From f00328793a78568bc4878c88eb82b36895d30818 Mon Sep 17 00:00:00 2001 From: kawaaaas Date: Sun, 26 Oct 2025 12:14:25 +0900 Subject: [PATCH 1/2] docs: move the should i use this or Parser to the top of the validation --- docs/features/parser.md | 14 ++++++++++++++ docs/features/validation.md | 28 ++++++++++++++-------------- 2 files changed, 28 insertions(+), 14 deletions(-) diff --git a/docs/features/parser.md b/docs/features/parser.md index 59f961258f..5e6c004943 100644 --- a/docs/features/parser.md +++ b/docs/features/parser.md @@ -370,3 +370,17 @@ This also works when using `safeParse` option. ```typescript --8<-- "examples/snippets/parser/schema.ts" ``` + +## Should I use this or Validation? + +One of Powertools for AWS Lambda [tenets](../index.md#tenets) is to be progressive. This means that our utilities are designed to be incrementally adopted by customers at any stage of their serverless journey. + +For new projects, especially those using TypeScript, we recommend using the [Parser](parser.md) utility. Thanks to its integration with [Zod](http://zod.dev), it provides an expressive and type-safe way to validate and parse payloads. + +If instead you are already using JSON Schema, or simply feel more comfortable with it, the Validation utility is a great choice. It provides an opinionated thin layer on top of the popular [ajv](https://ajv.js.org) library, with built-in support for JMESPath and AWS service envelopes. + +When it comes to feature set, besides the type-safe parsing, the Parser utility also provides a rich collection of built-in schemas and envelopes for AWS services. The Validation utility, on the other hand, follows a more bring-your-own-schema approach, with built-in support for JMESPath and AWS service envelopes to help you unwrap events before validation. + +Additionally, while both utilities serve specific use cases, understanding your project requirements will help you choose the right tool for your validation needs. + +Finally, in terms of bundle size, the Validation utility is slightly heavier than the Parser utility primarily due to ajv not providing ESM builds. However, even with this, the Validation utility still clocks in at under ~100KB when minified and bundled. diff --git a/docs/features/validation.md b/docs/features/validation.md index 6095cb8287..929c4259e7 100644 --- a/docs/features/validation.md +++ b/docs/features/validation.md @@ -7,6 +7,20 @@ descrition: Utility This utility provides [JSON Schema](https://json-schema.org) validation for events and responses, including JMESPath support to unwrap events before validation. +## Should I use this or Parser? + +One of Powertools for AWS Lambda [tenets](../index.md#tenets) is to be progressive. This means that our utilities are designed to be incrementally adopted by customers at any stage of their serverless journey. + +For new projects, especially those using TypeScript, we recommend using the [Parser](parser.md) utility. Thanks to its integration with [Zod](http://zod.dev), it provides an expressive and type-safe way to validate and parse payloads. + +If instead you are already using JSON Schema, or simply feel more comfortable with it, the Validation utility is a great choice. It provides an opinionated thin layer on top of the popular [ajv](https://ajv.js.org) library, with built-in support for JMESPath and AWS service envelopes. + +When it comes to feature set, besides the type-safe parsing, the Parser utility also provides a rich collection of built-in schemas and envelopes for AWS services. The Validation utility, on the other hand, follows a more bring-your-own-schema approach, with built-in support for JMESPath and AWS service envelopes to help you unwrap events before validation. + +Additionally, while both utilities serve specific use cases, understanding your project requirements will help you choose the right tool for your validation needs. + +Finally, in terms of bundle size, the Validation utility is slightly heavier than the Parser utility primarily due to ajv not providing ESM builds. However, even with this, the Validation utility still clocks in at under ~100KB when minified and bundled. + ## Key features - Validate incoming event and response payloads @@ -215,17 +229,3 @@ This is also useful if you want to configure `ajv` with custom options like keyw ``` 1. You can pass your own `ajv` instance to any of the validation methods. This is useful if you want to configure `ajv` with custom options like keywords and more. - -## Should I use this or Parser? - -One of Powertools for AWS Lambda [tenets](../index.md#tenets) is to be progressive. This means that our utilities are designed to be incrementally adopted by customers at any stage of their serverless journey. - -For new projects, especially those using TypeScript, we recommend using the [Parser](parser.md) utility. Thanks to its integration with [Zod](http://zod.dev), it provides an expressive and type-safe way to validate and parse payloads. - -If instead you are already using JSON Schema, or simply feel more comfortable with it, the Validation utility is a great choice. It provides an opinionated thin layer on top of the popular [ajv](https://ajv.js.org) library, with built-in support for JMESPath and AWS service envelopes. - -When it comes to feature set, besides the type-safe parsing, the Parser utility also provides a rich collection of built-in schemas and envelopes for AWS services. The Validation utility, on the other hand, follows a more bring-your-own-schema approach, with built-in support for JMESPath and AWS service envelopes to help you unwrap events before validation. - -Additionally, while both utilities serve specific use cases, understanding your project requirements will help you choose the right tool for your validation needs. - -Finally, in terms of bundle size, the Validation utility is slightly heavier than the Parser utility primarily due to ajv not providing ESM builds. However, even with this, the Validation utility still clocks in at under ~100KB when minified and bundled. From 35a7ab97f2e60b1eccadc52d6394b5dd457652aa Mon Sep 17 00:00:00 2001 From: kawaaaas Date: Mon, 27 Oct 2025 19:13:47 +0900 Subject: [PATCH 2/2] docs(parser): link to validation utility instead of self --- docs/features/parser.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/features/parser.md b/docs/features/parser.md index 5e6c004943..0746103880 100644 --- a/docs/features/parser.md +++ b/docs/features/parser.md @@ -375,9 +375,9 @@ This also works when using `safeParse` option. One of Powertools for AWS Lambda [tenets](../index.md#tenets) is to be progressive. This means that our utilities are designed to be incrementally adopted by customers at any stage of their serverless journey. -For new projects, especially those using TypeScript, we recommend using the [Parser](parser.md) utility. Thanks to its integration with [Zod](http://zod.dev), it provides an expressive and type-safe way to validate and parse payloads. +For new projects, especially those using TypeScript, we recommend using the Parser utility. Thanks to its integration with [Zod](http://zod.dev), it provides an expressive and type-safe way to validate and parse payloads. -If instead you are already using JSON Schema, or simply feel more comfortable with it, the Validation utility is a great choice. It provides an opinionated thin layer on top of the popular [ajv](https://ajv.js.org) library, with built-in support for JMESPath and AWS service envelopes. +If instead you are already using JSON Schema, or simply feel more comfortable with it, the [Validation](validation.md) utility is a great choice. It provides an opinionated thin layer on top of the popular [ajv](https://ajv.js.org) library, with built-in support for JMESPath and AWS service envelopes. When it comes to feature set, besides the type-safe parsing, the Parser utility also provides a rich collection of built-in schemas and envelopes for AWS services. The Validation utility, on the other hand, follows a more bring-your-own-schema approach, with built-in support for JMESPath and AWS service envelopes to help you unwrap events before validation.