JSON Schema - JSON Buddy Blog

Configure and use JSON schema pools for validation

The JSON schema standard does not define a way to reference local or remote schema files for validation from within the JSON instance document. A JSON validator needs to support a way to load and assign schemas to the JSON data. Just setting a single root schema is not sufficient, if the schema itself references other components with $ref and $id. A JSON schema is identified by its $id and not by a local or remote path (Uri).

To address this, a schema pool can hold any number of JSON Schema files. One of those schemas is also set as the root schema in the configuration file.

Selecting a JSON Schema pool

In JSONBuddy, a schema for the active document can be selected using the Quick Associations pane. You can either set a pool or a local or remote path to the root schema as an alternative. If a schema pool is selected, the edit field to enter a path is disabled. The current schema pool assignment can be cleared with the red X button to the right.

The schema pools configuration file

All available JSON schema pools are configured using a settings document. This JSON file can be opened in JSONBuddy with the “Open config…” button. Add and edit the single pool entries directly in the JSON editor to change the configuration. Save the JSON file as usual and use the “Reload” button of the “Quick Associations” pane to apply the modifications to the schema pools used for JSON validation.

Here is an example of a simple schema pools configuration file:

[
  {
    "id": "1948DF5D-0765-4939-9F88-64CD3BB1D306-0",
    "title": "Library Example Schema",
    "version": 1,
    "rootIndex": 0,
    "entries": [
      "SchemaPools\\Library\\library_schema_root.json",
      "SchemaPools\\Library\\library_schema_book.json"
    ]
  }  
]

Property	Type	Description
`id`	`string`	A unique identifier of the pool within this configuration file.
`title`	`string`	Title to be displayed.
`rootIndex`	`integer`	Zero-based index to set the root schema of this pool. If omitted, the first entry is taken as root schema.
`entries`	`array`	An array of strings with local or remote (Url) paths to the schema documents. For local paths, the entry can be a relative path with the configuration file as the base.

Properties of a JSON schema pool entry.

Introducing the JSON Schema validation debugger

You got a JSON Schema written by someone else and have difficulty understanding why your data is not checked as you expected? Wouldn’t it be nice if you could step through the validation process and learn how the schema is applied to your JSON? Are you already thinking about a JSON Schema validation debugger?

You changed something in your JSON Schema and you want to be sure quickly, that your instance location is still validated? Setting a breakpoint in your JSON data would be very helpful in this case.

You check a huge JSON document with thousands of lines and you want to see in seconds what schema part validates a certain key? Just use the debugger and set a breakpoint at any JSONPointer location.

Well, there is a JSON editor available where you can do this and even more. Just start JSONBuddy Plus and run the JSON Schema validation debugger with a single click:

The JSON editor will then arrange the instance document to the left and the root JSON Schema file to the right. The locations of the first validation steps are marked with yellow arrows in the left margin areas of the editor windows. The current lines are also indicated with an alternative background color. Therefore, the current validation step is always clearly visible.

Debugging commands

You can find all of the usual debugger commands in the toolbar. Often it will be quicker to use the keyboard. Press F8 for a single step and Ctrl+F8 to run until the next breakpoint or validation error. There is also an option to toggle if the debugger should break whenever a validation error occurred.

A breakpoint can be set in the instance document and any referenced JSON Schema file with the right-mouse-click context menu in the text editor window.

Set a breakpoint in the JSON instance document

Getting a deeper understanding of the JSON Schema validation process is only one reason to use the debugger. It saves a lot of time on getting a schema ready for production. But don’t forget to restart the debugger session if you modify any of the JSON Schema files.

Editing the JSON input data while debugging

Furthermore, it is possible to edit the JSON data while the debugger session is active. Jump from error to error to resolve and fix any issues in the instance.

Validation stopped in JSON debugger at an error.

In order to give additional details about the error, all of the usual context information and indicators are also available while running the debugger. As a consequence, it is often easy to apply the fix.

Fixing the error and continuing with debugging

