AWS CloudControl schema breaking change policy

[bagajjal]

• Is the removal of a property from an existing resource type considered a breaking change?
  • If so, what is the protocol for notifying users about such modifications?
  • If not, how can customers ensure the compatibility of their client applications in the event of schema alterations? Is there a mechanism to receive responses based on the existing schema rather than the current one? Typically, this is achieved through an API versioning approach, but I do not see AWS CloudControl API accepting an api-version input parameter. What guidance does AWS provide regarding this?

Given that AWS does not maintain a Github repository for AWS CloudControl schema, I'm looking to Pulumi for insights into property removal within a specific resource type. According to pulumi (pulumi/pulumi-aws-native#1124), there have been instances of property removals for certain resources.

[bagajjal]

@mircealam, can you please look into this issue.

[benbridts]

This probably does not completely answer your question, but you can mark properties as deprecated in the resource schema:

https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-schema.html#schema-properties-deprecatedproperties

deprecatedProperties

Resource properties that have been deprecated by the underlying service provider. These properties are still accepted in create and update operations. However they may be ignored, or converted to a consistent model on application. Deprecated properties are not guaranteed to be returned by read operations.

Type: List of JSON pointers

[bagajjal]

@benbridts, I appreciate your response. Regrettably, it doesn't provide the information I'm seeking.

@mircealam, whenever you have a moment, could you kindly provide answers to my questions? Thank you.

[bagajjal]

@mircealam, ping.

[mircealam]

in general, is the removal of a property considered a breaking change? Yes. if your contract changes and you no longer are providing you used to provide that would be considered a breaking change.

Also, in general there should be backwards compatibility and we work really hard to ensure this backwards compatibility.

picking an example from pulumi linked PR for s3 bucket and looking at schema history, I don't see the schema ever specifying an id (but it got somehow in the schema generated by pulumi) so I am not sure where the disconnect is in that specific case.

[bagajjal]

@mircealam,

Pulumi reads the cloud formation schema from https://schema.cloudformation.us-east-1.amazonaws.com/CloudformationSchema.zip and then stores the cloud formation schema in Pulumi repository. Looking at the Pulumi history, the "id" is a deprecated property.

Few follow-up questions,

1. The addition of new properties is not considered as a breaking change? Even in this case, the contract between client and AWS service changes so ideally it should be treated as a breaking change?

2. In the event of deprecating properties, is there a way to get the AWS response in the previous schema that has the deprecated properties? AWS CloudControl API doesn't take in API version so I'm not sure.

3. What is the process for deprecating properties for a resource type?