Evolving Models¶

Updating operations¶

The following changes to operation shapes are backward-compatible:

1. Changing an operation from no input to referencing a structure that contains all optional members.
2. Changing an operation from no output to referencing a structure.
3. 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. Removing or renaming a resource or operation.
2. Removing an operation from a service or resource.
3. Removing a resource from a service.
4. Changing the parent of a resource.
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. Changing a structure member from required trait to optional. The required trait SHOULD only be used for validation purposes; code generators SHOULD NOT consider whether or not a structure member is required when generating data structures.

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