diff --git a/README.md b/README.md
index 0d0693895c5fd4d16691a436258bc153b602d626..4f895e0f5dcc1f3da08162bf6de75d0072638f43 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,13 @@
# VOSpace Data Model
+Java classes used for modelling VOSpace entities are used both by REST web service and UI application, so they are kept in a separate software module called VOSpace Data Model:
+
+
+
+The main goal of this shared library is to provide a binding between Java classes and XML defined by the VOSpace standard. We are also using `jackson-module-jaxb-annotations` to support both XML and JSON binding. Our REST service supports also JSON payloads (Spring Framework performs content negotiation based on HTTP Accept header).
+
+Some utility methods for extracting information from nodes have also been added.
+
## Generating beans from XML schema
cd xsd
@@ -11,45 +19,48 @@ It seems that xjc does something wrong when retriving the imported XSD from the
In vospace.xsd:
- <xsd:import namespace="http://www.ivoa.net/xml/UWS/v1.0" schemaLocation="./uws.xsd"/>
+```xml
+<xsd:import namespace="http://www.ivoa.net/xml/UWS/v1.0" schemaLocation="./uws.xsd"/>
+```
In uws.xsd:
- <xs:import namespace="http://www.w3.org/1999/xlink" schemaLocation="./xlink.xsd"/>
+```xml
+<xs:import namespace="http://www.w3.org/1999/xlink" schemaLocation="./xlink.xsd"/>
+```
### Changes to the generated classes
-In package-info.java the following element has been added to serialize the XML keeping the namespace.
-
- xmlns = {
- @javax.xml.bind.annotation.XmlNs(
- namespaceURI = "http://www.ivoa.net/xml/VOSpace/v2.0",
- prefix = "vos"
- )
- }
+#### Namespaces issues
-Some issues emerged in handling inheritance and namespaces in a way compatible both to JSON and XML formats. Moreover it was necessary to setup a workaround for filling the `xsi:type` of the root node:
+In package-info.java files some `@javax.xml.bind.annotation.XmlNs` annotations have been added to serialize the XML keeping the namespaces (vos, xsi, xlink, uws).
-In Node.java type field and removeType() method have been added:
+To handle the `vos:` prefix in JSON a custom type id resolver (`NodeTypeJsonResolver`) has been added to the `Node` class.
- // Used for generating missing type attribute for root node. For child nodes it is filled automatically.
- @XmlAttribute(name = "type", namespace = "http://www.w3.org/2001/XMLSchema-instance", required = false)
- private String type;
+#### Type attribute issue
- /* This method exists to fix the issue with type attribute. See RemoveDuplicateTypeAdapter class. */
- public void removeType() {
- this.type = null;
- }
+JAXB automatically generates the `xsi:type` attribute, however it doesn't fill it for the root node (it seems that this is by design). Since we need it, we manually added it on the `Node` class, but this caused a duplication of the attribute in the children nodes. So we added a `removeType()` method that sets it to null. This method is called by a custom adapter (`RemoveDuplicateTypeAdapter`) during the marshalling of the node.
-For JSON compatibility the following has been added to Node.java (annotation on class):
+#### JSON inheritance
- @JsonTypeInfo(use = JsonTypeInfo.Id.CUSTOM, property = "type", include = JsonTypeInfo.As.EXISTING_PROPERTY)
- @JsonTypeIdResolver(NodeTypeJsonResolver.class)
+The `@JsonTypeInfo` annotation has been added to the `Node` class for telling to Jackson that the field type is used to handle inheritance.
-The `@JsonTypeInfo` tells to Jackson that the field type is used to handle inheritance. A custom type id resolver has been created to handle the `vos:` prefix.
+#### Root element tag name
2 annotations have been added to each node subtype:
- @XmlRootElement(name = "node")
+```java
+@XmlRootElement(name = "node")
+```
+
+`@XmlRootElement` is necessary to parse single nodes. The value `"node"` has been specified because by default the bean would be serialized as `<unstructuredDataNode>` or `<containerNode>` and so on.
+
+#### Handling generic type in JobInfo content
+
+`JobSummary` class has a `jobInfo` field that is a generic object (since it is the payload of UWS jobs). In the case of VOSpace the `jobInfo` is an instance of `Transfer`. To properly serialize this object the following annotation has been added to the `JobSummary` class:
+
+```java
+@XmlSeeAlso({Transfer.class})
+```
-`@XmlRootElement` is necessary to parse single nodes. The value `"node"` has been specified because by default the bean would be serialized as `<unstructuredDataNode>`.
+Moreover custom JSON serializer and deserialized have been added on the `JobInfo` class.
diff --git a/vospace-datamodel.jpg b/vospace-datamodel.jpg
new file mode 100644
index 0000000000000000000000000000000000000000..6e67a71b74a3d572cae1031f813f9f16de764199
Binary files /dev/null and b/vospace-datamodel.jpg differ