1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
|
===
FAQ
===
Why JSON Schema?
================
This design was initially inspired by an issue_ in the ``setuptools`` repository,
and brings a series of advantages and disadvantages.
Disadvantages include the fact that `JSON Schema`_ might be limited at times and
incapable of describing more complex checks. Additionally, error messages
produced by JSON Schema libraries might not be as pretty as the ones used
when bespoke validation is in place.
On the other hand, the fact that JSON Schema is standardised and have a
widespread usage among several programming language communities, means that a
bigger number of people can easily understand the schemas and modify them if
necessary.
Additionally, :pep:`518` already includes a JSON Schema representation, which
suggests that it can be used at the same time as specification language and
validation tool.
Why ``fastjsonschema``?
=======================
While there are other (more popular) `JSON Schema`_ libraries in the Python
community, none of the ones the original author of this package investigated
(other than :pypi:`fastjsonschema`) fulfilled the following requirements:
- Minimal number of dependencies (ideally 0)
- Easy to "vendorise", i.e. copy the source code of the package to be used
directly without requiring installation.
:pypi:`fastjsonschema` has no dependency and can generate validation code directly,
which bypass the need for copying most of the files when :doc:`"embedding"
<embedding>`.
Why draft-07 of JSON Schema and not a more modern version?
==========================================================
The most modern version of JSON Schema supported by :pypi:`fastjsonschema` is Draft 07.
It is not as bad as it may sound, it even supports `if-then-else`_-style conditions…
Why the URLs used as ``$id`` do not point to the schemas themselves?
====================================================================
According to the JSON Schema, the `$id keyword`_ is just a unique identifier
to differentiate between schemas and is not required to match a real URL.
The text on the standard is:
Note that this URI is an identifier and not necessarily a network locator.
In the case of a network-addressable URL, a schema need not be downloadable
from its canonical URI.
This information is confirmed in a `similar document submitted to the IETF`_.
Where do I find information about *format* X?
=============================================
Please check :doc:`/api/validate_pyproject.formats`.
.. _if-then-else: https://json-schema.org/understanding-json-schema/reference/conditionals.html
.. _issue: https://github.com/pypa/setuptools/issues/2671
.. _JSON Schema: https://json-schema.org/
.. _$id keyword: https://json-schema.org/draft/2020-12/json-schema-core.html#name-the-id-keyword
.. _similar document submitted to the IETF: https://datatracker.ietf.org/doc/html/draft-wright-json-schema-01#section-8
|
