Feature request: standalone validate function for JSON Schema validation #3607
Description
Use case
To start implementing the new Validation utility, we should implement a validate standalone function, which is the core of the Validation utility and is a thin layer around ajv, the JSON Schema validation module we're taking a dependency on.
Note
This issue is open for contributions 🎉 If you're interested in contributing, please leave a comment below so that a maintainer can assign it to you. If you have questions or need clarifications, please don't hesitate to ask.
Solution/User Experience
A longer version of this can be found in the unpublished documentation page about the feature, that can be found at docs/utilities/validation.md.
The validate function should be a synchronous function that takes a single params object and acts as an assertion function which - as the name suggests - asserts that the event is of a certain type, or throws a SchemaValidationError error otherwise.
The params object should accept the following items:
- a
payload- this is the unknown object we want to validate - a
schema- this is the JSON Schema we'll use to validate - an optional
envelopeparameter of typestring(more on this later) - an optional
formatsoptional parameter to pass custom formats - an optional
externalRefsarray of schemas that can be used to supply external references to the main schema - an optional
ajvparameter that customers can use to provide their own instance - this is useful when wanting to use a different JSON Schema version/draft
The validate function should be generic and accept a type which is the type being asserted, if no type is supplied we'll default to unknown.
In terms of implementation, the validate function will rely on ajv and instantiate its own instance (new Ajv()) whenever one is not provided in the params object. When creating a new Ajv instance, we'll pass down any of the formats and externalRefs present in the params to the Ajv constructor.
If instead an ajv instance is already supplied, we'll add the formats and externalRefs using the methods addFormat() and addSchema().
Next, the validate function should call the compile() method on the ajv instance using the schema provided.
In case an envelope is passed, the function will use the search function from the @aws-lambda-powertools/jmespath module (already installed as dependency) to extract a subset of the payload using the envelope expression. The resulting object should be the one actually being validated.
Finally, it should validate the data and throw a SchemaValidationError error if the validation fails. This is a custom error that should be defined and exported for customers to use. If the validation is successful, the function should return the validated data.
As part of the implementation the implementer should also write unit tests to cover 100% of the files, lines, branches of the code added as part of this issue. All the dependencies needed should already be present in the workspace, ideally the implementation should follow existing project conventions as much as possible.
Alternative solutions
N/AAcknowledgment
- This feature request meets Powertools for AWS Lambda (TypeScript) Tenets
- Should this be considered in other Powertools for AWS Lambda languages? i.e. Python, Java, and .NET
Future readers
Please react with 👍 and your use case to help us understand customer demand.