json-schema-core 0.99.8 API

JSON Schema core utilities

See: Description

Packages 
Package Description
com.github.fge.jsonschema  
com.github.fge.jsonschema.exceptions
Exceptions and exception provider
com.github.fge.jsonschema.exceptions.unchecked
Unchecked processing exceptions
com.github.fge.jsonschema.jsonpointer
JSON Pointer related classes
com.github.fge.jsonschema.library
Base library class
com.github.fge.jsonschema.messages
Messages used for ProcessingException and ProcessingError messages
com.github.fge.jsonschema.processing
Core processing interface and building utility classes
com.github.fge.jsonschema.ref
JSON Reference related classes
com.github.fge.jsonschema.report
Processing report infrastructure
com.github.fge.jsonschema.tree
Navigable JSON tree representations
com.github.fge.jsonschema.util
Various utility classes
com.github.fge.jsonschema.util.equivalence  
JSON Schema core utilities

What this is

General presentation

This package originated as a split from json-schema-validator. Elements provided by this package can be used to plug the validation capabilities of json-schema-validator with other JSON Schema related tasks.

The following elements are provided:

  • a processor system, complete with chaining, selecting, caching;
  • a fully customizable reporting/logging system;
  • full JSON Reference and JSON Pointer support;
  • JSON (as JsonNode) utilities: parsing (with arbitrary large scale/precision for numbers), writing, generating;
  • other various JSON Schema base classes.

Processors

Basics

A 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 ProcessingReport as an argument, to which you can log messages.

All the processing infrastructure is in the following package: com.github.fge.jsonschema.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 Equivalence on inputs to reduce the set of inputs cached.

Reporting/logging

Basics

The two basic components of the reporting/logging infrastructure are ProcessingReport and 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: com.github.fge.jsonschema.report.

Reports

A processing report has a classical set of logging methods, which names will be familiar to anyone having used a logging API: debug(), info(), warn() and error(). You can customize what log levels are effectively logged, but also from what level exceptions are thrown instead.

As 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 AbstractProcessingReport instead.

This package comes with three implementations built in: ConsoleProcessingReport (which logs to the standard output), ListProcessingReport (which accumulates messages in a list, which you can retrieve later} and ForwardingReport (which forwards all messages to another report but keeps its own success status).

Messages

Messages have one main source: processor inputs. You will have noticed that both inputs and outputs are required to implement the 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, AbstractProcessingReport does not throw per se, but calls this message's .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 ProcessingException.

JSON Reference and JSON Pointer

JSON Reference

This package allows to build JSON References from string inputs or 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 jar URIs as well.

All JSON Reference related classes are in the following package: com.github.fge.jsonschema.ref.

JSON Pointer

You can use JSON Pointer to navigate through JSON documents, and this package has full support for this. While the mostly used class will be JsonPointer itself, the code is generic enough that it can adapt to any TreeNode instance.

See the different classes in com.github.fge.jsonschema.tree for examples of how JSON Pointer is used.

All JSON Pointer related classes are in the following package: com.github.fge.jsonschema.jsonpointer.

Other utilities

Many other utilities exist in this package. This lists the most important of them.

Exceptions

This package has a set of both checked and unchecked exceptions. Checked exceptions are all subclasses of ProcessingException, while unchecked exceptions are subclasses of ProcessingError.

Unchecked exceptions are thrown when a misconfiguration occurs, therefore always before the processing actually takes place. This mostly occurs when a null input is provided to methods which do not accept it, and prevents NullPointerExceptions to be thrown when processing.

All the exception infrastructure is in the following package: com.github.fge.jsonschema.exceptions.

Important JSON Schema related utilities

This package provides five important utility classes for JSON Schema usage:

  • JacksonUtils provides a reader and node factory with customized configuration; in particular, all decimal number instances are read as BigDecimal to prevent loss of precision during computations;
  • JsonLoader allows to load JSON content from various sources, and makes use of the reader above;
  • NodeType allows to determine the type of a JSON value according to the JSON Schema definition;
  • RhinoHelper allows to check the validity of, and use regexes using, ECMA 262, as required by the JSON Schema specification;
  • JsonSchemaEquivalence allows equality comparison of two JSON values (however complex) according to the JSON Schema definition of equality.

Freeze/thaw

The two interfaces, Frozen and Thawed, provide a contract whereby any frozen value may provide a "thawed", mutable version of itself, and any thawed value may provide a "frozen", immutable version of itself.

json-schema-validator makes heavy use of this paradigm -- and this is the main reason why it is thread safe: all processors use immutable, frozen instances at initialization time.

In this package, one utility class uses this paradigm: Dictionary (frozen) and DictionaryBuilder (thawed).

Copyright © 2013. All Rights Reserved.