The Last Breaking Change for JSON Schema

published on 2023/03/06

Suppose a user wrote the example schema above while using a validator written to conform to the 2023 version of the specification. A couple years later, they want to upgrade the validator now that supports the 2025 specification. However in that 2025 specification, we added database-field-id as a keyword, and its value is expected to be a string. Suddenly the user's schema is no longer valid. We've broken a user by adding a new keyword.

In order to prevent this scenario, we are forced to forbid keywords that are not declared by a listed vocabulary. We recognize that this will break a lot of people up front. However we feel that a promise of future-compatible specifications should take precedence over the immediate pain of having to change your schemas yet again (and potentially again perpetually into the future).

JSON Schema