What current features should be considered unstable?

[jdesrosiers]

We decided that we would move any features we consider unstable from the spec into separate documents. We still need to decide which features are not ready to be considered stable and need to move out. In the past there have been opinions ranging from "everything currently in the spec should be considered stable", to "anything that's changed recently or there's been discussion about changing should be considered unstable". I'll open with a list of features that have been discussed. If I missed any, I'll update this list when they come to light.

• The vocabulary system ($vocabularies) - Anything from updates to complete replacement have been proposed.
• $dynamicRef - This keyword has had a lot of churn and a few people have expressed hope we can replace it with something else entirely.
• $schema - It's currently ambiguous what to do with a schema that doesn't declare a dialect. We want to change that.
• $id - This keyword has had a lot of churn and there have been various discussions about more tweaks.
• Annotations - How annotations are collected was recently debated. There doesn't appear to be much if any adoption of this feature in the wild. It's been proposed to remove annotations as a prescribed implementation detail for inter-keyword communications.
• if/then/else - then and else are unique in that they depend on the evaluation result of if. There's been some talk of addressing that in some way.
• unevaluatedProperties/unevaluatedItems - Relatively new. unevalutedItems changed recently (contains). Depends on how annotations are collected which was recently debated.
• items - Recently changed.
• prefixItems - Recently added.
• $ref - Recently changed.
• propertyDependencies - Recently added (not yet released).
• contains - Added support for objects (not yet released).
• requireAllExcept - Nearly added, but stalled due to one person preferring a different solution.
• Output Formats - A new proposal has been put forward.

Edit: It's expected that implementations support unstable features, so it shouldn't be a problem for something like $dynamicRef to be unstable even though the meta-schemas depend on them.

Edit: Added "Output Formats" to the list.
Edit: Added $ref to the list.

[gregsdennis]

Let's not forget about the work we've already done in this space: spreadsheet

There's also been talk on contains about whether we should add a separate keyword in order to support objects.

[jdesrosiers]

Thanks. I was lazy and didn't want to find that link.

[gregsdennis]

It's easy when it's just in my owned spreadsheets 😉.

[jdesrosiers]

My opinions.

Unstable

• The vocabulary system ($vocabularies) - This definitely needs to change at least a little. It was explicitly released as something to get feedback on so we could iterate on the concept. I think this should be considered unstable unless our plan is to deprecate it an do something completely different. If our plan is to iterate on it, then it should be moved to an experimental feature document.
• Annotations - My main concern about this feature is that I see no evidence that anyone is actually using annotations. It's a relatively new concept and we don't have any real feedback about it. The only time annotations comes up is with implementers using it for inter-keyword communication, which I think needs to be removed from the spec as it's an implementation detail.
• propertyDependencies/requireAllExcept - These should be introduced as the first new feature proposals.
• contains - I think the object functionality should be a new keyword and introduced as a new feature proposal.
• Output Formats - We're definitely still iterating on this one.

Stable

• $schema/$id/$dynamicRef - These need some tweaks, but I think we can make those before release and call them stable. $dynamicRef I'd like to deprecate and replace at some point if we can come up with a non-dynamic replacement.
• if/then/else - There are issues here, but these keywords are very high use and we should commit to not changing them. I'd like to see them deprecated and replaced with something else, but that's for the future if at all.
• items/prefixItems - I'm still not a fan the change that got us to where we are with these keywords, but items is a very high use keyword and I think it's a bad idea to keep changing it.
• unevaluatedProperties/unevaluatedItems - As much as I dislike dynamic keywords, these are widely used and solve real problems. I'd love to at some point replace these with something non-dynamic that solves the same problem, but that's for the future.
• contains - Just the array functionality.
• Output Formats - I think we can declare the FLAG format stable.

[gregsdennis]

I'm not sure that it's entirely possible to achieve the goal of releasing a 100% stable spec and follow the "feature onboarding" process.

If we're going to say that these are stable, then we need to be perfectly clear on what their intended behavior is and know that we're taking on the risk that if they need to change, we have to follow the deprecation policy of finding a new keyword that exhibits the new behavior. I think putting keywords like $schema and $id through the deprecation process would be fairly awkward for us.

[chanced]

$dynamicRef I'd like to deprecate and replace at some point if we can come up with a non-dynamic replacement.

I'm still new to all of this and my perception is fairly naive but the nature of $dynamicRef to allow for polymorphism creates two categories of schemas. Ones that can be easily utilized for static analysis, i.e. code generation, and those that introduce a great deal of complexity by means of $dynamicRef.

As cool of a keyword as it is, it complicates things considerably.

I don't know how you could have a keyword replace it with something that could be done statically though.

[jdesrosiers]

I don't know how you could have a keyword replace it with something that could be done statically though.

It wouldn't be possible for a static keyword to do absolutely everything that a dynamic reference can do, but I think it can do the important things. The only thing you wouldn't be able to do is conditionally change where a dynamic reference resolves like in this test.

[chanced]

So you'd restrict where a $dynamicAnchor (or whatever replaces it) can reside or perhaps limit it to one per root schema?

Is polymorphism worth it at all?

[jdesrosiers]

Admittedly, I haven't thought this through yet or I would have proposed it already. But, I don't see any need to restrict where $dynamicAnchor can be. In any case, let's not get too far on this tangent in this discussion.

[gregsdennis]

