Use Pydantic models instead of dataclasses

[CoreOxide]

Consider using Pydantic models, at least for user facing classes.

for example, the amazingly complex ApplyGuardrailInput class becomes:

class ApplyGuardrailInput(BaseModel):
    """
    Input for applying a guardrail.
    """
    guardrail_identifier: Optional[str] = Field(
        default=None,
        description="The guardrail identifier used in the request to apply the guardrail."
    )
    guardrail_version: Optional[str] = Field(
        default=None,
        description=" The guardrail version used in the request to apply the guardrail."
    )
    source: Optional[str] = Field(
        default=None,
        description=" The source of data used in the request to apply the guardrail."
    )
    content: Optional[List[GuardrailContentBlock]] = Field(
        default=None,
        description="* The content details used in the request to apply the guardrail."
    )
    output_scope: Optional[str] = Field(
        default=None,
        description=(
            "Specifies the scope of the output that you get in the response. 
        )
    )

You get serialization and deserialization OOTB, plus complex field validations, inheritance and readability.
I'm not sure on what you base your generation, but you can check out aws_resource_validator, as a reference. It generates Pydantic models from boto3 stubs.

[stalkerg]

I think they also can use https://github.com/Fatal1ty/mashumaro which is very fast.

[CoreOxide]

I think they also can use https://github.com/Fatal1ty/mashumaro which is very fast.

Pydantic is way more popular, used in powertools and only slightly slower.

[JordonPhillips]

Pydantic doesn't give us anything over dataclasses that we actually want in the context of an AWS client.

