Evolving Models#

This guide describes how to evolve Smithy models without breaking your customers.

Note

This page does not include every possible backwards or forwards compatible change. For traits, the best place to look for compatibility is the specification for the trait or its model definition as defined by the breaking changes property.

Updating services#

The following changes to operation shapes are backward-compatible:

  1. Adding operations.
  2. Adding resources.

The following changes are not backward-compatible:

  1. Removing a resource or operation.
  2. Renaming a shape that was already part of the service.

Updating operations#

The following changes to operation shapes are backward-compatible:

  1. Adding a new error shape if the error shape is only encountered under new conditions that previously released clients/tools will not encounter.

The following changes are not backward-compatible:

  1. Changing the shape targeted by the input or output of an operation. For example, it is not backward compatible to change an operation's input or output from targeting smithy.api#Unit to then later target a different shape.
  2. Removing or renaming a resource or operation.
  3. Removing an operation from a service or resource.
  4. Removing a resource from a service.
  5. Changing an operation from referencing an input/output structure to no longer referencing an input/output structure.
  6. Renaming an error that is referenced by an operation.
  7. The addition, removal, or modification of traits applied to an operation or members of the input/output of an operation MAY result in a breaking change if it changes the wire representation of an operation or breaks behavior that was previously relied upon by tooling.

Updating structures#

The following changes to structure shapes are backward-compatible:

  1. Adding new optional members to a structure.

  2. Removing the required trait from a structure member and replacing it with the default trait (assuming the member was not marked with the clientOptional trait).

  3. Removing the required trait from a structure member when the structure is marked with the input trait.

  4. Removing the required trait from a structure member that is marked with the clientOptional trait.

  5. Adding the required trait to a member of a structure if the member is marked as clientOptional or the structure is marked with the input trait.

  6. Adding or removing the input trait from a structure is generally backward incompatible.

    Note

    Many code generators automatically create dedicated synthetic input structures for each operation and treat the synthetic structure as if it is marked with the @input trait. Code generators that do this MAY ignore backward incompatible changes around adding or removing the @input trait.

The following changes to a structure are not backward-compatible:

  1. Renaming a member.
  2. Removing a member.
  3. Changing the shape targeted by a member.
  4. Adding the required trait to a member that was not previously marked with the clientOptional trait.
  5. Removing the default trait from a member.
  6. Adding the default trait to a member that was not previously marked with the required trait.
  7. Adding the default trait to a member that was previously marked with the clientOptional trait.
  8. Removing the clientOptional trait from a member that is marked as required.
  9. Adding or updating constraint traits that further restricts the allowed values of a member.

Booleans and API evolution#

A boolean shape is often used to model state flags; however, consider whether or not the state of a resource is actually binary. If other states can be added in the future, it is often better to use a enum shape or a union shape.

Updating unions#

The following changes to union shapes are backward-compatible:

  1. Adding a new member to a union. Unions in Smithy are considered "open"; it is a backward-compatible change to add new members to a union. Smithy clients SHOULD anticipate and account for receiving unknown members for a union in a response from a service at runtime. Clients SHOULD NOT fail when receiving unknown members from a service.

The following changes are backward-incompatible:

  1. Renaming a union member.
  2. Removing a union member.
  3. Changing the shape targeted by a union member.

Sparse lists and maps#

The sparse trait is used to influence code generation in various programming languages. It is a backward-incompatible change for the sparse trait to be added or removed from a shape because it will affect types generated by tooling that uses Smithy models.

Updating traits#

The following changes to trait definitions are backward compatible:

  1. Relaxing the selector of a trait.
  2. Removing a trait from the conflicts list.
  3. Removing the structurallyExclusive property.
  4. Marking a trait as deprecated.

Using Smithy Diff#

Smithy Diff is a tool used to compare two Smithy models to check for backward compatibility issues. Smithy Diff can be run via a Java library or via the Smithy CLI.