Update documentation for 0.8.0 release

CHANGELOG.rst

@@ -1,8 +1,8 @@
 Changelog
 =========
 
-v0.8.0 (in development)
------------------------
+v0.8.0 (2022-01-29)
+-------------------
 Features:
 
 * Added support for remote schema references and, more generally, 'sources' for loading

README.rst

@@ -8,15 +8,18 @@ jschon is a pythonic and extensible implementation of the
 
 Features
 --------
-* JSON Schema validator implementation (2019-09, 2020-12)
+* JSON Schema validator implementation (drafts 2019-09, 2020-12)
 
-  * Format assertion supported via plug-in callables
   * Schema compilation and indexing
-  * $ref loading from local and (coming soon!) remote sources
+  * $ref loading from local and remote sources
   * Support for custom keywords, vocabularies and meta-schemas
+  * Support for format validation
 
 * JSON class implementing the JSON data model
-* JSON pointer implementation (`RFC 6901 <https://tools.ietf.org/html/rfc6901>`_)
+* JSON Pointer (`RFC 6901 <https://tools.ietf.org/html/rfc6901.html>`_)
+* JSON Patch (`RFC 6902 <https://tools.ietf.org/html/rfc6902.html>`_)
+* Relative JSON Pointer (`draft <https://json-schema.org/draft/2020-12/relative-json-pointer.html>`_)
+* JSON document translation (`experimental <https://github.com/marksparkza/json-translation-vocabulary>`_)
 
 Installation
 ------------

docs/api.rst

@@ -11,6 +11,8 @@ The following classes may be imported directly from the top-level
 * :class:`~jschon.jsonpatch.JSONPatchOperation`
 * :class:`~jschon.jsonpointer.JSONPointer`
 * :class:`~jschon.exceptions.JSONPointerError`
+* :class:`~jschon.jsonpointer.RelativeJSONPointer`
+* :class:`~jschon.exceptions.RelativeJSONPointerError`
 * :class:`~jschon.jsonschema.JSONSchema`
 * :class:`~jschon.exceptions.JSONSchemaError`
 * :class:`~jschon.catalog.LocalSource`

docs/examples/extending_json_schema.rst

@@ -1,16 +1,9 @@
 Extending JSON Schema
 =====================
-Consider the following scenario:
-
-You're working on data validation for a project that uses enumerations
-consisting of thousands of codes, obtained and cached from remote terminology
-services. Your validation schema -- and any error output it produces -- cannot
-list all the possible values for an enumeration, but should rather reference
-an enumeration by its id.
-
-In the following example, we solve this problem by defining a custom keyword --
-``"enumRef"`` -- that can retrieve an enumeration given its URI and decide
-whether a given string instance is valid.
+In this example, we define a custom keyword -- ``"enumRef"`` -- that provides
+us with the capability to validate JSON string instances against enumerations
+(which may consist of many thousands of terms) that we have obtained and cached
+from remote terminology services.
 
 First, we create a vocabulary that describes the syntax of our new keyword.
 This is a JSON meta-schema that we'll save to ``data/enumRef-vocabulary.json``:

docs/guide/catalog.rst

@@ -42,12 +42,15 @@ specified when creating new :class:`~jschon.jsonschema.JSONSchema` objects:
 
 Reference loading
 -----------------
-With jschon, schema references can be resolved to files on disk, by configuring
+Schema references can be resolved to files on disk, by configuring
 a local directory source for a given base URI:
 
->>> from jschon import create_catalog, URI
+>>> from jschon import create_catalog, LocalSource, URI
 >>> catalog = create_catalog('2020-12')
->>> catalog.add_local_source(URI("https://example.com/schemas/"), '/path/to/schemas/')
+>>> catalog.add_uri_source(
+...     URI("https://example.com/schemas/"),
+...     LocalSource('/path/to/schemas/', suffix='.json')
+... )
 
 Now, the ``"$ref"`` in the following schema resolves to the local file
 ``/path/to/schemas/my/schema.json``::

docs/guide/json.rst

@@ -11,24 +11,18 @@ of each. We begin by importing the :class:`~jschon.json.JSON` class:
 
 >>> from jschon import JSON
 
->>> JSON(None).type
-'null'
-
->>> JSON(True).type
-'boolean'
+>>> JSON("Hello, World!").type
+'string'
 
 >>> JSON(3.14159).type
 'number'
 
->>> JSON("Hello, World!").type
-'string'
+>>> JSON(None).type
+'null'
 
->>> JSON((1, 2, 3)).type
+>>> JSON(("a", "b", "c")).type
 'array'
 
->>> JSON({"foo": True, "bar": False}).type
-'object'
-
 Instances with the JSON types ``"array"`` and ``"object"`` are constructed
 recursively. Here we create an array and an object:
 
@@ -68,7 +62,8 @@ working with complex JSON structures. Consider the following example:
 ...     ]
 ... })
 
-A leaf node's :attr:`~jschon.json.JSON.data` is the value from which it was constructed:
+A leaf node's :attr:`~jschon.json.JSON.data` attribute holds the value from which
+it was constructed:
 
 >>> document["1a"]["2a"].data
 'foo'
@@ -124,21 +119,20 @@ items have different JSON types:
 >>> JSON([False, True]) == JSON([0, 1])
 False
 
-:class:`~jschon.json.JSON` also implements the ``<``, ``<=``, ``>=``, ``>`` and
-``!=`` comparison operators, which may be used wherever it makes sense for the
-types of the given operands:
-
->>> JSON(3) < JSON(3.01)
-True
-
 A :class:`~jschon.json.JSON` instance may be compared with *any* Python object.
-Internally, the non-:class:`~jschon.json.JSON` object is cast to its :class:`~jschon.json.JSON`
+Internally, the non-:class:`~jschon.json.JSON` object is coerced to its :class:`~jschon.json.JSON`
 equivalent before performing the comparison. Notice that tuples and lists are
 considered structurally equivalent:
 
 >>> (7, 11) == JSON([7, 11])
 True
 
+:class:`~jschon.json.JSON` also implements the ``<``, ``<=``, ``>=`` and ``>``
+inequality operators, which may be used for numeric or string comparisons:
+
+>>> JSON(3) < 3.01
+True
+
 jschon is not a JSON encoder/decoder. However, the :class:`~jschon.json.JSON`
 class supports both serialization and deserialization of JSON documents, via the
 Python standard library's :mod:`json` module.

docs/guide/jsonschema.rst

@@ -128,7 +128,7 @@ The argument to :meth:`~jschon.json.JSON.loadf` may be a plain :class:`str`, or
 any :class:`PathLike` object; for example:
 
 >>> import pathlib
->>> schema_path = pathlib.Path(__file__).parent / 'num-schema.json',
+>>> schema_path = pathlib.Path(__file__).parent / 'num-schema.json'
 >>> num_schema = JSONSchema.loadf(schema_path)
 
 Both :meth:`~jschon.json.JSON.loads` and :meth:`~jschon.json.JSON.loadf` accept

docs/reference/translation.rst

@@ -0,0 +1,3 @@
+jschon.translation
+==================
+.. automodule:: jschon.translation

docs/reference/vocabulary/translation.rst

@@ -0,0 +1,3 @@
+jschon.vocabulary.translation
+=============================
+.. automodule:: jschon.vocabulary.translation