On contains, we have an open issue still where Henry suggests that we revert the change to include objects because it introduces breaking changes. However, reading through the proposal issue and the associated PR, it seems we understood that it would be breaking and we were all okay-ish with it (the entire core team was involved).

Then in the reversion issue, it seems that everyone is in agreement about reverting it. That would make contains stable (although we'd probably want to tweak "how it works"), but it would mean that we'd need to eventually introduce new keywords for the properties versions of contains, minContains, and maxContains.

[gregsdennis]

Discussing at this week's OCWM, it was determined that we to want to revert contains to just covering arrays. This makes contains stable. We'll need to later introduce new keywords to cover objects.

[gregsdennis]

At this week's OWCM, we determined that the vast majority of the things in the opening comment should be considered stable as most of these things are pretty close to their 2020-12 behavior, which has been out for nearly three years now. Additional reasoning is below:

The vocabulary system ($vocabulary) ✔️

While incomplete, vocabularies are currently in use, and changing it at all without having a complete solution in mind isn't beneficial. We can develop a complete solution under a new keyword and phase out $vocabulary.

$dynamicRef ✔️

We believe that removing the bookending and initial resolution requirements are the only changes this keyword will need. This effectively separates dynamic references from regular references, giving two distinct referencing mechanics. If we find we need to change something further, we'll need to introduce a new keyword, but that seems unlikely with the coming changes.

$schema && $id ✔️

It doesn't make sense to release these as unstable as they're so fundamental to how schemas work. We need to be sure we get these right.

if/then/else ✔️

The behavior of these isn't changing, but how the spec describes their interaction could be improved.

contains ✔️

We will be reverting the "applies to objects" change, which means this is unchanged.

unevaluatedProperties / unevaluatedItems ✔️

unevaluatedItems currently has a change that respects items covered by contains. (unevaluatedProperties would be affected by this as well if contains applied to objects, but that contains change is being reverted.)

Also, the spec's description of how they work could be changed depending on how the annotations discussion goes.

items / prefixItems ✔️

These are unchanged since 2020-12. People would have to migrate from items/additionalItems to prefixItems/items when going from draft 7 to 2020-12 anyway, so there's no real change here.

propertyDependencies / requireAllExcept ❌

These are new proposals. They need to be considered unstable.

Output Formats ❌

The path forward seems to be removing this from the spec and defining it externally to allow for

• continued iteration without breaking the main spec
• additional output formats to be defined

The proposal also defines some terms that all output specs can use as a common language.

---

We didn't discuss annotations during the call, but I'll leave my opinion in another thread.

[benjagm]

Thanks for putting this together. I haven't had the time with OpenSource Summit Europe.

[gregsdennis]

Annotations - How annotations are collected was recently debated. There doesn't appear to be much if any adoption of this feature in the wild. It's been proposed to remove annotations as a prescribed implementation detail for inter-keyword communications.

Annotations are definitely being used in the wild. I know of at least one project that needs them, not counting hyper-schema (which is "for annotating JSON documents with hyperlinks"). Maybe there isn't much adoption, but there is some, and I think that warrants keeping them around.

Secondly, I personally like them as a descriptive tool to illustrate how keywords interact. Rather than completely removing this, I think it would be better to leave this mechanic in and be much more explicit that their use in this regard is illustrative and not prescriptive.

Some examples:

1. It's easy to describe how unevaluated* "see inside" sibling keywords using annotations.
2. If if produces an annotation of its evaluation result, then and else can look at that annotation and either evaluate or skip accordingly.
3. We can get rid of the "minContains overrides the evaluation result of contains" problem if minContains merely produces an annotation that contains watches for.

I think annotations can act as a good explanatory mechanic. But again, we need to be very explicit that that's what it is; it's not prescriptive.

[jdesrosiers]

I think I'm fine with this.

Maybe there isn't much adoption, but there is some, and I think that warrants keeping them around.

This makes it sound like we're considering dropping the concept of annotations entirely. I just want to be clear that I don't think anyone wants that. The question is whether annotations should be considered stable in the next release. It would still be a feature if we say "no", we would just be able to change it if we decided that was necessary. It's also important to keep in mind that annotations are something that won't be able to deprecate and replace as easily as a keyword.

Given all that, the argument that there is some adoption, but not much seems like a better argument for making it an unstable feature. I think a better argument is the same one for $id and $schema. It's such a fundamental concept that it would be awkward to release without it in stable category. So, while ideally I think we want a much higher bar of adoption before calling a feature stable, I'm ok with grandfathering this one in.

[mwadams]

I agree - I think there are two separate things going on here; conceptual annotations (which are a powerful way of explaining how interactions are supposed to work) and concrete annotations (which are, as you say, not yet a "stable" thing.)

At the moment, it's all a bit blurred.

[jdesrosiers]

I just added $ref to the list at the top as it's something that's changed since draft-07. I think this falls into the same category as $id and $schema. It's too fundamental to not consider stable.

[SorinGFS]

I think requireAllExcept is the worst keyword idea I encountered so far. I'm strongly against this 'nice to have' type of keywords, and I think json-schema should asume a simple rule for defining keywords, something like:

• is this new keyword proposal a solution that solves a problem which cannot be solved in any other way

[gregsdennis]

This opinion needs to be expressed on the issue proposing that feature. Since it's not an actual feature yet (nor is it in the proposal pipeline), it's already not in the spec, so it can't be considered "stable". This was already mentioned in the opening comment.

There is no debate on whether this keyword will be in the stable release.