JSON Schema - JSON Buddy Blog

The JSON Schema tester you really need

If you are looking for a way to test your JSON Schemas, you might be interested in the new JSON Schema tester from JSONBuddy. This tool allows you to validate your JSON Schemas against any number of JSON test data files, and check for consistency, correctness and coverage. In this blog post, we will show you how to use this tool and what benefits it can bring to your JSON Schema development.

What is a JSON Schema tester?

A JSON Schema tester is a tool that helps you to verify how a set of data files are validated against your JSON Schema resources. This is especially helpful during the design phase of the JSON Schema. The other way around, a JSON Schema test tool can also help you to ensure that your JSON data files match the expected structure and constraints defined by your JSON Schemas.

There are many online JSON Schema validators available. However, these online tools have some limitations. For example, they may not support the latest version of the JSON Schema specification, they may not allow you to test multiple JSON data files at once, or they may not provide detailed feedback on how well your JSON data covers your JSON Schema definitions.

That’s why JSONBuddy has developed a new JSON Schema test tool that aims to overcome these limitations and provide a more comprehensive and convenient way to test your JSON Schemas.

How to use the JSON Schema test tool from JSONBuddy?

JSONBuddy is a desktop application that runs on Windows. You can download it for free from https://www.json-buddy.com.

To use the tool, you need to have either a JSON Schema file, a JSON Schema pool and one or more JSON data files that you want to test against it. You can either create them in the built-in editor of JSONBuddy, or import them from your local or remote sources. It is only required, that the test data files are accessible in a single local folder.

Once you have your files ready, you can start testing them by following these steps:

Activate the Testing pane from the user-interface and bring the “Create new” tab to the front.
Assign a descriptive name for your schema test entry. A good name should be clear, concise and meaningful to help you identify the test later.
Set the JSON Schema resource. You can either select a predefined JSON Schema file
or pick a schema pool that can contain multiple schema resources.
As a final step, we choose the folder with the test data that we want to quickly and repeatedly validate against the selected JSON Schema resource.
Click on the Add test button to add your JSON Schema file and your JSON data files.
Switch to the Test collections tab to see a list of already added test entries.
Select an entry and click on the Run Test button to begin the validation process. The tool will check each JSON data file against the selected JSON Schema resource.
After the test is completed, you can examine all validation
results in detail. A separate log is saved for each test run to preserve the test data. This will show you the validation errors, warnings and processing information for each data file.
Optionally, you can set a reference result for each JSON Schema test entry by clicking on the Set as reference button. This will allow you to compare ongoing tests with the reference result and see if there are any changes or errors.
You can also view the schema definition coverage by clicking on the Schema Coverage button. This will show you which parts of the used schemas are checked by the test data, and which parts are not covered.

A collection of JSON Schema test entries

What are the main features of the JSON Schema test tool from JSONBuddy?

The JSON Schema test tool from JSONBuddy has several features that make it stand out from other online validators. Here are some of them:

It supports all versions of the JSON Schema specification, from Draft 4 to Draft 2020-12.
It allows you to test multiple JSON data files at once, without having to paste or upload them individually.
It allows you to set a reference result and compare ongoing tests with it. This can help you to check for consistency and correctness of your data over time.
It collects schema definition coverage information and shows you which parts of your schemas are tested by your data, and which parts are not. This can help you to improve your schema design and completeness.
It provides a summary report with one click, showing you the overall status of your tests, the number of errors and messages, and the coverage.
It integrates with the built-in editor of JSONBuddy, allowing you to edit your schemas and data files easily and see the validation results in real-time.

Why should you use the JSON Schema test tool from JSONBuddy?

The JSON Schema test tool from JSONBuddy is a powerful and convenient way to test your JSON Schemas and ensure that they are valid, compatible and complete. By using this tool, you can:

Save time and effort by testing multiple files at once
Avoid errors and inconsistencies by comparing tests with reference results
Improve your schema design and quality by collecting coverage information
Edit your schemas and data files with ease and see the validation results instantly

If you are interested in trying out the JSON Schema test tool from JSONBuddy, you can download it for free from https://www.json-buddy.com. You can also find more information and tutorials on how to use the software on the website.

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.