Loïc Lefèvre

How Oracle is Bridging the Gap Between JSON Schema and Relational Databases





# How RxDB embraces JSON Schema to build its NoSQL Database

[RxDB](https://rxdb.info/) is a NoSQL database designed primarily for client-side JavaScript applications, focusing on the [offline-first approach](https://rxdb.info/offline-first.html), multi-tab operations, and data replication. It seamlessly integrates with modern web and mobile app frameworks, supports various storage backends, and provides a plugin-based architecture to handle encryption, compression, type generation, and more.

One of RxDB's standout architectural choices is its reliance on JSON Schema to define data models for documents in collections. Instead of inventing a custom schema language, RxDB adopts a standard that is already well-established in the broader JavaScript community. By doing so, RxDB solves several major hurdles that often arise when developers are introduced to new databases:

- **Familiarity**: Most JavaScript developers have already encountered JSON Schema, either via OpenAPI or other tooling. Thus, they can quickly understand and adopt RxDB's schemas without investing time in learning a new schema language.

- **Tooling ecosystem**: JSON Schema boasts a robust set of libraries, validators, and code generators. RxDB leverages these rather than maintaining its own schema validation library, giving teams the freedom to pick what works best for them.

- **Long-term maintainability**: Because JSON Schema is recognized as a standard, future updates and ecosystem support are more reliable than a custom, one-off solution.


By building on JSON Schema, RxDB has a foundation that makes schema design, data validation, and typing straightforward, making it easier for developers to build robust, safe applications in production.


<center>
    <a href="https://rxdb.info/">
        <img src="https://rxdb.info/files/logo/rxdb_javascript_database.svg" alt="JavaScript Database" width="220" />
    </a>
</center>

## How RxDB uses JSON Schema


While RxDB adopts the JSON Schema Core and Validation specifications, it also extends it to introduce RxDB-specific functionality. Like in other NoSQL databases, you can manually define which fields to encrypt, which ones to index, and how to interpret specific fields for queries. RxDB enables these configurations as custom JSON Schema keywords:

- `primaryKey`: Specifies which field in the document serves as the primary key.
- `indexes`: Defines which fields (or combination of fields) RxDB indexes. You can have single-field indexes or compound indexes.
- `version`: Indicates the version of the schema. Whenever you change your schema, you must increment this version so RxDB can handle migrations or other adjustments. This is important because data migration on a client-side database can be tricky when you have many clients out there that update your app at different points in time.
- `encryption`: Specifies which fields should be stored in an encrypted form. This is useful for sensitive data that you do not want to store in plaintext on the client's device.
- `keyCompression`: Can be set to `true` to enable the key-compression plugin.

RxDB supports a [compression plugin](https://rxdb.info/key-compression.html) that uses a "compression table." This is essentially a lookup table derived from your JSON Schema which assigns shorter keys or transforms fields so that the stored data becomes more compact. By analyzing the schema, the plugin understands which fields appear repeatedly and can replace them with shorter tokens. Remarkably, RxDB can still query the data in its compressed form. This leads to performance improvements, especially in environments where local storage space is limited.

Below is a sample RxDB schema that demonstrates how standard JSON Schema vocabularies combine with RxDB's custom extensions:

```ts
const mySchema = {
    primaryKey: 'id',
    type: 'object',
    properties: {
        id: {
            type: 'string',
            maxLength: 100
        },
        name: {
            type: 'string'
        },
        birthdate: {
            type: 'string',
            format: 'date'
        },
        secret: {
            type: 'string'
        }
    },
    additionalProperties: false,
    required: ['name', 'birthdate', 'id'],
    // RxDB specific fields:
    primaryKey: 'id',
    version: 0,
    keyCompression: true,
    indexes: [
        'name', // single-field index
        ['name', 'birthdate'] // compound index
    ],
    encrypted: ['secret']
}
```

## Restrictions

Although RxDB aims to remain fully spec compliant with JSON Schema, it does impose some extra restrictions:

The schema requires top-level field names to match the regex `^[a-zA-Z][a-zA-Z0-9_]*[a-zA-Z0-9]$`. This rule ensures that property names are valid JavaScript identifiers.

At the top level of the schema, `additionalProperties` must be set to `false`. This prevents silently introducing new fields that could potentially clash with built-in RxDocument methods (like `.toJSON()`). By making you list out each property, RxDB ensures you can't unknowingly overwrite or conflict with standard methods.

RxDB does not allow `$ref` to other files or external schema fragments or `$dynamicRef`. The goal is to keep schema loading fast and self-contained. If a schema needs to be composed of multiple parts, you must combine them at build time or otherwise ensure they are merged before passing them to RxDB at runtime. This approach also prevents any network calls or asynchronous fetches that could slow down your application's startup.


## Inferring Document Types with TypeScript

JSON Schema is not just for validation and structural guarantees, it can also help generate or infer TypeScript types. In many projects, developers rely on tools like [json-schema-to-typescript](https://github.com/bcherny/json-schema-to-typescript) to produce `.d.ts` files or interface definitions from schema files at build time. However, that requires a separate build step, which slows down your workflow.

To improve developer experience, RxDB offers a [built-in way](https://rxdb.info/tutorials/typescript.html) to infer the document's TypeScript type from the schema during runtime. This is helpful because you get immediate feedback in your IDE: As soon as you update the schema, TypeScript picks up the changes. You'll see type errors in your code if you attempt to use fields that are no longer valid or if you forget to include newly required fields.

Below is an example on how to infer the TypeScript type of a document from its JSON-schema:

```ts
import {
    toTypedRxJsonSchema,
    ExtractDocumentTypeFromTypedRxJsonSchema,
    RxJsonSchema,
    RxCollection
} from 'rxdb';

const heroSchemaLiteral = {
    title: 'hero schema',
    description: 'describes a human being',
    version: 0,
    keyCompression: true,
    primaryKey: 'passportId',
    type: 'object',
    properties: {
        passportId: {
            type: 'string',
            maxLength: 100
        },
        /* ...other fields... */
    },
    required: ['name', 'birthdate', 'passportId'],
    indexes: ['name', 'birthdate']
} as const;

// Convert the literal object to a typed schema
const schemaTyped = toTypedRxJsonSchema(heroSchemaLiteral);

// Extract the document type from the typed schema
type HeroDocType = ExtractDocumentTypeFromTypedRxJsonSchema<typeof schemaTyped>;

// Create a typed RxJsonSchema
const heroSchema: RxJsonSchema<HeroDocType> = heroSchemaLiteral;

// Example usage: create a typed collection
const myCollection: RxCollection<HeroDocType> = db.heroes;
```


## Different JSON Schema Validators

In order to validate whether a given document complies with the schema, RxDB uses pluggable validators. Historically, RxDB supports/supported:

- [ajv](https://ajv.js.org/)
- [z-schema](https://github.com/zaggino/z-schema)
- [is-my-json-valid](https://github.com/mafintosh/is-my-json-valid) (now deprecated in RxDB because it incorrectly handles large and decimal numbers)

No single validator is perfect; each has its trade-offs in performance, build size, and correctness edge cases. Some libraries rely on `eval()` or `new Function`, which can break in strict Content-Security-Policy (CSP) environments. Others have issues with large integers. RxDB encourages you to pick a validator that matches your app's needs and environment constraints.

Note that RxDB itself does not define a specific JSON Schema dialect. Instead, the range of supported dialects is determined by the JSON Schema validation plugin in use.

One important consideration is that each validator has a unique format for its **error messages**. If your application inspects validation errors and makes decisions (e.g., showing descriptive warnings to the user), be aware that switching validators later can require extensive code changes. In theory this is solved by the JSON Schema specification by the use of the [Standard Output](https://json-schema.org/draft/2020-12/json-schema-core#name-output-formatting) format, but this is not implemented in the listed schema validators.

## Performance Comparison of Validators

Performance is a critical factor in deciding whether to validate documents at runtime, especially in production environments. The following tables illustrate a basic comparison of initialization time (time-to-first-insert) and bulk insertion speed for different validators on two RxDB storages

The RxDB team ran performance benchmarks using two storage options on an Ubuntu 24.04 machine with Chrome version `131.0.6778.85`. The testing machine has 32 core `13th Gen Intel(R) Core(TM) i9-13900HX` CPU.

Dexie Storage (based on IndexedDB in the browser):

| **Dexie Storage** | Time to First insert | Insert 3000 documents |
| ----------------- | :------------------: | --------------------: |
| no validator      |        68 ms         |                213 ms |
| ajv               |        67 ms         |                216 ms |
| z-schema          |        71 ms         |                230 ms |

On Dexie Storage, the difference in time-to-first-insert is negligible, and inserting thousands of documents also shows only a modest increase in latency when using a validator. The overall overhead for 3000 inserts remains fairly small (a difference of tens of milliseconds).


Memory Storage: stores everything in memory for extremely fast reads and writes, with no persistence by default. Often used with the RxDB memory-mapped plugin that processes data in memory an later persists to disc in background:

| **Memory Storage** | Time to First insert | Insert 3000 documents |
| ------------------ | :------------------: | --------------------: |
| no validator       |       1.15 ms        |                0.8 ms |
| ajv                |       3.05 ms        |                2.7 ms |
| z-schema           |        0.9 ms        |                 18 ms |

For the Memory Storage, you see a wider variance. Although z-schema has a faster startup (time-to-first-insert) than ajv, it becomes much slower at continuous inserts (18 ms vs. 2.7 ms). This discrepancy might not matter if you rarely insert documents, but it can become significant if you have high-volume write operations.

Including a validator library also increases your JavaScript bundle size. Here's how it breaks down (minified + gzip):

| **Build Size** (minified+gzip) | Build Size (dexie) | Build Size (memory) |
| ------------------------------ | :----------------: | ------------------: |
| no validator                   |      73103 B       |             39976 B |
| ajv                            |      106135 B      |             72773 B |
| z-schema                       |      125186 B      |             91882 B |

Including a validator can substantially increase your final bundle size. For large single-page applications, an extra 30-50 KB or more of JavaScript could influence startup times, especially for users on slow networks.



## Should JSON Schema Validation Be Used in Production?

Many teams limit JSON Schema validation to development builds to avoid performance overhead in production. However, if your application deals with highly sensitive or mission-critical data, keeping validation enabled ensures data integrity and can prevent costly errors, despite the added CPU and bundle-size costs. Ultimately, the choice depends on your performance targets and  the risk of invalid data.

### Running the Validation in a WebWorker

If you must keep validation enabled in production but you have to ensure that your UI does not lack during validation, you might consider the [RxDB WebWorker plugin](https://rxdb.info/rx-storage-worker.html). This plugin runs the RxDB storage & validation in a separate Web Worker, offloading the main UI thread. While it won't reduce the absolute time spent on validation, it can help maintain a smooth UI by preventing blocking operations on the main thread.


## Learnings

Over time, RxDB has evolved its usage of JSON Schema, learning from real production experiences and feedback from the community. Here are some key takeaways:

- Avoid inlined `required` fields: In older JSON Schema dialects such as Draft 3, it was acceptable to define `"required": true` directly inside the property definition. However, more recent dialects expect required to be declared as an `array` at the parent object level. If you're using a validator based on newer specs, place your required fields in the parent-level array. If you intentionally stick to Draft 3, inlined required is still valid, but it may cause confusion if you switch to a newer validator or tool later on.

- Keep Custom Fields at the Top Level: Originally, RxDB allowed custom definitions (`index`, `encrypted`, etc.) to appear deeply nested. This caused performance hits because the library had to traverse large schema objects to find them. By placing these fields at the top level, RxDB can parse and apply them much faster, improving startup times.

- Error messages are not standardized: Each validator produces a different structure for error messages. If your app logic inspects these errors, you risk partial or complete rewrites if you ever switch validators. Decide early on which validator meets your needs and plan on sticking with it long-term. This might be solved in the future when all validators support the [standard output formatting](https://json-schema.org/draft/2020-12/json-schema-core#name-output-formatting).


## Follow Up

Using JSON Schema in RxDB has greatly simplified data definitions, tooling integration, and type inference. Although some restrictions and performance considerations come into play, the overall developer experience is significantly improved by using a well-known standard rather than reinventing the wheel.

For more information on RxDB, including further details on schema extensions and advanced plugins, check out the [official RxDB documentation](https://rxdb.info/quickstart.html).


Daniel Meyer

How RxDB embraces JSON Schema to build its NoSQL Database


Last year, JSON Schema proudly participated in Google Summer of Code (GSoC) 2024, a global program designed to bring fresh talent into open-source communities. Through this initiative, we tackled some of our most exciting projects yet, creating opportunities for contributors to make meaningful impacts while gaining valuable experience.

We’re thrilled to share the highlights of this journey and the incredible work our contributors and mentors achieved together.

## A Unique Start: Setting the Stage for Success
For JSON Schema, GSoC 2024 wasn’t just about welcoming contributors but about setting a high standard. Before selection, applicants underwent a qualification test, allowing us to assess technical skills and alignment with project goals. This ensured each participant had the tools and mindset to thrive.

Here’s what stood out in our journey:

* 8 projects completed across diverse aspects of JSON Schema.
* A record number of applicants, with a community brimming with enthusiasm.
* Returning mentors and contributors, bringing experience and new perspectives.

## Transformative Projects and Talent Contributors

### 1. Bowtie-Trend: Long-Term Reporting With Bowtie

* Contributor: [Adwait Godbole](https://github.com/adwait-godbole)
* Mentors: [Julian Berman](https://github.com/Julian), [Agnivesh Chaubey](https://github.com/AgniveshChaubey)
* [Idea on GitHub](https://github.com/json-schema-org/community/issues/607)

The project aims to enhance [Bowtie](https://github.com/bowtie-json-schema/bowtie), a meta-validator for the JSON Schema specification that coordinates the execution of validator implementations and reports their results. While Bowtie already generates compliance reports accessible [here](https://bowtie.report), this project introduces a mechanism to track compliance metrics over time. The goal is to enable graphing and querying of how test results evolve as implementations fix bugs or new tests are added. Key outcomes include a new bowtie trend command to aggregate results into trend reports and a dedicated webpage displaying graphs of failed tests over time, providing deeper insights into long-term compliance trends.

### 2. Bowtie-Perf: A Performance Tester for JSON Schema Implementations

* Contributor: [Dhruv Singh](https://github.com/sudo-jarvis)
* Mentors: [Julian Berman](https://github.com/Julian), [Agnivesh Chaubey](https://github.com/AgniveshChaubey)
* [Idea on Github](https://github.com/json-schema-org/community/issues/605)

The project enhances [Bowtie](https://github.com/bowtie-json-schema/bowtie), a meta-validator of the JSON Schema specification. Bowtie provides universal access to JSON Schema implementations, enabling users to validate instances and identify bugs or gaps in functionality. Currently, Bowtie supports validating instances against schemas and comparing implementations based on correctness. This project expands its capabilities by developing a performance tester integrated within Bowtie. This addition provides a critical dimension for performance optimization and enables more comprehensive comparisons across JSON Schema implementations.

### 3. Setting up the CI/CD Pipeline for the JSON Schema Website

* Contributor: [Alok Gupta](https://github.com/aialok)
* Mentor: [Benjamin Granados](https://github.com/benjagm)
* [Idea on Github](https://github.com/json-schema-org/community/issues/603)

The Improved CI/CD Workflow for the [website](https://github.com/json-schema-org/website) project with GitHub Actions project focuses on enhancing the existing CI/CD pipelines by adding essential features like linting, formatting, unit testing, UI testing, broken link checks, and build processes. The project involves streamlining workflows for pull requests, pushes, and issues, with special emphasis on first-time contributors. Key deliverables include creating and optimizing workflows such as PR workflows, push workflows, issue workflows, stale issue and PR reminders, unauthorized file detection, and CodeQL for security analysis. Additionally, the project aims to provide clear documentation on workflow roles and guidelines for updates, ensuring smoother community operation integration and more efficient code management.

### 4. Building a New Version of the JSON Schema Tooling Page

* Contributor: [DV](http://github.com/darhkvoyd)
* Mentor: [Benjamin Granados](https://github.com/benjagm)
* [Idea on Github](https://github.com/json-schema-org/community/issues/602)

The JSON Schema [Tooling Page](https://json-schema.org/tools) plays a vital role in helping developers explore the ecosystem of JSON Schema tools and implementations. However, its current design presents usability challenges that hinder adoption. This project aims to rebuild the tooling page using a data-driven approach while adhering to the updated UI/UX standards of the JSON Schema website. By improving accessibility, simplifying navigation, and enhancing clarity, the revamped tooling page will make JSON Schema implementations more discoverable and user-friendly, ultimately reducing friction and encouraging broader adoption within the developer community.

### 5. JSON Schema Language Server Contributions

* Contributor: [Diya Solanki](https://github.com/diyaayay)
* Mentor: [Jason Desrosiers](https://github.com/jdesrosiers)
* [Idea on Github](https://github.com/json-schema-org/community/issues/601)

The project focuses on enhancing the [Language Server Protocol (LSP)](https://github.com/hyperjump-io/json-schema-language-tools) for JSON Schema, enabling improved support for various editors and IDEs. Unlike the existing VSCode integration, which lacks support for recent JSON Schema versions and struggles with performance for large schemas, this project aims to expand functionality. Key improvements include inline diagnostics for invalid schemas, semantic highlighting for JSON Schema and deprecated keywords, support for multiple drafts (04/06/07/2019-09/2020-12), and enhanced configuration management. The project also focuses on adding code completion for $schema, making JSON Schema development more efficient and accessible across platforms.

### 6. Define Upgrade/Downgrade Language-Agnostic Declarative Transformation Rules for all JSON Schema Dialects

* Contributor: [Suprith KG](https://github.com/suprith-hub)
* Mentor: [Juan Cruz Viotti](https://github.com/jviotti)
* [Idea on Github](https://github.com/json-schema-org/community/issues/599)

The project addresses the challenges of maintaining software compatibility across different schema versions. It focuses on creating declarative, language-agnostic rules to streamline the process of [upgrading or downgrading JSON Schemas](https://github.com/json-schema-org/upgrade-downgrade-rules). This is crucial for users working with high-level languages like Python, managing large documents, or navigating diverse network communication setups such as HTTP, WebSocket, microservices, or IoT. By simplifying schema transformations and introducing standardized procedures, this project aims to save time, ensure reliability, and improve JSON Schema’s versatility across various implementations and use cases.

### 7. Source Generation Analyzer Powered by Corvus.JsonSchema (.NET)

* Contributor: [Pranay Joshi](https://github.com/pranayjoshi)
* Mentors: [Matthew Adams (Endjin)](https://github.com/mwadams), [Greg Dennis](https://github.com/gregsdennis)
* [Idea on Github](https://github.com/json-schema-org/community/issues/614)

The project focuses on creating a source generator that integrates seamlessly with [Corvus.JsonSchema](https://github.com/corvus-dotnet/corvus.jsonschema). This tool will automatically generate code from JSON Schema files within a .NET project at compile time, streamlining the development process. The ultimate goal is to foster collaboration and consistency across software development teams using diverse technology stacks by establishing JSON Schema as a unified source of truth for data modeling. This ensures that generated code adheres to a standardized data structure, improving efficiency and alignment within organizations.

### 8. A Tour of JSON Schema

* Contributor: [Zeel Rajodiya](https://github.com/JeelRajodiya)
* Mentors: [Bence Eros](https://github.com/erosb), [Benjamin Granados](https://github.com/benjagm)
* [Idea on Github](https://github.com/json-schema-org/community/issues/645)

The [Tour of JSON Schema](https://github.com/json-schema-org/tour) project is an interactive learning platform designed to help beginners quickly grasp JSON Schema concepts and best practices. Through step-by-step lessons and hands-on exercises, users can learn by doing, using a simple interface and built-in code editor. The platform provides practical examples, real-time validation of JSON Schema, and immediate feedback, making the learning process engaging and effective. By following structured lessons, users will gain the confidence to create and work with JSON Schemas independently.

## Mentorship: A Two-Way Learning Process

The success of GSoC 2024 for JSON Schema wouldn’t have been possible without our dedicated mentors. They not only guided contributors but also gained fresh perspectives from working closely with emerging talent.

## Watch the Journey

Want to hear more about the contributors’ stories? Watch our [YouTube presentation](https://www.youtube.com/watch?v=2V9k1Hqhgnw) where contributors reflect on their challenges, successes, and learning moments.

## Looking Forward

GSoC 2024 has left an indelible mark on JSON Schema. From automation to tooling, each project has strengthened our ecosystem and laid a foundation for continued innovation.
We are excited about the future and invite developers from around the world to join us in shaping it.

## Ready to contribute?
Explore our [GitHub repository](https://github.com/json-schema-org), get involved in discussions, and be a part of the JSON Schema community!

Background photo by <a href="https://unsplash.com/@jessbaileydesigns?utm_content=creditCopyText&utm_medium=referral&utm_source=unsplash">Jess Bailey</a> 
on <a href="https://unsplash.com/photos/colored-pencil-lined-up-on-top-of-white-surface-l3N9Q27zULw?utm_content=creditCopyText&utm_medium=referral&utm_source=unsplash">Unsplash</a>


Onyedikachi Hope Amaechi-Okorie

Celebrating JSON Schema’s Google Summer of Code 2024 Journey


Many of you may have noticed a lot of changes happening around the JSON Schema community.  This website has had a facelift, we've started appearing at developer conferences, and we even participated in Google's Summer of Code & Summer of Docs programs.  But many of you may be asking, "What's happening with the spec?"

In this post I'll be providing an update on specification development and our new publication process.

## Publication Process

In a [previous post](./json-schema-joins-the-openjsf), we announced that we were no longer publishing our specifications through the IETF.  At the time, the intent was to join the OpenJS Foundation, however for multiple reasons, the onboarding process was not able to be completed.  As such, currently we are independent.  In the future, we may again seek to join a foundation (we may even try OpenJS again), but for now, independence seems to be the best place for us.

When we last published a specification, we used the IETF's [Internet-Draft Publication Process](https://authors.ietf.org/en/rfc-publication-process).  This meant that our documents were required to retain the "draft" moniker, even though we considered them fully fledged and ready for use in production systems.  Publishing independently, we're no longer bound by this requirement, however it does mean that we can no longer rely on the IETF document publishing infrastructure.  We have to build our own.

The foundation of our publication process is built on several ideals, and I'll cover the major ones in the next few sections.  By focusing on these pillars, we can ensure a safe and easy upgrade path for our users as the specification continues to evolve.

### Minimize Backward-Incompatible Changes Between Releases

One of the primary complaints we received about releasing a new specification over the last few iterations, particularly between Drafts 2019-09 and 2020-12, is the lack of consideration for backward compatibility.

Just to highlight a few of the breaking changes introduced with the latest version:

- `$recursiveRef` / `$recursiveAnchor` became `$dynamicRef` / `$dynamicAnchor`
- Array-form `items` became `prefixItems`
- `additionalItems` was removed; use schema-form `items` now

These changes meant that a schema written for Draft 2019-09 could validate completely differently when processed under Draft 2020-12 rules.  This creates a very poor upgrade experience.

In defending our decision to include these breaking changes, we hid behind our own advice to schema authors to include the `$schema` keyword, which identifies the dialect (specification version), instead of designing a [pit of success](https://blog.codinghorror.com/falling-into-the-pit-of-success/) that allowed them to continue their current behavior in a system that "just works".

**_Moving forward, upgrade compatibility is our #1 concern when developing a new release._**

That doesn't mean that a breaking change will _never_ happen, but we will make every effort to ensure that it doesn't.

### Maximize Forward Compatibility

**_We need to protect ourselves from potential future changes that would harm or prevent backward compatibility._**

Ironically, this means introducing a breaking change.  (I had [posted](./the-last-breaking-change) about this a couple of years ago, and the reception wasn't awesome, which led to a [follow-up post](./custom-annotations-will-continue).)

In short, to preserve future compatibility, we need to ensure that schemas can't contain extra properties which may one day be proposed as legitimate keywords.  This means that extra data in schemas can no longer be acceptable.  To accommodate our users' need to include meta-data and other values in their schemas, the specification will define a convention or namespace for property names that are to be ignored, and we guarantee that no future proposed keyword may follow this convention in order to keep the namespace protected.

As it stands today, the convention is that your property name should start with `x-`.  If you like, you can read about alternative ideas and how we decided on this approach in [the ADR](https://github.com/json-schema-org/json-schema-spec/blob/main/adr/2023-04-sva-prefix.md).

### Formally Define a Feature Proposal Process

In the past, new features would just be added to the specification and released with the next version.  We held it as acceptable that a feature may not be fully finished when we released the specification.  We expected to receive feedback, and the feature would be updated in the next version.

However, this approach puts a large burden on tooling maintainers who want to support multiple versions of the specification, which is basically all of them.  They'd have to support many different behaviors, sometimes for the same keyword.

The perfect example of this is Draft 2019-09's `$recursiveRef` & `$recursiveAnchor`.  The idea was solid and had a lot going for it.  In 2019 when we were working on it, we developed the concept as best we could, but we needed actual user feedback, so we added it to the specification, knowing that it wasn't quite complete.  Prior to releasing the specification, a few of us who had implementations also added it as an optional feature to let our users try it out.  But after the specification was released, we found that many users were confused as to how it should work, and we identified several ways that we could make it better.  Those improvements became `$dynamicRef` & `$dynamicAnchor` in Draft 2020-12.  Even though the "recursive" keywords weren't part of the latest specification, many implementations wanted to support Draft 2020-12 while continuing to support Draft 2019-09.  Furthermore, schemas which contained the "recursive" keywords couldn't be processed under the Draft 2020-12 rules, which takes us back to the backward compatibiility problem.

**_We need a feature proposal process that encourages tool support while also allowing continued feature development._**

By introducing a feature proposal process, all tooling maintainers can add support as they elect to do so.  And because these proposals aren't considered a hard requirement of the specification, we can continue to iterate on them (including breaking changes).  Finally, by actively encouraging tooling support, we can obtain the real-world feedback that we need to ensure that the feature is the best it can be before we officially integrate it into the specification.

## Compatibility with Draft 2020-12

To close this out, and with all of the above in mind, I want to cover what the upcoming release will entail as it stands now.

First, the incompatibilities:

- As mentioned before, we won't be supporting arbitrary properties anymore.  Any extra data you wish to include will need to use the `x-` property name convention.
- The `$dynamicRef` / `$dynamicAnchor` referencing system will be completely disjoint from the `$ref` / `$id` / `$anchor` system.  In Draft 2020-12, `$dynamicRef` could sometimes fall back to a normal `$ref` behavior.  This has been very confusing, so we've just isolated the two referencing systems.  This is _technically_ a breaking change, but we're pretty certain no one ever used `$dynamicRef` expecting it to work like `$ref`.
- `format` will validate by default.  There was a lot of [discussion](https://github.com/json-schema-org/json-schema-spec/issues/1520) on this topic, but the deciding factor was that users generally expect it to validate, and we wanted to meet that expectation.
- Vocabularies are being demoted to a feature proposal.  This was one of those ideas that wasn't completely finished when it was added to the spec in Draft 2019-09.  It's likely that this feature will change substantially before being merged back into the specification.  As a proposal, the feature can still be supported as development continues, but it's not a hard requirement.

Additionally, but not breaking:

- The recommended output format introduced in Draft 2019-09 has been extracted to its own specification.  The two driving factors for this decision were that different output formats could be more beneficial to different consumers and having the output versioned separately from the specification would more easily allow them to evolve independently.
- Many keyword interaction behaviors were defined by the annotations that were produced at various levels of evaluation.  This led to some confusion and unnecessary requirements, so we've loosened the language around this to allow tooling to figure out how they want to implement the behavior rather than prescribing a particular approach.
- General clean-up and clarifications to more accurately define behavior.

Beyond that, we still have a lot to do, but not nearly as much as we had this time last year, and we still have to figure out the actual publication piece, i.e. how we want it on the website.  We have the IETF-published documents mirrored here, and the new ones will likely go up next to those.  It's just another thing we need to do.  You can track our list of items on the [GitHub project board](https://github.com/orgs/json-schema-org/projects/15/views/1).

It's been four years since we published a new version, but we're getting really close, and I'm very excited.  Stay tuned!

_Cover image is of Mt. Taranaki in New Zealand, by [Sophie Turner](https://unsplash.com/@sophie_turner) on [Unsplash](https://unsplash.com/photos/mountain-near-body-of-water-during-daytime-LZVmvKlchM0)._


Greg Dennis

Moving Toward a Stable Spec

## Introduction
[Apidays Paris](https://www.apidays.global/paris/), the flagship event of the apidays family, returned this year with a focus on "The Future API Stack for Mass Innovation." This annual gathering of API enthusiasts, developers, and industry leaders brought together experts to discuss the latest trends and best practices in API design, API development, and API management.

This year's agenda highlighted the increasing role of AI in API development, exploring how AI can be used to automate tasks, improve API design, and enhance API performance.
Continuing our successful partnership with [AsyncAPI](https://www.asyncapi.com/en) and [OpenAPI](https://www.openapis.org/), this year's event marked a significant milestone with the inaugural JSON Schema conference track. This dedicated track, sponsored by [Octue](https://www.octue.com/), delved deep into the world of JSON Schema, exploring its role in API design, validation, and documentation.

## The first JSON Schema conference

The inaugural [JSON Schema conference track](https://conference.json-schema.org/) at apidays Paris 2024 was a resounding success. As part of the larger conference theme "The Future API Stack for Mass Innovation," the track showcased JSON Schema's crucial role in modern API development and data contract design. 

<figure className='flex flex-wrap justify-center items-center gap-4 w-full'>
    <img className='max-w-400 px-20' src='/img/posts/2024/apidays-paris-2024-recap/json-schema-team.jpg' alt="Five people standing at a booth labeled 'Standards'. They are smiling and looking at the camera. From left to right, their names are Benjamin Granados, Thomas Clark, Andreas Eberhart, Juan Cruz Viotti, and Ben Hutton."/>
    <figcaption class="text-center text-gray-600 text-sm">Community members at the standards booth shared with AsyncAPI, OpenAPI, and GraphQL. From left to right: Benjamin Granados (community manager), Thomas Clark (Octue CEO), Andreas Eberhart (JSON Schema ambassador), Juan Cruz Viotti (TSC member), and Ben Hutton (TSC member).</figcaption>
</figure>
<br>

[Ten comprehensive presentations](https://conference.json-schema.org/sessions/) spanned the spectrum of JSON Schema applications, from foundational concepts to cutting-edge implementations. The list of talks included:

- JSON Schema for data design and contract, client and code generation by Tom Collins (DVLA, UK Gov)
- IEC standards: Toward digital standards with JSON Schema by Thomas Clark (Octue CEO, conference sponsor)
- Introducing Strands - a JSON Schema repository by Thomas Clark
- JSON Schema: powering FINOS architecture as code by James Gough (Morgan Stanley)
- Generic and extensible web of things manager using JSON Schema and AI by Andreas Eberhart (Dashjoin, JSON Schema ambassador)
- High-performance JSON Schema validation in .NET by Matthew Adams (Endjin, TSC member)
- JSON schema and relational databases: bridging the gap by Loic Lefèvre (Oracle)
- Applying software engineering practices to JSON Schemas by Juan Cruz Viotti (Sourcemeta CEO, TSC member)
- The state of JSON schema by Benjamin Granados (Celonis, TSC member)
- Unlocking dynamic frontend development through JSON Schema by Neha Singla (Apple)

Three major themes recurred throughout the track: data design and standardization, tooling infrastructure, and modern application integration. Particularly notable was the emphasis on JSON Schema's role in AI integration and automated API development, aligning perfectly with the broader conference focus on AI's increasing importance in the API landscape.

Octue's sponsorship significantly bolstered the track's success, demonstrating their commitment to the JSON Schema community. This support enabled a diverse range of speakers to share their expertise and experiences.

Audience engagement exceeded expectations. Attendees from various industries and organizations - such as fintech, renewable energy, IT, and government - participated in robust Q&A sessions after each presentation. The discussions revealed both the growing adoption of JSON Schema across different sectors and the community's hunger for more knowledge about its practical applications.

<figure className='flex flex-wrap justify-center items-center gap-4 w-full'>
    <img className='max-w-400 px-20' src='/img/posts/2024/apidays-paris-2024-recap/loic-lefevre-talk.jpg' alt="Loic Lefevre presenting on stage at the APIDays Paris 2024 conference. The audience is seated in rows of chairs, facing the stage."/>
    <figcaption class="text-center text-gray-600 text-sm">A room full of people listening to Loïc Lefèvre’s engaging presentation on utilizing JSON schemas to manage relational databases.</figcaption>
</figure>
<br>

Looking ahead, this first dedicated track has laid a strong foundation for future JSON Schema events. The feedback highlighted the need to further showcase JSON Schema's versatility across different use cases, and plans are underway to expand and enhance next year's track. This successful launch not only validates JSON Schema's importance in modern API development but also signals the beginning of a new chapter in the community's growth and evolution.

## Collaboration with organizations

The success of the JSON Schema track at apidays Paris 2024 highlighted the vital role of community collaboration in our growth. It also demonstrated how organizations collaborating with JSON Schema gain more than just visibility - they become part of a broader movement toward standardized, high-quality API development. 

Here's how your organization can benefit:
- **Standardization & interoperability**: Ensure seamless data exchange and API integration.
- **Improved data quality**: Minimize errors with robust data validation.
- **Enhanced API design**: Streamline development with clear and concise schemas.
- **Increased productivity**: Automate tasks and boost efficiency with JSON Schema tools.
  
Here’s how you can become part of the initiative:
- [Be an ambassador](https://github.com/json-schema-org/community/tree/main/programs/ambassadors): Share your JSON Schema expertise and champion its adoption.
- [Become a sponsor](https://json-schema.org/overview/sponsors): Gain visibility and support the standard's growth.
- [Contribute to the project](https://github.com/json-schema-org): Help us shape the future of JSON Schema development.
- [Join our Slack workspace](https://json-schema.org/slack): Connect with the vibrant JSON Schema community.


Together, we can build a more robust and interoperable API ecosystem. 

A final thank you to Octue for sponsoring the conference, apidays Paris for hosting it, the organizers for their dedication and hard work, and the attendees for your valuable input and insightful questions. On behalf of JSON Schema, we look forward to seeing you again next year!

Acknowledgments: The author would like to thank Onyedikachi Hope, Ben Hutton, and Benjamin Granados for their valuable feedback, which enhanced the quality of this article. 


Build more. Break less. Empower others.

JSON Schema enables the confident and reliable use of the JSON data format.

Used by

Why JSON Schema?

Start learning JSON Schema

Explore the JSON Schema Ecosystem

Welcome to the JSON Schema Community

How Oracle is Bridging the Gap Between JSON Schema and Relational Databases

Upcoming Events

Start contributing to JSON Schema

Sponsors

Gold Sponsors

Silver Sponsors

Bronze Sponsors

Supported by