Reference: OASIS JIRA entry SRAMP-1
Description
"Someone needs to review the documents and evaluate the relationships that are described in the text and the tables. Especially the table in Appendix E of the Foundation Document. The determination needs to be made whether or not the XML Schemas as they exist completely describe those relationships or if we need to make modifications to the schemas to more completely define the relationship or if we need to find an other mechanism altogether to define the relationships. This was Issue-001 from the contributed issues document.
The relationships as described in the Foundation Document may or may not be able to be fully represented in schema. The relationships need to be looked in to and evaluated to make sure that all relationships defined in the foundation document and possibly the atom document can be properly described in the XML Schemas. If they can not be properly described then we may need to explore other mechanism to better model these relationships."
Background
The foundation document contains UML diagrams specifying relationships between the various artifacts. For example the core model is represented by figure 1.
Figure 1. Core Model UML as shown in the Foundation Document Specification Document.
Note the relationship named ‘relatedDocument’ between DerivedArtifactType and DocumentArtifactType. This specifies that the DerivedArtifactType can have a reference to a DocumentArtifactType. The coremodel.xsd models this relationship using a Target element, where that target element is defined as a complexType with a String value with any number of attributes:
<xsd:complexType name="target">
<xsd:simpleContent>
<xsd:extension base="xsd:string">
<xsd:anyAttribute namespace="##any" />
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
Figure 2. Definition of the target element.
the atom-binding document shows a valid XML fragment, where ‘aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaa6b’ is a reference to a uuid value of a XsdDocument in this case. Also it contains one attribute ‘href’ in the ‘xlink’ namepace.
<s-ramp:target xlink:href="http://example.org/s-ramp/xsd/XsdDocument/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaa6b">
aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaa6b
</s-ramp:target>
Figure 3. XML Fragment of a target.
It must be noted that the target objects only specifies the value of the uuid, and the href. This data only captures the UML relationship by convention, and it is by no means an object relation, or typed relation.
Now we generate Java objects from the given xsd and then generate the UML representation from the Java objects.
Figure 4. Generated UML (based on Java objects which where generated from the core-model.xsd).
When looking at Figure 4 it is clear that there is a relationship from ‘DerivedArtifactType’ to ‘Target’ but as expected the object model does not capture the relation from ‘Target’ to ‘DocumentArtifactType’.
Statement of the problem
The ‘target’ element in the xml schemas is capable of modelling references to ArtifactTypes, but the relation is based on UUID reference only (and an additional href when using atom bind). The xsds themselves do not express the relationships.
Proposed Solution
In order for the xml schemas to express the relationships we propose to add a required ‘artifactType’ attribute to Target which would contain the type of artifact the value (uuid) is referencing. The artifactType would be of type ‘Enumeration’. The artifactType enumeration would be a list of all possible artifacts that Target is allowed to reference. Furthermore since the different Target relationships only allow a subset of enumerations we’d create different enumerated lists to go with each Target.
Simplified core model
Let’s try to visualize the above with a simplified core-model, which only contains the Base-, Derived- and Document-Artifact Types, as well as the generic Target element. Check the The simplified simplified core model XML Schema on the oasis-spec-s-ramp-1 branch. When we generate the Java objects and the UML from those objects we get the schematic show in Figure 5.
Figure 5. UML diagram of the simplified core model.
Simplified core model with artifactType attributes.
We now enhance the simple coremodel. The XML Schema is called coremodel.typed. We add two enumerations; baseArtifactEnum and documentArtifactEnum:
<xsd:simpleType name="baseArtifactEnum" >
<xsd:restriction base="xsd:string">
<xsd:enumeration value="BaseArtifactType" />
<xsd:enumeration value="DocumentArtifactType" />
<xsd:enumeration value="DerivedArtifactType" />
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="documentArtifactEnum">
<xsd:restriction base="s-ramp:baseArtifactEnum">
<xsd:enumeration value="DocumentArtifactType" />
</xsd:restriction>
</xsd:simpleType>
Figure 7. Two new enumerations; baseArtifactEnum and documentArtifactEnum.
Also we add an attributeType attribute to all ArtifactType definitions and we create a new DocumentArtifactTarget. DocumentArtifactTarget extends Target and is defined in Figure 8.
<xsd:complexType name="documentArtifactTarget">
<xsd:simpleContent>
<xsd:extension base="xsd:string" >
<xsd:attribute name="artifactType" type="s-ramp:documentArtifactEnum" />
<xsd:anyAttribute namespace="##any" />
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
Figure 8. A new documentArtifactTarget which contains an artifactType attribute of type ‘documentArtifactEnum’.
When generating the Java objects and the UML from that we get the diagram shown in Figure 9.
Figure 9. Generated UML using the typed core model version.
The UML diagram of Figure 9 now show the relation between DocumentTypeTarget and DocumentArtifact. When writing Java code, in this case the Enumeration only shows ‘DocumentArtifactEnum’, as shown in Figure 10.
Figure 10. DocumentArtifactEnum options only lists the DocumentArtifactType.
Conclusion
Using the Enumerations and the Typed Target Element seem to create the relationship specified in the UML quite well. It also provides a convenient coding model and it will reduce the ambiguity of the content of the Target element. This change has been applied across the s-ramp xsds. The new schemas are checked into the oasis-spec-s-ramp-1 branch.
I'd love to hear your feedback! Cheers, --Kurt