Difference between revisions of "EclipseLink/Development/404452"

From Eclipsepedia

Jump to: navigation, search
(Known Issues/Bugs)
(Known Issues/Bugs)
Line 237: Line 237:
 
*BinaryData/BinaryDataCollectionMapping
 
*BinaryData/BinaryDataCollectionMapping
 
*XmlInverseReferenceMapping (see org.eclipse.persistence.testing.jaxb.annotations.xmlcontainerproperty.ContainerPropertyTestCase)
 
*XmlInverseReferenceMapping (see org.eclipse.persistence.testing.jaxb.annotations.xmlcontainerproperty.ContainerPropertyTestCase)
 +
*[https://bugs.eclipse.org/bugs/show_bug.cgi?id=410658 Bug 410658] JSON_INCLUDE_ROOT property defaults to true

Revision as of 16:04, 12 June 2013

Contents

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
}

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"
      }
    },
    "address": {
      "type":"object",
      "properties": {
        "street": {
          "type":"string"
        },
        "city": {
          "type":"string"
        },
        "country": {
          "type":"string"
        }
      }      
    },
    "phoneNumbers": {
      "type":"array",
      "items": {
        "type":"object",
        "properties": {
          "areaCode": {
            "type":"string"
          },
          "number": {
            "type":"string"
          }
        }
      }      
    },
    "department": {
      "enum":["dev", "support", "sales", "qa"]
    }
  },
  "required": ["id"]
}

Phase 4 - Additional Mappings and Properties

Any additional mappings not supported by Phase III will be added during this phase. Also, there are some Json Specific marshal properties which can have an effect on the generation of the schema. These will be handled by this phase of the development.

JSON Marshaller Properties:

  • JSON_ATTRIBUTE_PREFIX - This property sets a prefix to be prepending to attributes. In a JSON Schema, any properties that are generated from fields mapped with @XmlAttribute should have this prefix prepended.
  • JSON_INCLUDE_ROOT - This property indicates that a root specified by @XmlRootElement should be included in the marshalled json document. If this is set to true, then the generated json schema will also have to contain the root .
  • JSON_REDUCE_ANY_ARRAYS - This property won't effect the generation of the schema
  • JSON_MARSHAL_EMPTY_COLLECTIONS - This property only effects marshalling and won't have an effect on the schema.
  • JSON_VALUE_WRAPPER - This specifies a property name to be used for anything mapped with an XmlValue annotation. This will be included in the schema for DirectMappings with the xpath "text()"
  • NAMESPACE_PREFIX_MAPPER & JSON_NAMESPACE_SEPARATOR - If both of these are set then namespace processing will be enabled, and property names will be prepended with the prefix corresponding to their namespace.

Known Issues/Bugs

  • Bug 410638 CompositeMapping with no reference descriptor causes NPE
  • Cyclic references ie: Employee has a List<Employee> causes infinite loop
  • @XmlValue annotation (see org.eclipse.persistence.testing.jaxb.xmlidref.XmlIdRefTestCases)
  • XmlVariableXPathObjectMapping/XmlVariableXPathCollectionMapping
  • XmlObjectReferenceMapping/XmlCollectionReferenceMapping
  • AnyObject/AnyCollectionMapping
  • BinaryData/BinaryDataCollectionMapping
  • XmlInverseReferenceMapping (see org.eclipse.persistence.testing.jaxb.annotations.xmlcontainerproperty.ContainerPropertyTestCase)
  • Bug 410658 JSON_INCLUDE_ROOT property defaults to true