diff options
Diffstat (limited to 'docs/faq.rst')
| -rw-r--r-- | docs/faq.rst | 57 |
1 files changed, 2 insertions, 55 deletions
diff --git a/docs/faq.rst b/docs/faq.rst index 4dc1c5b..5ae3e62 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -85,9 +85,10 @@ The JSON object ``{}`` is simply the Python `dict` ``{}``, and a JSON Schema lik The :kw:`$ref` keyword is a single notable exception. - Specifically, in the case where `jsonschema` is asked to `resolve a remote reference <jsonschema.validators.RefResolver>`, it has no choice but to assume that the remote reference is serialized as JSON, and to deserialize it using the `json` module. + Specifically, in the case where `jsonschema` is asked to resolve a remote reference, it has no choice but to assume that the remote reference is serialized as JSON, and to deserialize it using the `json` module. One cannot today therefore reference some remote piece of YAML and have it deserialized into Python objects by this library without doing some additional work. + See `Resolving References to Schemas Written in YAML <referencing:Resolving References to Schemas Written in YAML>` for details. In practice what this means for JSON-like formats like YAML and TOML is that indeed one can generally schematize and then validate them exactly as if they were JSON by simply first deserializing them using libraries like ``PyYAML`` or the like, and passing the resulting Python objects into functions within this library. @@ -99,60 +100,6 @@ In such cases one is recommended to first pre-process the data such that the res In the previous example, if the desired behavior is to transparently coerce numeric properties to strings, as Javascript might, then do the conversion explicitly before passing data to this library. -How do I configure a base URI for $ref resolution using local files? --------------------------------------------------------------------- - -`jsonschema` supports loading schemas from the filesystem. - -The most common mistake when configuring a `jsonschema.validators.RefResolver` -to retrieve schemas from the local filesystem is to give it a base URI -which points to a directory, but forget to add a trailing slash. - -For example, given a directory ``/tmp/foo/`` with ``bar/schema.json`` -within it, you should use something like: - -.. code-block:: python - - from pathlib import Path - - import jsonschema.validators - - path = Path("/tmp/foo") - resolver = jsonschema.validators.RefResolver( - base_uri=f"{path.as_uri()}/", - referrer=True, - ) - jsonschema.validate( - instance={}, - schema={"$ref": "bar/schema.json"}, - resolver=resolver, - ) - -where note: - - * the base URI has a trailing slash, even though - `pathlib.PurePath.as_uri` does not add it! - * any relative refs are now given relative to the provided directory - -If you forget the trailing slash, you'll find references are resolved a -directory too high. - -You're likely familiar with this behavior from your browser. If you -visit a page at ``https://example.com/foo``, then links on it like -``<a href="./bar">`` take you to ``https://example.com/bar``, not -``https://example.com/foo/bar``. For this reason many sites will -redirect ``https://example.com/foo`` to ``https://example.com/foo/``, -i.e. add the trailing slash, so that relative links on the page will keep the -last path component. - -There are, in summary, 2 ways to do this properly: - -* Remember to include a trailing slash, so your base URI is - ``file:///foo/bar/`` rather than ``file:///foo/bar``, as shown above -* Use a file within the directory as your base URI rather than the - directory itself, i.e. ``file://foo/bar/baz.json``, which will of course - cause ``baz.json`` to be removed while resolving relative URIs - Why doesn't my schema's default property set the default on my instance? ------------------------------------------------------------------------ |