Wednesday, March 21, 2012

Representing Relationships in S-RAMP

I just finished work on capturing the relations specified in the UML in the S-RAMP xsds. I added an 'artifactType' to the Target element.

Reference: OASIS JIRA entry SRAMP-1


"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."


The foundation document contains UML diagrams specifying relationships between the various artifacts. For example the core model is represented by figure 1.

core model uml

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:extension base="xsd:string">
            <xsd:anyAttribute namespace="##any" />

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="">

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.

core model generated UML

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.

simple core model uml

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:simpleType name="documentArtifactEnum">
  <xsd:restriction base="s-ramp:baseArtifactEnum">
    <xsd:enumeration value="DocumentArtifactType" />

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:extension base="xsd:string" >
            <xsd:attribute name="artifactType" type="s-ramp:documentArtifactEnum" />
            <xsd:anyAttribute namespace="##any" />

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.

simple core model uml typed

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.


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

Monday, May 9, 2011

Great Governance JUDCon session

Our Governance presentation at JUDCon was very well attended! People were very excited to see the direction in which we are moving, as well as to see the added value of using ModeShape as the JCR implementation. The slide deck is published here. It is really good to know that so many people care about Governance. Thank you for all the positive feedback and we are looking forward seeing you become part of the Guvnor community!



Tuesday, March 15, 2011

Governing services, data, rules, processes and more

Get ready to get to Boston for JUDCON on May 2-3, 2011. Randall Hauch and myself will talk about how Guvnor is being reborn so that it can manage artifacts from a variety of domains, including web services, data services, business rules and processes, and metadata management. Guvnor not only will storing these artifacts, but it will fully manage their lifecycle, enable search and discovery, and provide insight into how, when and where they can be used. They'll also describe Guvnor's architecture and use of JCR, REST, GWT, Atom, and S-RAMP.



Friday, March 11, 2011

AtomPub Interface for Guvnor

Nice post about by Andrew Waterman about a contribution he made to Guvnor.

Andrew: "Over the last 6 months, I have been working to make our newer games more open to changes and modifications by players on the ground and in realtime. To do this, I have implemented our latest game so it’s rules and object models are hosted by the Guvnor."

See here for the entire article.

Thank you Andrew!

Tuesday, March 1, 2011

Splitting up into smaller git repositories and smaller builds

A first step to split out guvnor as a generic governance framework! Well done Geoffrey!

Open Source Governance: Guvnor

Welcome to Guvnor Project: Open Source Governance. The Guvnor Project is building an Governance Repository Application which enables you to govern and manage artifacts, such as rule and process definitions, service descriptions, databases schemas, etc. The Drools team has been working on Drools-Guvnor for a few years now and it has proven its value. The Guvnor project works to introduce a more generic governance application framework so that other artifacts (like service artifacts) can be governed and maintained in this repository. This project collaborates highly with other projects in particular the other Overlord projects as well as Drools and ModeShape.

The Guvnor Team