From 3893ae7c4af9aad5da03bc76eda2ffb3c4c7f3cd Mon Sep 17 00:00:00 2001 From: Juan Cruz Viotti Date: Mon, 3 Jun 2024 12:46:18 -0400 Subject: [PATCH] Revisit command documentation Signed-off-by: Juan Cruz Viotti --- docs/bundle.markdown | 12 +++++++----- docs/lint.markdown | 11 +++++++---- docs/test.markdown | 6 ++++-- docs/validate.markdown | 4 ++-- 4 files changed, 20 insertions(+), 13 deletions(-) diff --git a/docs/bundle.markdown b/docs/bundle.markdown index 1fce733d..d5342d2b 100644 --- a/docs/bundle.markdown +++ b/docs/bundle.markdown @@ -5,12 +5,14 @@ Bundling jsonschema bundle ``` -A schema may contain references to remote schemas located in other files or -even shared over the Internet. JSON Schema supports a standardized process, -referred to as +A schema may contain references to remote schemas outside the scope of the +given schema. These remote schemas may live in other files, or may be server by +others over the Internet. JSON Schema supports a standardized process, referred +to as [bundling](https://json-schema.org/blog/posts/bundling-json-schema-compound-documents), -to resolve remote references in advance and inline them into the given schema. -The JSON Schema CLI supports this functionality through the `bundle` command. +to resolve remote references in advance and inline them into the given schema +for local consumption or further distribution. The JSON Schema CLI supports +this functionality through the `bundle` command. Examples -------- diff --git a/docs/lint.markdown b/docs/lint.markdown index 5ddc0e9d..dd2a20a7 100644 --- a/docs/lint.markdown +++ b/docs/lint.markdown @@ -6,10 +6,13 @@ jsonschema lint [schemas-or-directories...] [--fix|-f] ``` JSON Schema is a surprisingly expressive schema language. Like with traditional -programming languages, writing efficient and maintainable schemas take -experience, and there are lots of ways of doing it wrong. To help with this, -the JSON Schema CLI provides a `lint` command that can check your schemas -against various common anti-patterns and automatically fix many of them. +programming languages, writing efficient and maintainable schemas takes +experience, and there are lots of common pitfalls. Just like popular linters +like [ESLint](https://eslint.org), +[ClangTidy](https://clang.llvm.org/extra/clang-tidy/), and +[PyLint](https://www.pylint.org), the JSON Schema CLI provides a `lint` command +that can check your schemas against various common anti-patterns and +automatically fix many of them. Examples -------- diff --git a/docs/test.markdown b/docs/test.markdown index 7803d14b..349fe37a 100644 --- a/docs/test.markdown +++ b/docs/test.markdown @@ -6,8 +6,10 @@ jsonschema test [schemas-or-directories...] ``` Schemas are code. As such, you should run an automated unit testing suite -against them. The JSON Schema CLI provides a schema-oriented test runner -inspired by the [official JSON Schema test +against them. Just like popular test frameworks like [Jest](https://jestjs.io), +[GoogleTest](https://google.github.io/googletest/), and +[PyTest](https://docs.pytest.org), the JSON Schema CLI provides a +schema-oriented test runner inspired by the [official JSON Schema test suite](https://github.com/json-schema-org/JSON-Schema-Test-Suite). Examples diff --git a/docs/validate.markdown b/docs/validate.markdown index 3d957f7d..9bf2d6ae 100644 --- a/docs/validate.markdown +++ b/docs/validate.markdown @@ -6,7 +6,8 @@ jsonschema validate ``` The most popular use case of JSON Schema is to validate JSON documents. The -JSON Schema CLI offers a `validate` command to do exactly that. +JSON Schema CLI offers a `validate` command to evaluate a JSON instance against +a JSON Schema, presenting human-friendly information on unsuccessful validation. Examples -------- @@ -16,4 +17,3 @@ Examples ```sh jsonschema validate path/to/my/schema.json path/to/my/instance.json ``` -