Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add support for custom default values #1286

Merged
merged 1 commit into from
Jun 30, 2022
Merged

Conversation

mtdowling
Copy link
Member

This commit updates Smithy IDL v2 to support custom default values
rather than only default zero values.

We didn't previoulsy support custom default values because we wanted to
be able to change default values if ever needed, we wanted to avoid
information disclosure of unreleased internal members, and we wanted
clients to be able to fill in a default zero value if a required member
is missing on the wire (implying that the member transitioned from
required to default).

While default zero values are a big simplification for clients, they do
come with awkward tradeoffs. For example, the zero value of an enum was
"" (or it could have been the first enum in the shape definition but
that's problematic due to model filtering, and it requires a lot of
up-front planning from service teams). We also observed that there are
likely 1,000+ members already used in AWS that have default values that
are only captured through documentation. If we could actually model
defaults, it would be easier to catch changes to default values in
automated diff tools and discuss them in API reviews.

To address these concerns and support custom default values, we
recommend the following:

  • clients implement presence tracking and only serialize default values if
    the member is explicitly set to the default value. This allows services
    to change defaults if ever necessary.
  • servers always serialize default values unless the member is marked with
    the @internal trait. This makes it explicit as to what the server
    thinks the default value is while still preventing unintended
    information disclosure of unreleased features.
  • To avoid downtime and account for misconfigured servers that do not
    serialize required or default members, clients attempt to populate the
    member with a default zero value.

More details and specifics can be found in
defaults-and-model-evolution.md.

Enum changes:

  • Given the addition of syntax sugar for assigning values to
    defaulted structure members, this commit also allows syntactic sugar for
    assigning values to enum and intEnum shapes without the use of the
    @enumValue trait.
  • Now that there is no default zero value for enums, the @enumDefault
    trait has been removed.

Issue #, if available:

Description of changes:

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

@mtdowling mtdowling marked this pull request as ready for review June 24, 2022 23:40
@mtdowling mtdowling requested a review from a team as a code owner June 24, 2022 23:40
designs/defaults-and-model-evolution.md Show resolved Hide resolved
designs/defaults-and-model-evolution.md Outdated Show resolved Hide resolved
designs/defaults-and-model-evolution.md Outdated Show resolved Hide resolved
designs/defaults-and-model-evolution.md Outdated Show resolved Hide resolved
designs/defaults-and-model-evolution.md Outdated Show resolved Hide resolved
designs/enum-shapes.md Show resolved Hide resolved
@mtdowling mtdowling force-pushed the default-custom-value branch from 9341dea to 807e310 Compare June 28, 2022 22:22
@mtdowling mtdowling requested a review from JordonPhillips June 28, 2022 22:23
@mtdowling mtdowling force-pushed the default-custom-value branch from 807e310 to 5485700 Compare June 30, 2022 22:07
@mtdowling mtdowling requested a review from kstich June 30, 2022 22:07
This commit updates Smithy IDL v2 to support custom default values
rather than only default zero values.

We didn't previously support custom default values because we wanted to
be able to change default values if ever needed, we wanted to avoid
information disclosure of unreleased internal members, and we wanted
clients to be able to fill in a default zero value if a required member
is missing on the wire (implying that the member transitioned from
required to default).

While default zero values are a big simplification for clients, they do
come with awkward tradeoffs. For example, the zero value of an enum was
`""` (or it could have been the first enum in the shape definition but
that's problematic due to model filtering, and it requires a lot of
up-front planning from service teams). We also observed that there are
likely 1,000+ members already used in AWS that have default values that
are only captured through documentation. If we could actually model
defaults, it would be easier to catch changes to default values in
automated diff tools and discuss them in API reviews.

To address these concerns and support custom default values, we
recommend the following:

* clients implement presence tracking and only serialize default values if
  the member is explicitly set to the default value. This allows services
  to change defaults if ever necessary.
* servers always serialize default values unless the member is marked with
  the `@internal` trait. This makes it explicit as to what the server
  thinks the default value is while still preventing unintended
  information disclosure of unreleased features.
* To avoid downtime and account for misconfigured servers that do not
  serialize required or default members, clients attempt to populate the
  member with a default zero value.

More details and specifics can be found in
defaults-and-model-evolution.md.

Enum changes:
* Given the addition of syntax sugar for assigning values to
  defaulted structure members, this commit also allows syntactic sugar for
  assigning values to enum and intEnum shapes without the use of the
  `@enumValue` trait.
* Now that there is no default zero value for enums, the `@enumDefault`
  trait has been removed.
@mtdowling mtdowling force-pushed the default-custom-value branch from 5485700 to 9598892 Compare June 30, 2022 22:42
@mtdowling mtdowling merged commit e8c82ab into idl-2.0 Jun 30, 2022
@mtdowling mtdowling deleted the default-custom-value branch July 29, 2022 23:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants