[Documentation Request] Add section on backwards compatible changes for cedar schemas

[hpmellema]

Background

Some schema changes may be backwards incompatible, for example, changing the type of a required field. However, the documentation for the cedar schema format does not discuss such backwards-incompatible changes or provide any guidance about backwards compatibility with respect to schemas.

Documentation Request

Add a section to the cedar schema format documentation detailing what changes to a cedar schema are backwards incompatible or add some guidance about backwards-incompatibility to the docs.

[bisdavid]

Thanks for reporting this, Hunter! I've got it on my list of things to do.

[bisdavid]

I don't think it's possible to put together a comprehensive list of all possible schema changes that are backwards-incompatible.

Instead, I included a warning in both the schema and policy validation topics that state the importance of reviewing your policies after making schema changes. The key is that the entities you submit to authz queries likely now adhere to the new schema. It's not the schema change that triggers the error, it's the use of entities that don't match the policies.