search

json-schema-org / TSC

The repository where the JSON Schema TSC discuss and decide things
1 stars 1 forks source link

TSC Vote - The future of `format` #19

Open gregsdennis opened 4 days ago

gregsdennis commented 4 days ago

https://github.com/json-schema-org/json-schema-spec/issues/1520 describes the current state of the format keyword and proposes a change that will technically be breaking but should also align the keyword's behavior with user expectation.

In summary:

I have created PR https://github.com/json-schema-org/json-schema-spec/pull/1553 to reflect these changes, but the TSC should vote on this change.

Julian commented 4 days ago

I am -1 personally on all backwards incompatible changes, but curious to see what others' opinions are.

mwadams commented 4 days ago

I'm really struggling to choose between strict backwards compatibility (ie 👎), an explicit acknowledgement of the opt-in-to-backwards compatibility (😕 and something like Implementations MUST support annotations for unknown formats by explicit config only) or the devil-may-care 👍

Thinking about a user base which is already splintered between the "format is asserted" and "format is annotated" drafts, I am tending towards 😕 or 👍 and will tentatively vote 😕 - implementations MUST have a back-compat mode - with no real conviction!

(This leads me to some thoughts about the difference between implementation config and vocabs and whether this should all be revisited when vocabs are nailed down).

gregsdennis commented 4 days ago

Thinking about a user base which is already splintered between the "format is asserted" and "format is annotated" drafts... - @mwadams

There are no "format is asserted" drafts. format has always been an annotation.

mwadams commented 4 days ago

Thinking about a user base which is already splintered between the "format is asserted" and "format is annotated" drafts... - @mwadams

There are no "format is asserted" drafts. format has always been an annotation.

Apologies, I'm confusing the optional tests with the specs again!

jviotti commented 4 days ago

I don't like breaking changes either, but I agree with @gregsdennis that users do expect this. It is such a common source of confusion that I'm :+1: for fixing it

jdesrosiers commented 1 day ago

Considering the compatibility guarantees that we're going to make going forward from the next release, we can no longer allow a "best effort" validation for format. It has to be strict validation or there isn't compatibility between implementations let alone versions of the spec. Then in order to allow for forward compatibility of the spec, we need to raise an error on unknown formats. If unknown formats are ignored, we would never be able to add a new format because it would be incompatible with the previous spec behavior of being ignored.

So, a backward incompatible change is required no matter what we do. The validation behavior of format either needs to change as proposed or needs to be removed altogether. I think it's safe to assume no one wants to completely remove validation behavior, so what remains is whether we want to retain annotation-only behavior and what we want to call the keyword(s).

My preference is that we introduce a new keyword (format has too much baggage) and make it strict validation only. I don't think we need an annotation-only keyword. People can use x- keywords for formats they want to declare, but not validate.

So, I think this change needs to happen, but my vote is :confused: for two reasons. First, I would like us to consider a rename. It would not be a blocker for me if everyone wants to keep the name and we can always make the change and rename in a later step, so it doesn't have to hold up this change. The second change I'd like to see is that the PR still has the "best effort" language and I think that needs to be more strict.

gregsdennis commented 1 day ago

I don't think we need an annotation-only keyword.

If we introduce a new keyword, I think we still need to keep format, even if it's included as deprecated. I know that Henry in particular relies on the annotation output of this keyword, and where there's one...

jdesrosiers commented 1 day ago

If we introduce a new keyword, I think we still need to keep format, even if it's included as deprecated

Then we wouldn't be addressing the user expectation problem. I think that's something worth addressing, which means our only options are change format or replace it. Replacing format would make the upgrade path a little more complicated, but I think jettisoning format's baggage is worth it. A simple rename shouldn't be too difficult for users to deal with.

I know that Henry in particular relies on the annotation output of this keyword, and where there's one...

I probably shouldn't have said "validation-only". I expect the keyword will still emit annotations as well as validate. I'm not sure if there was a miscommunication there or not, so I wanted to clarify. The annotation output wouldn't go away, it would just be under a different name. Migrating to the new name is just part of updating for the stable release. Everyone will need to do it regardless of whether they use annotation output or not.

karenetheridge commented 50 minutes ago

+1 on this proposal as it is (barring any minor wording tweaking), using the existing keyword name.

My reading of this is that this is exactly the behaviour when using the format-assertion vocabulary in draft2020-12 with a value of true: there are a list of formats to be supported, and if any of them are not supported then the schema cannot be processed (this is different from generating a validation error, which might be unseen or turn into a true validation if below an anyOf, if/then/else or not keyword, etc).