json-schema-catalog-rs 0.2.0

A tool for managing JSON Schema catalogs as defined by https://github.com/hmcts/cp-framework-libraries/blob/main/json-schema-catalog/catalog-core/src/main/resources/schema_catalog_schema.json
Documentation

Hercules CI

json-schema-catalog-rs provides Rust-based tooling around the de facto JSON Schema Catalog standard.

JSON Schema Catalog

A JSON Schema Catalog file provides a mapping from schema URIs to schema locations. By constructing and using a catalog, you can avoid the need to download and parse schemas from the internet. This is particularly useful when working with large schemas or when you need to work, test or build offline.

A json version of XML Catalogs for JSON Schemas.

— cp-framework-libraries

JSON Schema Catalog is not part of any standardization process, as far as I know, as of writing.

Origin

JSON Schema Catalog was published in the cp-framework-libraries project (by the UK Govt, but this project is neither affiliated nor endorsed by them). Tea was consumed during this project's creation, fwiw.

CLI

This crate provides a command line interface (CLI) for working with JSON Schema Catalogs.

Usage: json-schema-catalog <COMMAND>

Commands:
  check    Check a JSON schema catalog file for validity
  lookup   Look up a schema location by its id in a JSON schema catalog file
  replace  Replace "$ref", "$schema" occurrences in a JSON file with the corresponding physical file location
  new      Create a new JSON Schema Catalog file from a set of JSON schema filesCommands:

Example usage:

$ json-schema-catalog check json-schema-catalog-rs/example.json

$ export XDG_DATA_DIRS=$PWD/json-schema-catalog-rs/test/xdg${XDG_DATA_DIRS:+:$XDG_DATA_DIRS}

$ json-schema-catalog lookup https://schema.example.com/schema/schema_catalog_schema.json
/home/user/src/json-schema-catalog-rs-main/json-schema-catalog-rs/test/xdg/json-schema-catalogs/vendor/schema_catalog_schema.json

# Use `replace` on a catalog with a $schema property
$ json-schema-catalog replace json-schema-catalog-rs/test/example-with-schema.json
{
  "$schema": "/home/user/src/json-schema-catalog-rs-main/json-schema-catalog-rs/test/xdg/json-schema-catalogs/vendor/schema_catalog_schema.json",
  "groups": [
    {
      "baseLocation": "../vendor",
      "name": "json-schema-catalog-rs",
      "schemas": [
        {
          "id": "https://schema.example.com/schema/schema_catalog_schema.json",
          "location": "schema_catalog_schema.json"
        }
      ]
    }
  ],
  "name": "Example Catalog"
}

Installation

Contributing

Contributions are welcome, but open an issue, especially if you want to do something non-trivial.

replace is a stop-gap

I recommend that JSON Schema Catalog support be built in to any tools that use JSON Schema. Mutating the schema with replace is a destructive operation that will interfere with schema-based tooling that expects schemas to be referenced by their canonical URI, for example for the purpose of identifying which "types" are the same. Catalogs should be handled right above the transport layer, and not be observable in any schema-related behaviors or layers above it.