feature: Evolve an API by Adding a Field

[stevekuznetsov]

Feature Description

As a service provider exposing an API through an export,
I would like to add a new field to my API
In order to evolve the features I support

Proposed Solution

We need to make sure that:

• the API author owns the storage version
• if the storage version is newer, the field is pruned when clients request older versions
• if the storage version is older, the field is defaulted when clients request newer versions
• we need lossless round-tripping

Note: it is possible (and likely) that new fields which impact behavior for the object will cause old clients to have ill-defined behavior, as the pruned version of the schema may make two objects appear identical when their only difference is in new fields, but the client will observe behavioral differences between them.

Alternative Solutions

No response

Want to contribute?

• I would like to work on this issue.

Additional Context

Extracted from this design doc.

[stevekuznetsov]

@sttts it's not clear how, specifically, the "pruned objects appear identical but aren't" case impacts acceptance criteria for this task - can you expand on that?

[stevekuznetsov]

From discussion: if it's technically feasible, we should try to detect situations where the default behavior from a new field is not the same as the previous behavior and flag that for the API author.

[stevekuznetsov]

We need to consider the flow:

1. sever has version v1, updates to v1 (no change) but adds a backwards-compatible field
2. client has naive deserialization, drops new field
3. client does update, loses field