Runtime validation isn't something we really want to do, for example. Client-side validation is a waste of time. Type hints do enough outside of runtime to give developers confidence in what they're writing, and the server will perform canonical validation. Worse, client side validation is a forwards-compatibility issue. Consider if we validated that the length of some string is no more than 20 characters. If the service updates to allow it to be 30 characters, old clients will break. (This isn't theoretical, it happened when EC2 updated instance IDs).

The serialization it provides is also not useful in this context. While it is fast, its ties to JSON are baked in. This is untenable for us because we have protocols that aren't JSON. XML, CBOR, the vnd.amazon.eventstream format, and more formats in the future need to be supported. And, importantly, they need to be changeable without changing the underlying data types so that a service can change protocols without breaking changes or support multiple protocols. pydantic-xml, for example, requires you to change the base class.

[CoreOxide]

While I might agree regarding the JSON serialization challenges, stating that client-side validation is "a waste of time" is just plain wrong. Perhaps you have used a bad validator condition and that's why you had such a bad experience with it. IMO there is no need to enforce a string maximum length, unless there is a good reason for it.

Consider an unvalidated IP string, which the downstream logic expects in IPv4 format, that suddenly changed to IPv6. You wouldn't catch this error in the payload validation stage, and will propagate the IPv6 value to inner logic layer, possibly causing undefined behavior in your application.

[stalkerg]

@CoreOxide as I understand they expect what a such task will be solved on source generation level. It works until they generate data from one schema source. Unfortunately, we already have multiple S3 providers.

[JordonPhillips]

client-side validation is "a waste of time" is just plain wrong

Validation should take place at the boundary of your application. For a web service, this means that validation must always take place upon receipt of the request.

An HTTP request can come from anywhere. While a well-supported client is usually the easiest way to make a request, there is nothing stopping somebody from sending a request via curl or otherwise using their own hand-written client. The server has absolutely no idea where that request came from. It can guess if the user-agent or some other header makes a declaration, but user-agents are just headers, and anybody can set a header to whatever they want.

Since the server cannot know where the request came from, it cannot trust that the request was validated before it was sent. Therefore, it must validate the request itself or be exposed to invalid data and/or malicious actors.

Since the server is always performing validation, the only thing you get by also doing client-side validation is a slightly faster time to error. Meanwhile, every single request that is valid has to go through the time-consuming process of being validated twice.

Setting that issue aside, there is also the matter of forwards-compatibility I previously mentioned. The second an interface update is pushed to a server, every client that was not simultaneously updated is now out of date. This is generally fine since services should not make breaking interface changes without some sort of version bump. Loosening validation on the server is not a breaking change unless the client is also doing validation. Version bumps are expensive, so having to do one every time you want to relax validation is unacceptable.

A semantic change of a string from ipv4 always to ipv6 without opt-in would be a breaking change that should be flagged in design review.

[JordonPhillips]

The examples on aws_resource_validator show it being used for constructing tests. In this scenario I can see the value in having local validation since the server is not involved. I don't think that use case justifies changing our default strategy and adding a dependency though.

Now you could customize the code generator to produce pydantic models anyway. We might need to clean up the hooks a bit, but in principle it shouldn't be a problem so long as the constructor looks the same and the serialize/deserialize methods persist

[CoreOxide]

Since the server cannot know where the request came from, it cannot trust that the request was validated before it was sent. Therefore, it must validate the request itself or be exposed to invalid data and/or malicious actors.

Client side validation happens usually on the response from the server, not on the payload you prepare to send to the server. The recipient is always the validator.

The examples on aws_resource_validator show it being used for constructing tests.

It shows interation with the dynamodb client, where the response is immediately converted into a Pydantic, pre generated model.

import boto3

from aws_resource_validator.pydantic_models.dynamodb.dynamodb_classes import ListTablesOutput

dynamodb = boto3.client('dynamodb')

def list_dynamo_tables() -> List[str]:
    return ListTablesOutput(**dynamodb.list_tables()).TableNames


if __name__ == "__main__":
    tables: List[str] = list_dynamo_tables()
    print("DynamoDB Tables:", tables)

[JordonPhillips]

Validating responses from the service is not free from forwards-compatibility issues. We don't want to make tools that make it harder for services to make valid changes.

Also consider that the trust model for a client is different than that of a server, particularly in the context of Smithy.

Model-first development as enabled by Smithy and practiced by Amazon already provides assurance that the responses will match the model, as the tooling used to produce those responses is generated from the model (the server too, not just the client). The client can generally trust that responses from a trusted server will be valid because it knows that the service it is connected to is doing validation. Regressions should be rare because there are automated checks to determine if a change is backwards compatible or not (e.g. smithy-diff) on top of manual review. Deliberate changes that knowingly can cause impact are accompanied by migration campaigns, such as in the EC2 instance ID lengthening case.

There are of course cases of regressions happening. In these cases the service teams generally have alarms to help detect problems and of course there's various means of reporting the issue. Typically the service team will roll back breaking changes or otherwise fix the issue.

If you don't trust the service, you might still want to do some sort of validation. But if you don't trust the service, why would you trust validation that they generate? Better to validate your requirements yourself, so you can be sure they match your needs and that they don't change until you're ready.

Take your IP address scenario, for example. On Day 1 a service is released that provides IPv4 addresses. You then write some tooling to use those addresses, which is written such that it can ONLY work with IPv4. You rely on the validation built into the client that enforces that it's specifically IPv4. On Day 2 the service makes a change that allows it to return IPv6 addresses in the same response field. If you update your client before you ever receive an IPv6 address, then your system will fail just as if it never had any validation in the first place. Maybe you do receive an IPv6 while you're still doing IPv4 validation, but you can't rely on the outcome of a race.

[CoreOxide]

It's not a matter of trust, it's a matter of taking care of yourself. I validate responses because sometimes unexpected things happen. you also should strive to fail fast, and not propagate invalid data through your application, hoping that something will fail eventually.

in any case, if i can sum up what you're saying - you only want type hints and not validation, as dataclasses only provide type hints. for example, this code works perfectly fine:

from dataclasses import dataclass

@dataclass
class SomeClass:
    some_string: str

my_vars = SomeClass(some_string=122)
print(my_vars.some_string)