Why our SDKs don't perform runtime request validation

The SDKs we generate validate the general shape of requests at compile-time using the language’s type system and leave constraints that aren’t ergonomically supported for the API to validate (e.g. string length, number of items in a collection, and so on).

While forgoing full runtime request validation may seem counterintuitive, we’ve found the benefits outweigh the cons:

• Code size: It’s critical to keep code size low for frontend use-cases and edge functions. Runtime request validation requires embedding far more information in the SDK, especially in languages like TypeScript where forgoing validation keeps type information in the type system only.

• Performance: Runtime request validation negatively impacts performance, especially on low-powered devices. For constraints that can’t be handled by a language’s type system it’s better to let your API validate incoming data. Most requests contain valid data, so client-side validation adds overhead to most requests with no tangible benefit. Validating only on the server optimizes for the most common outcome.

• Forward compatibility: If constraints are loosened on the API side, then the runtime request validation of older SDK versions will be outdated and will reject valid requests until the SDK is upgraded, which may not even be possible to guarantee if it requires an end-user to update something like a mobile app.

• Undocumented values: Without runtime request validation, the user can pretty easily bypass the type system in dynamically typed languages and send requests that don’t match the expected shape, which is useful when there are bugs in the OpenAPI spec or when there’s undocumented or not-yet-in-the-spec API functionality.