Evolving Models#

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

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 marked with 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.

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 string shape with an enum trait 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.

Boxed shapes#

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

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.