Add post on the future of JSON Schema

Author: jdesrosiers

pages/posts/future-of-json-schema.md

@@ -0,0 +1,130 @@
+---
+title: "Towards a stable JSON Schema"
+date: 2022-10-21
+type: Update
+tags:
+  - Standardization
+cover: /img/posts/2022/stability/arches.webp
+authors:
+  - name: Jason Desrosiers
+    photo: /img/avatars/jasondesrosiers.jpeg
+    link: https://twitter.com/jasondesrosiers
+    byline: JSON Schema Specification Contributor
+---
+
+About this time last year, I hosted a discussion at the API Specification
+Conference about the future of JSON Schema. The most popular topic of discussion
+was, when JSON Schema is going to be "done". Of course we've heard that question
+a lot. The question stems from the "draft" label we put on your releases. The
+term "draft" has led to quite a bit of confusion for our community over the
+years, so let's take a moment to understand where it comes from.
+
+## Why is it a "draft"?
+
+JSON Schema has been loosely following the IETF standards track RFC process.
+That means our releases are in the form of an Internet Draft (I-D). That's why
+we refer to them as drafts. However, because of JSON Schema's wide use in
+production systems, it's not really possible to treat the spec like a typical
+I-D. Therefore, our use of the term "draft" is a bit of legacy artifact from
+when the IETF process made more sense for JSON Schema.
+
+This is has been a problem because when people hear "draft", they hear
+"unfinished" or "not production ready". That's not the way we treat our
+releases. Every release is expected and encouraged to be used in production.
+It's no different than OpenAPI releasing a new version. No one asks when OpenAPI
+is going to be "done". JSON Schema is just perceived differently because we call
+our releases "drafts".
+
+## The real problem
+
+But this isn't just a branding problem. When people ask when JSON Schema is
+going to be out of "draft", what they really mean is, when is JSON Schema going
+to be "stable". They want to be able to write a schema and be sure that it will
+continue to work the same way no matter how JSON Schema evolves in the future.
+They want to be able to update their dependencies and not have to update their
+schemas that were working just fine.
+
+This effects library maintainers as well. Needing to support multiple versions
+of JSON Schema with no backward or forward compatibility guarantees gets
+cumbersome and has led many maintainers to
+[drop support](https://github.com/gregsdennis/json-everything/issues/310) for
+older releases. When this happens, it can leave users with a choice to have to
+update all of their existing schemas that weren't broken or pin to a
+no-longer-supported version of the JSON Schema library they are using.
+
+## Our solution
+
+Those are the problems we're aiming to solve in the next release. Instead of
+continuing to release a new immutable and incompatible version of JSON Schema
+with each release, our next release will be a long-lived version that is stable,
+but evolving. In this case, "stable" means that there will be strict backward
+and forward compatibility requirements that must be followed for any change. It
+will be much like JavaScript in that as it evolves you can always be sure that
+your existing schemas will continue to work with any JSON Schema library you're
+using, but you take a risk using newer features because not all libraries will
+have implemented those features yet.
+
+That vision of a stable yet continuously evolving spec doesn't fit well with the
+IETF process. There are paths we considered, but nothing was proposed that we
+thought would allow us to continue to evolve the standard and get out of "draft"
+any time soon. Therefore, the first step to achieving our vision is to [decouple
+our main spec development from the IETF process](https://github.com/json-schema-org/json-schema-spec/pull/1277).
+This split allows us to pursue a new model for the main spec development that is
+more conducive to our vision.
+
+Whether or not you're a fan of the direction the JavaScript language has
+evolved, it seems clear that they've come up with an
+[effective process](https://2ality.com/2015/11/tc39-process.html) for allowing
+for continuous evolution without sacrificing interoperability and longevity.
+That's why we've chosen to base our new process on the process that is used to
+evolve the JavaScript language. In our next release, most of the keywords and
+features you use today will be declared stable and they will never change in a
+backward incompatible way again. Features and keywords we aren't comfortable
+making stable yet will become part of a new staged release process that we are
+working on defining now. The goal of the staged release process is to ensure
+that the feature gets sufficient implementation, testing, and real world vetting
+for us to be confident in declaring it stable. The process should not only make
+us more confident, but also allow us to achieve that confidence much more
+quickly.
+
+## Standards considerations
+
+Starting with the next release, the JSON Schema specification will be
+self-published on our website.
+
+One of the concerns about self-publishing is about other standards being able to
+reference the JSON Schema specification. We have received
+[feedback](https://github.com/json-schema-org/json-schema-spec/pull/1277#issuecomment-1228734352)
+from people involved in standards development that our approach would be
+acceptable for them to reference our specification in their standards based on
+our membership with the OpenJS Foundation. We don't know if _all_ standards
+bodies will come to the same conclusion, but this feedback gives us confidence
+that it isn't going to be a significant problem.
+
+Although the main specification will be self published, we are continuing to
+work through the IETF process where it makes sense. For example, we are in the
+process of registering our media types such as `application/schema+json` through
+the HTTPAPIs WG. We are also looking into standardizing reusable components such
+as Relative JSON Pointer through IETF.
+
+## The bottom line
+
+Details about the new process will be shared in a separate post when they are
+finalized, but here are some outcomes users can expect.
+
+* If you use only stable features, you are guaranteed interoperability between
+  JSON Schema libraries and you will never need to update your schemas just for
+  the sake of keeping up with new releases.
+* You can safely use new features before they are stable, as long as the
+  libraries consuming your schemas support the feature.
+* Compatibility/Interoperability guarantees will only apply to the next release
+  and beyond. You will need to update your schemas to the stable version, but
+  you won't have to continue to update them as JSON Schema evolves.
+* Custom dialects and vocabularies will continue to be central concepts for
+  customizing and extending JSON Schema.
+* Implementations only need to support the latest stable release. For example, a
+  library that supports the 2025 release will automatically support the 2023 and
+  2024 releases. The older releases will no longer need to be maintained as
+  distinct versions. However, implementations that continue to support the
+  "draft" releases would still need to maintain those as distinct versions from
+  the current stable release.