Tech debt: Improve documentation of Event model fields in DynamoDB parser models

[leandrodamascena]

Description

Enhance the DynamoDB parser models with field descriptions and examples using Pydantic's Field() functionality. This improvement will provide better documentation and metadata for DynamoDB event parsing, following the pattern established in PR #7100.

Motivation

Currently, the DynamoDB models lack detailed field documentation, making it harder for developers to:

• Understand field purposes without referencing external AWS documentation
• Generate rich API documentation with tools like Swagger/OpenAPI
• Create realistic test data using model factories
• Get helpful IntelliSense in IDEs

Proposed Changes

Add description and examples parameters to all fields in the following models using Field():

Files to modify:

• aws_lambda_powertools/utilities/parser/models/dynamodb.py

Reference events:
Check the sample events in tests/events/ for realistic field values:

• dynamodbStreamEvent.json
• dynamoStreamTumblingWindowEvent.json

Implementation Requirements

• ✅ Add detailed description for each field explaining its purpose and usage
• ✅ Include practical examples showing realistic AWS DynamoDB values
• ✅ Base descriptions on official AWS DynamoDB documentation
• ✅ Maintain all existing functionality, types, and validation logic
• ✅ Follow the same pattern established in EventBridge, Kinesis, and ALB models

Example Implementation

# Before
class DynamoDBStreamRecordModel(BaseModel):
    eventID: str
    eventName: Literal["INSERT", "MODIFY", "REMOVE"]
    eventVersion: float
    eventSource: Literal["aws:dynamodb"]
    awsRegion: str
    eventSourceARN: str
    dynamodb: DynamoDBStreamChangedRecordModel
    userIdentity: Optional[UserIdentity] = None

# After  
class DynamoDBStreamRecord(BaseModel):
    eventID: str = Field(
        description="A globally unique identifier for the event that was recorded in this stream record.",
        examples=[
            "1",
            "e004269649ed5a1c09ad9abf0e369fbc",
            "shardId-00000001553894847284-8dd32cb9"
        ]
    )
    eventName: str = Field(
        description="The type of data modification that was performed on the DynamoDB table.",
        examples=[
            "INSERT",
            "MODIFY", 
            "REMOVE"
        ]
    )
    eventVersion: str = Field(
        description="The version number of the stream record format.",
        examples=["1.1"]
    )
    eventSource: str = Field(
        description="The AWS service from which the stream record originated.",
        examples=["aws:dynamodb"]
    )
    awsRegion: str = Field(
        description="The AWS region in which the DynamoDB table resides.",
        examples=[
            "us-east-1",
            "us-west-2",
            "eu-west-1"
        ]
    )

Benefits

For Developers

• Better IntelliSense with field descriptions and example values
• Self-documenting code without needing external AWS documentation
• Faster development with immediate reference for acceptable values

For Documentation Tools

• Rich Swagger/OpenAPI docs via .model_json_schema()
• Automated documentation generation with comprehensive metadata
• Interactive documentation with practical examples

Getting Started

This is a great first issue for newcomers to Powertools for AWS! The task is straightforward and helps you get familiar with our codebase structure.

Need help?

We're here to support you! Feel free to:

• Ask questions in the comments
• Request guidance on implementation approach

Acknowledgment

• This request meets Powertools for AWS Lambda (Python) Tenets
• Should this be considered in other Powertools for AWS Lambda languages? i.e. Java, TypeScript, and .NET

[sreejaaryahi18]

Hi could you please assign this to me , id love to contribute

[leandrodamascena]

Hey @sreejaaryahi18 this is amazing! I'm assigning to you! Please let me know if you need any help.

[sreejaaryahi18]

Hey @leandrodamascena , I’m a bit unsure about how to test these changes locally or in a test environment and if testing is needed for this kind of update, and if needed, how would i do it?

[powertools-for-aws-oss-automation]

Warning

This issue is now closed. Please be mindful that future comments are hard for our team to see.
If you need more assistance, please either reopen the issue, or open a new issue referencing this one.
If you wish to keep having a conversation with other community members under this issue feel free to do so.