Please note, that major changes to the structure of the JSON input can result in making it impossible for the debugger to find any subsequent error locations. In this case, it is recommended to restart the validation in the JSON editor.

Don’t underrate the benefits of a debugger

Learn about the details of an unknown schema. Resolve errors in JSON data step by step. Not to mention, check if a property is validated in huge JSON documents quickly. The benefits of having a validation debugger in your JSON editor are numerous.

Full support for JSON schema draft 2019-09

JSONBuddy 6 was released on June, 12th 2021. One of the major new features in the JSON editor is the full support of the JSON Schema draft 2019-09. This means the built-in validator is passing all test cases of the official test suite (around 1000 cases). Hence, JSONBuddy enables you to write and test JSON schemas for all popular drafts.

A JSON linter for JSON schema

If you follow the JSON schema Slack workspace or the JSON schema tag at StackOverflow, you will notice that schema authors are often struggling with the same problems while writing a valid and working JSON schema.

A type specifier or a schema keyword is mistyped, an unresolved $ref because the target is missing or the pointer is not correct or a required property is not defined. It is usually easy to fix those errors but unfortunately, it often takes a long time to find them.

Saving time while creating JSON schemas

This is the point, where the built-in JSON Schema analyzer of JSONBuddy can help you to save a lot of time and hassle if you use the tool as your JSON Schema editor. The analyzer is a linter for JSON schema and runs in the background while you are working on your schema. Whenever the schema linter finds something to report, you will get a message in the results window.

Let us take a quick look at an example from the real world.

Someone removed a definition from the JSON schema

You are working on a big schema and someone from your group removed a definition accidentally. The next time you open the JSON schema, JSONBuddy will show you the following message:

JSON schema linter message about an unresolved $ref

This allows you to fix the error right away. You can go to the version history of the JSON Schema in your repository and revert the change to get the definition back.

If you want to learn more about the JSON schema linter in JSONBuddy, take a look at the following page: JSON schema analyzer – Get a unique companion while editing your JSON schemas.

JSON Schema in the wild: A missing required property

There are some issues that happen over and over again if you write JSON schemas with a plain text editor. You can often follow them in the Slack community for JSON schema or at StackOverflow: A schema is modified and the validation is no longer working as before but nobody knows about it at the time the schema was changed.

The good news is: The built-in JSON schema analyzer in JSONBuddy can detect a lot of those issues while you are editing your schema in the JSON editor.

A while ago this happened to a user: A property was removed from the JSON Schema but was still present in the “required” keyword array. As a consequence, a lot of the JSON data was invalid.

Use an extraordinary JSON schema editor

This can’t happen if you use JSONBuddy as your JSON schema editor. Because the built-in schema analyzer reports the missing required property definition right at the time when you are editing your schema. Instead, you get the following warning:

Warning about a missing required property.

This and several other common issues are reported by the schema analyzer if you use JSONBuddy as your JSON schema editor. Providing you with exceptional support when working with JSON Schema documents helps to save time and avoid extra work.

JSON schema editor with $ref resolving

Being able to navigate quickly and conveniently in your JSON schema can make a big difference while you are working on your schema definitions. Here is a sample screen-shot directly from the JSON schema editor environment of JSONBuddy of the “Unity Assembly Definition” schema available at schemastore.org:

The editor resolves the target locations of all $ref keywords in the current schema and displays them as active links. The resolved JSON pointer and the path to the schema are shown as part of the info window if you move the mouse over the reference.

You get instant feedback if the $ref value can be resolved together with the target location and you save time by clicking the link if you need to take a closer look at the schema node.

Amazing navigation features

Hold down the Control key and left-click on the link to jump directly to the resolved JSON schema node.

An additional tip to quickly navigate in the JSON schema editor: Use the Navigation-history back shortcut “Control-Shift-,” to jump back immediately to the $ref keyword.

Altogether some outstanding enhancements for the JSON schema editor.

Using the built-in JSON schema generator

Do you want to quickly generate a basic JSON schema in your editor from any JSON input to avoid some typing that needs to be done every time you start writing a schema? A quick skeleton schema as a starting point with all current properties defined and their integral types already resolved? If yes, you can do this in JSONBuddy with ease.

