generator

JSONx Binding Generator

JSON Schema for the enterprise

Abstract

This document specifies the JSONx Binding Generator, which offers facilities for generating Java binding classes from a JSD schema.

Table of Contents

  1 Introduction
    1.1 Conventions Used in This Document
  2 Purpose
  3 Requirements
  4 Getting Started
    4.1 Generator
    4.2 Converter
  5 Specification
    5.1 Generator
    5.2 Converter
  6 Contributing
  7 Special Thanks
  8 License

1 Introduction

This document presents the functionality of the JSONx Binding Generator. It also contains a directory of links to related resources.

The JSONx Binding Generator consumes a JSD schema, and produces Java classes in the form of .java files. The generated classes have code that relies on the JSONx Runtime API to achieve binding between JSON documents conforming to a JSD schema, and Java object represetations of these documents.

1.1 Conventions Used in This Document

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119.

2 Purpose

Provide a binding generator utility for automatic generation of binding classes from a schema document.

3 Requirements

1. The binding generator MUST be able to consume a schema document, and produce Java class definitions (.java files) that use the runtime API.

2. The binding generator MUST be able to consume Java class definitions (.class files) utilizing the runtime API, and produce a schema document.

3. The binding generator MUST create Java classes (.java files) that encode the full normative scope of the schema document.

4. The binding generator MUST represent the constituent parts of a schema document with Java type bindings that are as strongly-typed as possible, but not limiting in any way with regard to the definition of the respective constituent part.

5. The binding generator MUST be able to validate a schema document.

4 Getting Started

The JSONx Binding Generator provides convenience utilities for generating bindings and converting schema documents. The following illustrates example usage of the Generator and Converter executable classes.

4.1 Generator

The following example generates binding classes (.java files) in target/generated-sources/jsonx for the schema document at src/main/resources/example.jsd, with package prefix org.example$.

java -cp ... org.jsonx.Generator -p org.example$ -d target/generated-sources/jsonx src/main/resources/example.jsd

4.2 Converter

The following example converts the JSD file at src/main/resources/example.jsd to a JSDx file in target/generated-resources.

java -cp ... org.jsonx.Converter src/main/resources/example.jsd target/generated-resources/example.jsdx

5 Specification

The JSONx Binding Generator generates Java binding classes. The generated classes contain the full scope of specification of the JSD schema from which they are generated. This means that the generated classes can be converted back to the JSD from which they were created, and the normative scope of the schema will be preserved.

A distinction has to be made between "normative scope" and "non-normative scope". When referring to a JSD schema, the term "normative scope" represents the structural scope, which isolates the part of the schema document that defines validation criteria for facets of JSON documents. The term "non-normative scope" includes the information in the JSD schema that does not have significance unto the validation for facets of JSON documents. An example of a "non-normative scope" is the name of a <string name="someName" ...> type as the root element of the schema. The JSONx Binding Generator discards this information when creating the Java binding classes.

5.1 Generator

The Generator is a utility class that can be used on the CLI to generate Java binding classes from a JSD schema. The Generator class has the following usage specification:

Usage: Generator <-p [NAMESPACE] PACKAGE>... <-d DEST_DIR> <SCHEMA.jsd|SCHEMA.jsdx|BINDING.jsb|BINDING.jsbx>...
  -p [NAMESPACE] <PACKAGE>  Package prefix of generated classes for provided namespace, recurrable.
  -d <DEST_DIR>             The destination directory.

Supported SCHEMA_FILE formats:
                 <JSD|JSDx|JSB|JSBx>

5.2 Converter

The Converter is a utility class that can be used on the CLI to convert JSD files to JSDx, and vice versa. The Converter class has the following usage specification:

Usage: Converter <SCHEMA_IN.jsd|SCHEMA_IN.jsdx> [SCHEMA_OUT.jsd|SCHEMA_OUT.jsdx]
            (or) <BINDING_IN.jsb|BINDING_IN.jsbx> [BINDING_OUT.jsb|BINDING_OUT.jsbx]

Supported SCHEMA_IN|OUT formats:
                 <JSD|JSDx|JSB|JSBx>

If a SCHEMA_OUT argument is not provided, the Converter will output the converted content to stdout.

6 Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

7 Special Thanks

_{Special thanks to EJ Technologies for providing their award winning Java Profiler (JProfiler) for development of the JSONx Framework.}

8 License

This project is licensed under the MIT License - see the LICENSE.txt file for details.