Skip to content

Commit 17cc0ea

Browse files
CapstanCapstan
committed
Restore javadoc overview page.
Partial revert of commit ed7901e.
1 parent ed7901e commit 17cc0ea

File tree

1 file changed

+193
-0
lines changed

1 file changed

+193
-0
lines changed

‎src/main/javadoc/overview.html

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
<!DOCTYPE html>
2+
<!--
3+
~ Copyright (c) 2014, Francis Galiegue (fgaliegue@gmail.com)
4+
~
5+
~ This software is dual-licensed under:
6+
~
7+
~ - the Lesser General Public License (LGPL) version 3.0 or, at your option, any
8+
~ later version;
9+
~ - the Apache Software License (ASL) version 2.0.
10+
~
11+
~ The text of this file and of both licenses is available at the root of this
12+
~ project or, if you have the jar distribution, in directory META-INF/, under
13+
~ the names LGPL-3.0.txt and ASL-2.0.txt respectively.
14+
~
15+
~ Direct link to the sources:
16+
~
17+
~ - LGPL 3.0: https://www.gnu.org/licenses/lgpl-3.0.txt
18+
~ - ASL 2.0: http://www.apache.org/licenses/LICENSE-2.0.txt
19+
-->
20+
<html xmlns="http://www.w3.org/1999/html">
21+
<body>
22+
A JSON Schema validator implementation in Java which aims for correctness and
23+
performance, in that order
24+
25+
<h1>What this is</h1>
26+
27+
<h2>Motivation</h2>
28+
29+
<p>This implementation is meant to be purely server-side if Java is your
30+
language of choice. You may, <b>or may not</b>, use it in your Java Web
31+
application; this library has no dependencies on anything Web-related.</p>
32+
33+
<h2>Extensibility</h2>
34+
35+
<p>This project uses the infrastructure provided by <a
36+
href="https://github.com/fge/json-schema-core">json-schema-core</a>, which
37+
means you can use all the power in this library to include the processors
38+
provided in this package into your own custom chains.</p>
39+
40+
<p>What is more, you can define your own schemas, with dedicated keywords and/or
41+
format attributes.</p>
42+
43+
<h2>Strong points</h2>
44+
45+
<p>This library has complete draft v3 and draft v4 validation support.</p>
46+
47+
<p>It also has three particular features making it stand apart:</p>
48+
49+
<ul>
50+
<li>regular expressions obey ECMA 262 (ie, those are JavaScript regular
51+
expressions);</li>
52+
<li><b>it can validate numeric JSON data or abitrary scale/precision</b>.
53+
</li>
54+
</ul>
55+
56+
<h1>Sample usage</h1>
57+
58+
<p>There are code examples in package {@link
59+
com.github.fge.jsonschema.examples} which you can use to get started.</p>
60+
61+
<h1>The validation process</h1>
62+
63+
<p>The validation process is a five step process:</p>
64+
65+
<ul>
66+
<li><span style="font-family: monospace">$ref</span> resolution;</li>
67+
<li>schema syntax validation;</li>
68+
<li>schema digesting;</li>
69+
<li>keyword building;</li>
70+
<li>instance validation (ie, validate your data).</li>
71+
</ul>
72+
73+
<h2><span style="font-family: monospace">$ref</span> resolution</h2>
74+
75+
<p>This is a critically important part of the validation process. You may
76+
encounter, during validation, what is called a <a
77+
href="http://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03">JSON
78+
Reference</a>. A JSON Reference is a JSON Object with one member named
79+
<span style="font-family: monospace">$ref</span>, and the value of this member
80+
is a text value which embodies a URI. Implementations are required to follow
81+
JSON References until an actual final content is reached (and this content may,
82+
or may not, be a valid JSON Schema).</p>
83+
84+
<p>Also, consider this schema:</p>
85+
86+
<pre>
87+
{
88+
"$ref": "some://where/else",
89+
"minimum": 3
90+
}
91+
</pre>
92+
93+
<p>This is <b>still</b> a JSON Reference. Other schema keywords, such as
94+
<span style="font-family: monospace">minimum</span> in this example, should be
95+
<b>ignored</b>. And this is what this implementation does.</p>
96+
97+
<p>Note that any failure in $ref validation is considered a fatal error.</p>
98+
99+
<p>The processor in charge of this step is {@link
100+
com.github.fge.jsonschema.core.load.RefResolver}. It is located in package
101+
<span style="font-family: monospace">json-schema-core</span>.</p>
102+
103+
<h2>Schema syntax checking</h2>
104+
105+
<p>This is an equally important part of the validation process. One thing to
106+
note about the previous step is that it will only check that JSON Reference
107+
resolution ultimately leads to a JSON document, whatever that document is. Which
108+
means it may not even be a JSON Object, therefore not a JSON Schema. This basic
109+
check is done at that level.</p>
110+
111+
<p>After schema syntax checking is done, you are ensured that the schema is well
112+
formed: this simplifies later processing. Note however that syntax checking will
113+
not follow JSON References.</p>
114+
115+
<p>The processor in charge of this step is {@link
116+
com.github.fge.jsonschema.core.keyword.syntax.SyntaxProcessor}. It is located in
117+
the <span style="font-family: monospace">json-schema-core</span> package.</p>
118+
119+
<h2>Digesting</h2>
120+
121+
<p>This step of the processing chain takes into account both the schema and the
122+
instance to validate. Its role is to check the instance type, pick the relevant
123+
keywords for that instance type into the current schema, and build digested
124+
forms of these keywords for the next step.</p>
125+
126+
<p>For instance, consider that you are validating a number instance, and the
127+
current schema reads:</p>
128+
129+
<pre>
130+
{
131+
"minItems": 3,
132+
"maximum": 3
133+
}
134+
</pre>
135+
136+
<p>{@code minItems} does not apply to numbers, it will therefore be filtered out
137+
here. But this is not all. Now consider those two schemas:</p>
138+
139+
<pre>
140+
{
141+
"additionalItems": true
142+
}
143+
</pre>
144+
145+
<pre>
146+
{
147+
"additionalItems": { "type": "string" }
148+
}
149+
</pre>
150+
151+
<p>They have exactly the same influence on the validation of the array itself
152+
(note: the array, <b>not</b> its elements). The digest for these two schemas
153+
when the instance to validate is an array will therefore be the same. This
154+
allows to prune a lot of duplicates out of keyword caching.</p>
155+
156+
<p>The processor in charge of this step is {@link
157+
com.github.fge.jsonschema.processors.digest.SchemaDigester}.</p>
158+
159+
<h2>Keyword building</h2>
160+
161+
<p>At this step, the digested form of the current schema is grabbed and all
162+
relevant keywords are built (if they are not found in the cache). The real
163+
validation can now take place.</p>
164+
165+
<p>Again, all results are cached for future reuse. And as all keywords are
166+
context-free, a same result can be reused across different schemas.</p>
167+
168+
<p>The processor in charge of this step is {@link
169+
com.github.fge.jsonschema.processors.build.ValidatorBuilder}.</p>
170+
171+
<h2>Instance (aka data) validation</h2>
172+
173+
<p>This is the part which actually matters to end users: ensure that their data
174+
is valid.</p>
175+
176+
<p>This step of the processing consists of two distinct elements:</p>
177+
178+
<ul>
179+
<li>running the keyword validators built at the previous step;</li>
180+
<li>(recursively) validating children of arrays and/or objects.</li>
181+
</ul>
182+
183+
<p>As some keywords require that this very same processor be called again, all
184+
keyword validators keep a reference to it: this is what also allows keywords
185+
such as {@code anyOf}, {@code allOf} and others to work correctly. In a similar
186+
manner, this processor also needs a reference to the start of the chain (the
187+
reference resolver processor).</p>
188+
189+
<p>The processor in charge of this step is {@link
190+
com.github.fge.jsonschema.processors.validation.ValidationProcessor}.</p>
191+
192+
</body>
193+
</html>

0 commit comments

Comments
 (0)