Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

org.brutusin:json Build Status Maven Central Latest Version

org.brutusin:json is a service provider interface (SPI) that aggregates all the JSON-related functionality needed by the rest of Brutusin modules.

This module defines the general contract required to any implementing JSON service provider, allowing to use different pluggable implementations and decoupling client modules from them.

Table of Contents:

Maven dependency


Click here to see the latest available version released to the Maven Central Repository.

If you are not using maven and need help you can ask here.


JsonCodec is the single entry point to the framework. It defines a SPI (service provider interface) that is implemented by pluggable service providers. Clients of the service make use of it by calling:


JsonCodec provides three types of operations: Data operations (inherited from JsonDataCodec), schema operations (inherited from JsonSchemaCodec) and path expression operations (via compile(String expression))

Class diagram


Data methods declared in JsonDataCodec offer Object/JSON binding (get JSON representations from objects and object tree instantiation from JSON data) and a generic API to interact with JSON data in a generic way (JsonNode).

JSON Schema

A JSON schema (specifications) is a JSON document that describes the structure of other JSON documents.

Schemas are represented by the interface JsonSchema, and instantiated by the methods in JsonSchemaCodec, either by parsing the JSON Schema document (parseSchema(String json)) and by reflection from a Class instance (getSchema(Class<T> clazz)).

This module adheres to the JSON schema specification defined in


Schemas are useful both for describing the structure and for validating JsonSchema.validate(JsonNode node) that JSON data complies the constraints imposed by them.

Path expressions

See extension specification.

See ExpressionTest for some examples.

Java Annotations

Schema generation annotations

The following annotations can be used to customize schema generation, and must be supported by all providers:

Standard schema properties

  • @JsonProperty. Lets specify standard schema properties like required, default, enum, title, description,...

Custom schema properties

  • @IndexableProperty. Adds custom "index":"index" or "index":"facet" properties to the schema generated.
  • @DependentProperty. Adds custom "dependsOn":<property name array> properties to the schema generated.

Streaming API

This SPI supports binary attachments in JSON data, a feature that enables serialization/deserialization of properties of type InputStream or MetaDataInputStream.

JsonStreamCodec declares the SPI functionality related with binary attachments.

Service Providers

Service providers are modules implementing this SPI and registering themselves via the ServiceLoader standard facility.

JUnit tests for implementing providers

All service providers must pass the JUnit tests included in this module. In order to that, the following maven dependence has to be included


and predefined tests have to be extended by the service provider tests.

Reference implementation

See org.brutusin:json-provider for a reference implementation.


  • Standard annotations also for data binding (not only for schema customization), supporting property ordering, ignoring properties...
  • Since annotation inheritance is not allowed in java, introduce some mechanism for schema extension (allowing non-standard schema properties) to be used by the service providers. This also would help to move @IndexableProperty (aimed at being used by org.brutuisn:flea-db) and @DependentProperty out of this module.
  • Path expressions: Add more features similar to those in XPath like:
    • Filters
    • Functions

See also

Support bugs and requests


Contributions are always welcome and greatly appreciated!


Apache License, Version 2.0


JSON SPI, supporting schemas, validation, projections, path expressions..







No packages published