search

SpaceApi / schema

SpaceAPI JSON schema files.
24 stars 14 forks source link

v14: Make state.open nullable again #91

Closed rnestler closed 3 years ago

rnestler commented 3 years ago

This is for better backwards compatibility with v0.13.

Fixes #86

rnestler commented 3 years ago

Only problem i have with that situation is that we're changing an agreed "standard", doesn't feel nice/right.

IMO fixing bugs in the agreed "standard" should be allowed. The question is more what exactly counts as bug fixing. I guess fixing typos in the documentation of the schema we'd all agree is OK. Renaming a key probably not (even if it has a typo in the key name).

I'd argue that the intended change we wanted to do in v14 is to remove state.open as a required field so that there is no need to set it to null. But we probably didn't want to make life for users hard by having contradicting requirements in v0.13 and v14, since we explicitly want to allow to support multiple versions of the API at the same time.

So I consider this a bug fix to change it the way we intended it to be.

rnestler commented 3 years ago

How can we make sure that this is a one time thing and not a broken window situation?

I agree we shouldn't make changes to old versions of the standard a regular thing. I would propose the following limitations:

gidsi commented 3 years ago

How can we make sure that this is a one time thing and not a broken window situation?

I agree we shouldn't make changes to old versions of the standard a regular thing. I would propose the following limitations:

* Only changing of the latest published standard is allowed. (So no changing of v0.13 at this point)

* Only changes which fix bugs which make the life of users hard for no apparent reason

* Fixes must be fully backward compatible (All valid documents before must be valid after the change)

But they are not backward compatible at this point, thats my issue.

Generated types and things like this are going to break too (which im fine with, but we shouldnt do it again).

But i dont have any idea how we wont get in the situation again beside "work better"

rnestler commented 3 years ago

But i dont have any idea how we wont get in the situation again beside "work better"

I guess we should actually update a reference implementation even for not yet published schema versions. That way we would notice practical problems with the schema immediately.