This is how you do it in the editor:

Open your JSON data as document. It doesn’t matter if you use the text or grid view.
Use the following command to open a new document with the generated JSON schema: “JSON | Generate JSON schema from document”.

Generate a JSON schema from the current document in the editor

The generated schema is opened as a new document in the editor. Integral types are resolved and all objects which are not part of the top level are added as definitions to the schema. Equal object definitions will only appear once.

Automatic schema generation in the background

But even if you don’t use the command to generate a schema, a JSON schema is automatically generated in the background for any JSON document with currently no schema assigned. This schema is used to fill the Elements pane and to provide the entry-helper windows.

JSON editor and validator for large schemas

Sometimes it can happen that a JSON schema is generated from existing data and the resulting schema is quite huge. And maybe this schema is just taken as a starting point and you need to extend or modify it to get the final specifications for your JSON input.

One example of a really huge JSON schema is the Ansible schema available from schemastore.org (Please take a look at this blog entry to see how easy it is to open any schema from schemastore.org in JSONBuddy). The Ansible schema has currently more than 100.000 lines and 5 MB of JSON text. For this task, you need a good JSON editor which can also handle quite large files.

JSONBuddy: The editor for large JSON schemas

JSONBuddy is capable of loading big schema documents. The editor will apply syntax-coloring, entry-helpers and code folding as it does for a typical schema. You also don’t have to work on your schema without the context-sensitive help of getting the specification text for the keyword you are currently editing. All of this is also functional for big schemas.

But there is more. For example, besides being able to edit a JSON schema as you are used to, you get an instant evaluation from the built-in JSON schema analyzer. The schema analyzer runs in the background and is also active for large schema documents. For example, if a certain definition is not used in the local schema, there is no need to run an explicit find operation:

Inserting a new definition in a JSON schema with more than 100k lines

And this also works the other way around, whenever you add a $ref keyword to your JSON schema in the editor, the analyzer will tell you if the referenced definition can be successfully resolved.

“And do I get those nice validation error indicators which are saving so much time on editing my JSON content in the editor?” Yes, you do:

Active background validation on using a huge JSON schema

JSON schema editor: Full support for draft 6

JSONBuddy continues to extend the support for JSON schema and fully supports draft 6 as the only available JSON schema editor. From now on (JSONBuddy 4.6), you can validate your JSON files against draft 6 directly in the editor. In addition, you can also start using draft 6 in the command-line tool, which is part of the JSONBuddy software package, to run your batch validation tasks.

JSON schema draft 6 is supported by the following components in detail

JSON validator – Also available for background validation and live error indicators in text view
JSON schema editor – Full entry-helper support for new draft 6 keywords, schema validation and schema specification as help text.
JSON schema analyzer – Support for draft 6 schema keywords.

With JSON schema draft 6 and the integrated easy access to the schemastore.org schema library, JSONBuddy provides the most comprehensive support for JSON schema available. And JSONBuddy will also continue to implement the latest versions of the JSON schema standard in the future.

All your JSON schema are belong to us

Ok, please don’t take this title literally. But did you know that you can instantly load all JSON schema files from schemastore.org in JSONBuddy? All you need to do is to open JSONBuddy and to use the “File | Open from JSON schema library…” command to show the open dialog which reads all available schema documents from schemastore.org. This list is updated any time you start the JSONBuddy editor.

schemastore.org is a great resource to learn how others are writing JSON schemas and can help a lot on providing own specifications for your JSON data. After the schema is loaded in JSONBuddy, the editor will automatically generate JSON sample data. You can immediately create a new document from the sample data using the “JSON | Generate sample document from JSON schema” command.

In addition, the unique built-in JSON schema analyzer will start to report any issues it can find about the schema. You can learn more about the analyzer on the following page: An assistant on creating JSON schema documents.

As you can see, JSONBuddy is a complete package to make working with JSON data and JSON schema a lot easier, quicker and more comfortable.