Revision as of 14:34, 26 April 2013

Planning: MOXy JSON Schema Generation

ER 404452

Currently EclipseLink supports generating XML Schemas from a JAXBContext. A feature will be added to generate JSON Schemas. At first this feature will be based on JAXB metadata and mappings, in the future this will be adapted to JSON-B metadata.

Phases

The development of this feature will need to be split into multiple phases. The current EclipseLink JSON support is insufficient to map to a json schema document. Additional enhancements will be required in order to generate these schemas.

Phase 1: Additional Mapping Support

JSON Schemas in several places specify collections of data where the name of the element corresponds to a property in the object. This is something that is not currently supported by eclipselink's oxm/json binding layer. This would require adding support

Example:

Mapping the list of properties on a schema. The name of the property is the key (or element) in the json schema, so this would require a variable-path mapping of some sort:

{
  ...
  {"properties": {
      "firstName":{"type":"string"},
      "lastName":{"type":"string"}
  }
}

Would need to be mapped to:

public class Schema {
  ...
  List<Property> properties;
}

public class Property {
  String name;
  String type;
}

Where name maps to the key/element name of the property entry.

More details on the new mapping described  here

Phase 2 - Basic Schema

The second phase would be to generate a basic schema for a single class with simple properties. This will require the creation of an object model to represent the schema and the code to process an EclipseLink project consisting of Descriptors and Mappings and generate the schema model for that project.

This could be done partially in parallel with Phase 1. The Schema Model and the code to create the Schema Model from the EclipseLink mappings could be done in advance. Actually mapping the Schema Model to output the json schema would require the completion of Phase 1.

Sample Object Model to be supported by Phase 2:

public class Employee {
  private int id;
  private String firstName;
  private String lastName;
  private List<String> responsibilities;
 
  public int getId() {
    return id;
  }
 
  public String getFirstName() {
    return firstName;
  }
 
  public String getLastName() {
    return lastName;
  }
 
  public List<String> getResponsibilities() {
    return responsibilities;
  }
 
  public void setId(int id) {
    this.id = id;
  }
 
  public void setFirstName(String firstName) {
    this.firstName = firstName;
  }
 
  public void setLastName(String lastName) {
    this.lastName = lastName;
  }
 
  public void setResponsibilities(List<String> responsibilities) {
    this.responsibilities = responsibilities;
  }
}

Would generate the following Schema

{
  "title": "Employee",
  "type": "object",
  "properties": {
    "id": {
      "type":"integer"
    },
    "firstName": {
      "type": "string"
    },
    "lastName": {
      "type": "string"
    },
    "responsibilities": {
      "type":"array"
      "item": {
        "type":"string"
      }
    }
  }
  "required": ["id"]
}

Phase 3: More Complex Schemas

Phase 3 would be to begin including more complex concepts into the schema model and generation code. This would include multiple types (in the "definitions" section of the schema) and references to those types. Also concepts like nested schemas and referencing external schemas could be added here.

Sample Object Model to be supported by Phase 3:

public class Employee {
  int id;
  String firstName;
  String lastName;
  List<String> responsibilities;
  Address address;
  List<PhoneNumber> phoneNumbers;
  Department department;
}

public Class Address {
  String street;
  String city;
  String country;
}

public Class PhoneNumber {
  String areaCode;
  String number;
}

public enumeration Department {
  DEVELOPMENT, SUPPORT, SALES, QA
}

{
  "title": "Employee",
  "type": "object",
  "properties": {
    "id": {
      "type":"integer"
    },
    "firstName": {
      "type": "string"
    },
    "lastName": {
      "type": "string"
    },
    "responsibilities": {
      "type":"array"
      "item": {
        "type":"string"
      }
    },
    "address": {
      "$ref":"#/definitions/address"
    },
    "phoneNumbers": {
      "type":"array",
      "items": {
        "$ref":"#/definitions/phoneNumber"
      }
    },
    "department": {
      "enum":["dev", "support", "sales", "qa"]
    }
  },
  "required": ["id"],
  "definitions": {
    "address": {
      "type":"object",
      "properties": {
        "street": {
          "type":"string"
        },
        "city": {
          "type":"string"
        },
        "country": {
          "type":"string"
        }
      }
    }
    "phoneNumber": {
      "type":"object",
      "properties": {
        "areaCode": {
          "type":"string"
        },
        "number": {
          "type":"string"
        }
      }
    }
  }       
}