Skip to content

install.markdown

Latest commit

 

History

History
114 lines (89 loc) · 3.85 KB

install.markdown

File metadata and controls

114 lines (89 loc) · 3.85 KB

Installing Dependencies

jsonschema install [<uri> <path>]
  [--force/-f] [--frozen/-z] [--verbose/-v] [--debug/-g] [--json/-j]

Many applications rely on consuming schemas authored and maintained by others. These schemas are typically published over HTTP(S) through registries like schemas.sourcemeta.com (a free public registry) or self-hosted solutions like Sourcemeta One. While you could manually download these schemas or write a custom fetching script, doing so quickly gets complicated: schemas often reference other schemas that also need to be fetched, and the results need to be bundled to inline those references for local consumption. The install command solves this in a single step.

Tip

The install command works with any resolvable URI, but it pairs especially well with a JSON Schema registry. If you don't have one yet, Sourcemeta One is a self-hosted registry built for this CLI, including dependency resolution, checksum verification, and GitOps-native deployment.

NOTE: Pass --frozen to strictly verify dependencies against the lock file without modifying it. This is intended for CI/CD pipelines where reproducibility is important. The lock file must exist and all dependencies must match.

You can quickly add a dependency by passing a URI and a local file path directly on the command line. For example:

jsonschema install https://schemas.sourcemeta.com/sourcemeta/std/v0/jsonrpc/v2.0/response ./vendor/response.json

This adds the dependency to jsonschema.json (creating the file if it does not exist) and immediately fetches it. The path is stored relative to jsonschema.json, so you can run this command from any subdirectory of your project.

Alternatively, you can declare dependencies manually. Create a jsonschema.json configuration file in your project and declare your dependencies as a mapping of schema URIs to local file paths. For example, to pull in the JSON-RPC 2.0 Response schema from the public registry:

{
  "dependencies": {
    "https://schemas.sourcemeta.com/sourcemeta/std/v0/jsonrpc/v2.0/response": "./vendor/response.json"
  }
}

Then run jsonschema install. Each dependency is fetched, bundled, and written to the specified path. A jsonschema.lock.json lock file is created alongside jsonschema.json to record the hash of each installed dependency. On subsequent runs, only dependencies that are missing, modified, or not yet tracked in the lock file are fetched again.

Tip

We recommend committing jsonschema.lock.json to version control (similar to package-lock.json) to enable reproducible installs across environments.

Warning

If a dependency uses a custom meta-schema that is itself an external dependency, make sure to list both the meta-schema and the schema that uses it in the dependencies map. The install command will resolve the meta-schema during bundling regardless of processing order. We are working on resolving this automatically in a future release.

Examples

Add a dependency

jsonschema install https://schemas.sourcemeta.com/sourcemeta/std/v0/jsonrpc/v2.0/response ./vendor/response.json

Add a dependency and force re-fetch all

jsonschema install --force https://schemas.sourcemeta.com/sourcemeta/std/v0/jsonrpc/v2.0/response ./vendor/response.json

Install all dependencies

jsonschema install

Force re-fetch all dependencies

jsonschema install --force

Install with verbose output

jsonschema install --verbose

Strict install for CI/CD

jsonschema install --frozen