jsonx-maven-plugin

JSONx Maven Plugin

JSON Schema for the enterprise

Abstract

This document specifies the JSONx Maven Plugin, which offers facilities for for generating JSONx and JSD bindings with the JSONx Runtime API.

Table of Contents

  1 Introduction
    1.1 Conventions Used in This Document
  2 Purpose
  3 Requirements
  4 Getting Started
  5 Specification
    5.1 Goals Overview
    5.2 Usage
       5.2.1 jsonx:generate
          5.2.1.1 Configuration Parameters
          5.2.1.2 Example
       5.2.2 jsonx:convert
          5.2.2.1 Configuration Parameters
          5.2.2.2 Example
       5.2.3 jsonx:validate
          5.2.3.1 Configuration Parameters
          5.2.3.2 Example
  6 Contributing
  7 Special Thanks
  8 License

1 Introduction

The jsonx-maven-plugin plugin is used to generate JSONx and JSD bindings with the JSONx Framework for Java.

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 schema validation, code generation, and other convenience utlities in a Maven plugin.

3 Requirements

1. The JSONx Maven plugin MUST offer utilities for the generation of binding classes from a specified schema document.

2. The JSONx Maven plugin MUST offer utilities for validation of schema documents and binding classes.

3. The JSONx Maven plugin MUST present clear and informative errors and warnings that arise during parsing and validation of schema documents and JSON documents with an associated schema.

4 Getting Started

The JSONx Maven Plugin implements a Maven MOJO that can be used in a pom.xml. The following illustrates an example usage.

<plugin>
  <groupId>org.jsonx</groupId>
  <artifactId>jsonx-maven-plugin</artifactId>
  <version>0.4.0</version>
  <executions>
    <execution>
      <goals>
        <goal>generate</goal>
      </goals>
      <phase>generate-sources</phase>
      <configuration>
        <destDir>${project.build.directory}/generated-sources/jsonx</destDir>
        <namespacePackages>
          <namespacePackage package="com.example.json."/>
        </namespacePackages>
        <schemas>
          <schema>src/main/resources/schema.jsd</schema> <!-- or schema.jsdx -->
        </schemas>
      </configuration>
    </execution>
  </executions>
</plugin>

5 Specification

5.1 Goals Overview

• jsonx:generate generates Java binding sources from JSD or JSDx schemas.
• jsonx:convert converts JSD schemas to JSDx, and vice versa.
• jsonx:valdate validates JSD and JSDx schemas.

5.2 Usage

5.2.1 jsonx:generate

The jsonx:generate goal is bound to the generate-sources phase, and is used to generate Java binding sources for JSD or JSDx schemas specified in the configuration.

5.2.1.1 Configuration Parameters

Name	Type	Use	Description
/destDir¹	String	Required	Destination path of generated bindings.
/namespacePackages¹	List	Optional	List of namespacePackage elements.
/namespacePackages/namespacePackageⁿ	String	Optional	Package prefix to be prepended to the class names of generated bindings. The value represents a: Package name if it ends with an unescaped . character. Declaring class name if it ends with an unescaped $ character.
/schemas¹	List	Required	List of schema elements.
/schemas/schemaⁿ	String	Required	File path or URL of JSD or JSDx schema.

5.2.1.2 Example

<plugin>
  <groupId>org.jsonx</groupId>
  <artifactId>jsonx-maven-plugin</artifactId>
  <version>0.4.0</version>
  <executions>
    <execution>
      <phase>generate-sources</phase>
      <goals>
        <goal>generate</goal>
      </goals>
      <configuration>
        <destDir>${project.build.directory}/generated-sources/jsonx</destDir>
        <namespacePackages>
          <namespacePackage package="com.example.json."/>
        </namespacePackages>
        <schemas>
          <schema>src/main/resources/schema1.jsd</schema>
          <schema>src/main/resources/schema2.jsdx</schema>
        </schemas>
      </configuration>
    </execution>
  </executions>
</plugin>

5.2.2 jsonx:convert

The jsonx:convert goal is bound to the generate-resources phase, and is used to convert JSD schemas to JSDx, and vice versa.

5.2.2.1 Configuration Parameters

Name	Type	Use	Description
/destDir¹	String	Required	Destination path of converted schemas.
/schemas¹	List	Required	List of schema elements.
/schemas/schemaⁿ	String	Required	File path or URL of JSD or JSDx schema.

5.2.2.2 Example

<plugin>
  <groupId>org.jsonx</groupId>
  <artifactId>jsonx-maven-plugin</artifactId>
  <version>0.4.0</version>
  <executions>
    <execution>
      <phase>generate-resources</phase>
      <goals>
        <goal>convert</goal>
      </goals>
      <configuration>
        <destDir>${project.build.directory}/generated-resources/jsonx</destDir>
        <schemas>
          <schema>src/main/resources/schema1.jsd</schema>
          <schema>src/main/resources/schema2.jsdx</schema>
        </schemas>
      </configuration>
    </execution>
  </executions>
</plugin>

5.2.3 jsonx:validate

The jsonx:validate goal is bound to the compile phase, and is used to validate JSD or JSDx schemas.

5.2.3.1 Configuration Parameters

Name	Type	Use	Description
/schemas¹	List	Required	List of schema elements.
/schemas/schemaⁿ	String	Required	File path or URL of JSD or JSDx schema.

5.2.3.2 Example

<plugin>
  <groupId>org.jsonx</groupId>
  <artifactId>jsonx-maven-plugin</artifactId>
  <version>0.4.0</version>
  <executions>
    <execution>
      <phase>generate-resources</phase>
      <goals>
        <goal>validate</goal>
      </goals>
      <configuration>
        <destDir>${project.build.directory}/generated-resources/jsonx</destDir>
        <schemas>
          <schema>src/main/resources/schema1.jsd</schema>
          <schema>src/main/resources/schema2.jsdx</schema>
        </schemas>
      </configuration>
    </execution>
  </executions>
</plugin>

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.