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

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.

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.