va-json-tools.json-schema-core.1.2.13.source-code.overview.html Maven / Gradle / Ivy
Show all versions of json-schema-core Show documentation
JSON Schema core utilities
What this is
This package provides an infrastructure to chain individual units of work
(processors) together in order to produce arbitrarily complex processing chains.
The provided infrastructure is complete with processing messages, reports and
dedicated exceptions.
In addition, it also provides a basic set of structures to work with JSON
Schema: trees and schema trees, JSON Reference, schema syntax validation and
schema walking (with associated listeners and processors), schema loading.
Processors
Basics
A {@link com.github.fge.jsonschema.core.processing.Processor} is a base unit
of work. Its concept is pretty simple: it accepts an input as an argument and
produces an output.
For reporting purposes, it also has a {@link
com.github.fge.jsonschema.core.report.ProcessingReport} as an argument, to which
you can log messages.
All the processing infrastructure is in the following package: {@link
com.github.fge.jsonschema.core.processing}.
Combining processors
You can combine processors in several ways:
- the first way is chaining them: as long as the output of a processor is
compatible with another, you can create a processor which is the result of
combining these two processors (of course, you are not limited to two);
- the second way is creating selectors; two selectors exist: a map-based
selector (which requires that you extract a key suitable for use in a map)
and a much more versatile, but more complex, predicate selector.
You can therefore create arbitrarily complex chains. And, last but not least,
you also have the ability to transparently cache the results of a processor if
the computation is expensive, for future reuse -- not only that, but you can
also provide an {@link com.google.common.base.Equivalence} on inputs to reduce
the set of inputs cached.
Reporting/logging
Basics
The two basic components of the reporting/logging infrastructure are {@link
com.github.fge.jsonschema.core.report.ProcessingReport} and {@link
com.github.fge.jsonschema.core.report.ProcessingMessage}.
The existing infrastructure allows you to:
- have full control over what is being logged, and how;
- customize exceptions and log messages.
All the logging infrastructure is in the following package: {@link
com.github.fge.jsonschema.core.report}.
Reports
A processing report has a classical set of logging methods, which names will
be familiar to anyone having used a logging API: {@code debug()}, {@code
info()}, {@code warn()} and {@code error()}. You can customize what log levels
are effectively logged, but also from what level exceptions are thrown instead.
As {@link com.github.fge.jsonschema.core.report.ProcessingReport} is an
interface, you can actually use a logging system for your messages -- or even
log messages at different levels differently; however, be aware that the
contract is rather strict (but it is documented), and as such you may prefer to
extend {@link
com.github.fge.jsonschema.core.report.AbstractProcessingReport} instead.
This package comes with three implementations built in: {@link
com.github.fge.jsonschema.core.report.ConsoleProcessingReport} (which logs to
the standard output), {@link
com.github.fge.jsonschema.core.report.ListProcessingReport} (which accumulates
messages in a list} and {@link
com.github.fge.jsonschema.core.report.DevNullProcessingReport} (which discards
all messages but keeps track of the processing status).
Messages
Messages have one main source: processor inputs. You will have noticed that
both inputs and outputs are required to implement the {@link
com.github.fge.jsonschema.core.report.MessageProvider} interface: this allows
reporting message templates to be generated out of an input and, as such, helps
greatly in identifying what the source of the message is, and therefore at what
step in the processing this message has been issued.
Another customization of logging messages is exception generation: when the
message is logged at a level which raises an exception rather than being
purely logged, {@link
com.github.fge.jsonschema.core.report.AbstractProcessingReport} does not {@code
throws} per se, but calls this message's {@code .asException()} instead. If you
have customized the processing message with a specific exception provider, this
means your custom exception will be thrown rather than the standard {@link
com.github.fge.jsonschema.core.exceptions.ProcessingException}.
JSON Reference
This package allows to build JSON References from string inputs or {@link
java.net.URI} instances. You can also resolve one reference against another and
obtain the fragment part (if the JSON Reference is legal) as a JSON Pointer.
The main use of this package in the core is to materialize URI contexts in
JSON Schema instances. A special form (non URI compliant) of reference exists
to be able to handle {@code jar} URIs as well.
All JSON Reference related classes are in the following package: {@link
com.github.fge.jsonschema.core.ref}.
Schema loading
Classes in the {@link com.github.fge.jsonschema.core.load} package serve
several purposes:
- preloading schemas;
- URI translations;
- adding and/or removing support for various URI schemes;
- JSON Reference resolving.
All aspects of schema loading are controlled via a {@link
com.github.fge.jsonschema.core.load.configuration.LoadingConfiguration}
instance.
Regular expressions
JSON Schema requires that regular expressions obey the ECMA 262 regular
expression dialect. This package, thanks to its dependency on Rhino, provides full
compliance.
For this purpose, the {@link com.github.fge.jsonschema.core.util.RhinoHelper}
class allows you to test whether a string is a valid ECMA 262 regular
expression, but also to test whether a string matches a given regex.