Small changes + example refactor

Author: leandrodamascena

aws_lambda_powertools/shared/functions.py

@@ -92,6 +92,23 @@ def resolve_env_var_choice(
     return choice if choice is not None else env
 
 
+def get_field_or_empty_dict(field: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+    """
+    Returns the given dictionary field if it is not empty, otherwise returns an empty dictionary.
+
+    Parameters
+    ----------
+    field: Dict[str, Any]
+        The dictionary field to be checked.
+
+    Returns
+    -------
+    Dict[str, Any]
+        The input dictionary field if it is not empty, or an empty dictionary.
+    """
+    return field or {}
+
+
 def base64_decode(value: str) -> bytes:
     try:
         logger.debug("Decoding base64 item to bytes")

aws_lambda_powertools/utilities/validation/base.py

@@ -3,7 +3,8 @@
 
 import fastjsonschema  # type: ignore
 
-from .exceptions import InvalidSchemaFormatError, SchemaValidationError
+from aws_lambda_powertools.shared.functions import get_field_or_empty_dict
+from aws_lambda_powertools.utilities.validation.exceptions import InvalidSchemaFormatError, SchemaValidationError
 
 logger = logging.getLogger(__name__)
 
@@ -38,9 +39,9 @@ def validate_data_against_schema(
         When JSON schema provided is invalid
     """
     try:
-        formats = formats or {}
-        handlers = handlers or {}
-        provider_options = provider_options or {}
+        formats = get_field_or_empty_dict(formats)
+        handlers = get_field_or_empty_dict(handlers)
+        provider_options = get_field_or_empty_dict(provider_options)
         fastjsonschema.validate(definition=schema, data=data, formats=formats, handlers=handlers, **provider_options)
     except (TypeError, AttributeError, fastjsonschema.JsonSchemaDefinitionException) as e:
         raise InvalidSchemaFormatError(f"Schema received: {schema}, Formats: {formats}. Error: {e}")

aws_lambda_powertools/utilities/validation/exceptions.py

@@ -1,6 +1,6 @@
 from typing import Any, List, Optional
 
-from ...exceptions import InvalidEnvelopeExpressionError
+from aws_lambda_powertools.exceptions import InvalidEnvelopeExpressionError
 
 
 class SchemaValidationError(Exception):

aws_lambda_powertools/utilities/validation/validator.py

@@ -1,10 +1,9 @@
 import logging
 from typing import Any, Callable, Dict, Optional, Union
 
+from aws_lambda_powertools.middleware_factory import lambda_handler_decorator
 from aws_lambda_powertools.utilities import jmespath_utils
-
-from ...middleware_factory import lambda_handler_decorator
-from .base import validate_data_against_schema
+from aws_lambda_powertools.utilities.validation.base import validate_data_against_schema
 
 logger = logging.getLogger(__name__)
 

docs/utilities/validation.md

@@ -147,10 +147,10 @@ Here is a handy table with built-in envelopes along with their JMESPath expressi
 | **`API_GATEWAY_HTTP`**            | `powertools_json(body)`                                       |
 | **`API_GATEWAY_REST`**            | `powertools_json(body)`                                       |
 | **`CLOUDWATCH_EVENTS_SCHEDULED`** | `detail`                                                      |
-| **`CLOUDWATCH_LOGS`**             | `awslogs.powertools_base64_gzip(data)                         | powertools_json(@).logEvents[*]` |
+| **`CLOUDWATCH_LOGS`**             | `awslogs.powertools_base64_gzip(data)` or `powertools_json(@).logEvents[*]` |
 | **`EVENTBRIDGE`**                 | `detail`                                                      |
 | **`KINESIS_DATA_STREAM`**         | `Records[*].kinesis.powertools_json(powertools_base64(data))` |
-| **`SNS`**                         | `Records[0].Sns.Message                                       | powertools_json(@)`              |
+| **`SNS`**                         | `Records[0].Sns.Message` or `powertools_json(@)`              |
 | **`SQS`**                         | `Records[*].powertools_json(body)`                            |
 
 ## Advanced
@@ -204,28 +204,26 @@ You can use our built-in [JMESPath functions](./jmespath_functions.md){target="_
 
 JSON schema [allows schemas to reference other schemas](https://json-schema.org/understanding-json-schema/structuring#dollarref) using the `$ref` keyword. The value of `$ref` is a URI reference, but you likely don't want to launch an HTTP request to resolve this URI. Instead, you can pass resolving functions through the `handlers` parameter:
 
-```python title="custom_reference_handlers.py"
-from aws_lambda_powertools.utilities.validation import validate
-
-SCHEMA = {
-    "ParentSchema": {
-        "type": "object",
-        "properties": {
-            "child_object": {"$ref": "testschema://ChildSchema"},
-            ...
-        },
-        ...
-    },
-    "ChildSchema": ...,
-}
+=== "custom_handlers.py"
 
-def handle_test_schema(uri):
-    schema_key = uri.split("://")[1]
-    return SCHEMA[schema_key]
+	```python hl_lines="1 7 8 11"
+    --8<-- "examples/validation/src/custom_handlers.py"
+	```
 
-test_schema_handlers = {"testschema": handle_test_schema}
+=== "custom_handlers_parent_schema"
 
-parent_event = {"child_object": {...}}
+	```python hl_lines="1 7"
+    --8<-- "examples/validation/src/custom_handlers_schema.py"
+	```
 
-validate(event=parent_event, schema=SCHEMA["ParentSchema"], handlers=test_schema_handlers)
-```
+=== "custom_handlers_child_schema"
+
+    ```python hl_lines="12"
+    --8<-- "examples/validation/src/custom_handlers_schema.py"
+    ```
+
+=== "custom_handlers_payload.json"
+
+    ```json hl_lines="2"
+    --8<-- "examples/validation/src/custom_handlers_payload.json"
+    ```

examples/validation/src/custom_handlers.py

@@ -0,0 +1,13 @@
+from custom_handlers_schema import CHILD_SCHEMA, PARENT_SCHEMA
+
+from aws_lambda_powertools.utilities.typing import LambdaContext
+from aws_lambda_powertools.utilities.validation import validator
+
+
+def get_child_schema(uri):
+    return CHILD_SCHEMA
+
+
+@validator(inbound_schema=PARENT_SCHEMA, inbound_handlers={"https": get_child_schema})
+def lambda_handler(event, context: LambdaContext) -> dict:
+    return event

examples/validation/src/custom_handlers_payload.json

@@ -0,0 +1,6 @@
+{
+    "ParentSchema":
+    {
+        "project": "powertools"
+    }
+}

examples/validation/src/custom_handlers_schema.py

@@ -0,0 +1,22 @@
+PARENT_SCHEMA = {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "$id": "https://example.com/schemas/parent.json",
+    "type": "object",
+    "properties": {
+        "ParentSchema": {
+            "$ref": "https://SCHEMA",
+        },
+    },
+}
+
+CHILD_SCHEMA = {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "$id": "https://example.com/schemas/child.json",
+    "type": "object",
+    "properties": {
+        "project": {
+            "type": "string",
+        },
+    },
+    "required": ["project"],
+}