Skip to content

Feature request: Improved documentation of Event model fields using description and examples #5475

@xkortex

Description

@xkortex

Use case

It would be convenient if models for well-known types such as EventBridgeModel, which map to well-documented objects in the AWS API, to use Field(description=..., examples =...). This serves as a really useful refresher for acceptable values, and adds this metadata to .model_schema_json() (useful for swagger docs, model factories and the like). To show you what I mean, I whipped up this class really quick before realizing ALP had a EventBridgeModel class already.

BaseModel classes with description and examples
class AWSEvent(BaseModel):
    model_config = ConfigDict(extra='allow', alias_generator=snake_to_kebab)

    # version: str # Currently 0 (zero) for all events, there is no need to allocate it at this time.
    id: str = Field(
        description="A Version 4 UUID generated for every event.",
        examples=['17793124-05d4-b198-2fde-7ededc63b103'],
    )
    account: str = Field(
        description="The 12-digit AWS account ID of the owner of the service emitting the event.",
        examples=['111122223333'],
    )
    detail_type: str = Field(
        alias='detail-type',
        serialization_alias='detail-type',
        description="Identifies the type of event",
        examples=['Scheduled Event', 'Object Created'],
    )
    source: str = Field(
        description="Identifies the service that generated the event",
        examples=['aws.s3', 'aws.events'],
    )
    time: datetime = Field(description="The time the event occurred.", examples=['2006-01-02T15:04:05Z'])
    region: str = Field(description="Identifies the AWS Region the event originated.", examples=['us-east-1'])
    resources: list[str] = Field(
        description="A JSON array that contains the Amazon Resource Name (ARN) "
        "of service(s) that generated the event",
        examples=['arn:aws:s3:::amzn-s3-demo-bucket1', 'arn:aws:events:us-east-1:123456789012:rule/SampleRule'],
    )

    detail: dict[str, Nested] = Field(
        description="A JSON object that contains information about the event. "
        "The service generating the event determines the content of this field."
    )


class S3ObjectEvent(AWSEvent):
    detail_type: str = Field(
        alias='detail-type',
        pattern='Object .+',
        examples=[
            'Object Created',
            'Object Deleted',
            'Object Restore Initiated',
            'Object Restore Completed',
            'Object Restore Expired',
            'Object Tags Added',
            'Object Tags Deleted',
            'Object ACL Updated',
            'Object Storage Class Changed',
            'Object Access Tier Changed',
        ],
    )
    source: Literal['aws.s3']


class ScheduledEvent(AWSEvent):
    detail_type: str = Field(alias='detail-type', pattern='Scheduled Event', examples=['Scheduled Event'])
    source: Literal['aws.events']
I mostly pulled these right from AWS documentation pages [like this](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ev-events.html). It might even be able to be autogenerated from botocore, not sure about that rabbit hole.

See also
#5476

Solution/User Experience

Basically the example above but adapted for how you have EventBridgeModel and its children structured.

Alternative solutions

No response

Acknowledgment

Sub-issues

Metadata

Metadata

Labels

Projects

Status

Coming soon

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions