27 November 2015

The production process

A diagrammatic representation of the conceptual production process.

The version shown is that current at the Copenhagen Sprint in November 2015

Outstanding work to implement this are:

Completion of export of class level documentation from Drupal in reStructuredText [3]
Specification and export of inline class level documentation from Drupal in Markdown [1,2]
Transformation of inline class level documentation from Markdown to HTML [6,7]
Formatting of PDF to publication quality standard
Specification and generation of convenience RDFS/OWL “schemas”

Review of RDFS/OWL schema definition

Model Creation and Documentation

A collaboration platform for the development of the DDI Model enables all contributors to work in a common working environment, this is currently implemented in Drupal and is hosted at www.lion.ddialliance.org.

The model contains a Library and Functional Views. The Library is composed of Library Packages which contain other data types (primitives or complex) or classes. The Functional Views contain references to the classes used by the particular Functional View that are needed to meet the needs of the use case or business application. Further information on this is available at [http://ddi4.readthedocs.org/en/latest/Introduction/modeldesc.html]

All changes are versioned and the model is output on nightly builds. Documentation relating to classes, their properties and relationships are also captured in the collaboration platform.

Production Process Outputs

The final outputs of the production process are Annotated Representations of the model initially in two implementations, XSD and OWL and documentation of each class in the model and relevant contextual information, uses cases and usage of the Functional Views.

Platform Independent Model (PIM)

The PIM is a UML model expressed as an XML Metadata Interchange (XMI) file [add in reference to specification / flavour etc]. This is the canonical expression of the model from which all transformations into different representations (XSD, RDFS/OWL, etc) are generated. The PIM will contain inline documentation (in Markdown) covering class, property and relationship information

Platform Specific Model (PSM)

The Platform Specific Model is the result of the first transformation of the PIM. The transformation modifies the model through a set of design rules which are implemented in the next transformation into the specific representations (XSD, OWL, etc).

The main design decisions are outlined below for each representation. Detailed explanations including validation criteria are contained in the XML Binding Specification and Validation [link] and RDFS/OWL Binding Specification and Validation [link] documents.

Flattening

For the XML and the RDFS/OWL representations, the PIM is flattened. This was originally proposed at the Minneapolis Sprint in 2015. This is a process whereby abstract classes and their contents are removed and passed down the chain of inheritance to the first non-abstract class. In the XML representation, the empty abstract class is retained, whilst in the RDFS/OWL representation it is removed.

PIM

PSM (XML)

PSM (RDFS/OWL)

Class A (abstract)

p

q

r

Class A (abstract)

Class B (not abstract)

extension base Class A

x

y

z

Class B (not abstract)

x

y

z

p

q

r

Class B (not abstract)

x

y

z

p

q

r

Class C

a

b

c

Class C

a

b

c

Class C

a

b

c

Example PSM XML

<?xml version="1.0" encoding="UTF-8"?>

<xmi:XMI xmlns:uml="http://www.omg.org/spec/UML/20110701"

xmlns:xmi="http://www.omg.org/spec/XMI/20110701"

xmi:version="">

<xmi:Documentation exporter="Enterprise Architect" exporterVersion="6.5"/>

<uml:Model xmi:type="uml:Model" xmi:id="42" name="ddi4">

<packagedElement xmi:type="uml:Package"

xmi:id="ddi4_model"

name="Class Model (Exported from Drupal)">

<packagedElement xmi:type="uml:Package"

xmi:id="ComplexDataTypes"

name="ComplexDataTypes">

. . .

</xmi:XMI>

Example PSM RDFS/OWL

<?xml version="1.0" encoding="UTF-8"?>

<xmi:XMI xmlns:uml="http://www.omg.org/spec/UML/20110701"

xmlns:xmi="http://www.omg.org/spec/XMI/20110701"

xmi:version="2.4.1">

<!--

NOTE: exporter have to be "Enterprise Architect", EA wont read it if set do eg. Drupal

We will play along to get "Enterprise Architect" happy

-->

<xmi:Documentation exporter="Enterprise Architect" exporterVersion="6.5"/>

<uml:Model xmi:type="uml:Model" xmi:id="42" name="ddi4">

<packagedElement xmi:type="uml:Package"

xmi:id="ddi4_model"

name="Class Model (Exported from Drupal)">

<packagedElement xmi:type="uml:Package"

xmi:id="ComplexDataTypes"

name="ComplexDataTypes">

. . .

</xmi:XMI>

Schema Structure

For both the XML and the RDFS/OWL representations there will be two types of output. A normative Schema for the entire model, and a Convenience Schema for each Functional View. This decision was taken at the Dagstuhl 2015 sprint and refined at the Copenhagen Sprint in 2015. The detailed design decisions for XML are expected to be stable, detailed design decisions for RDFS/OWL are provisional pending review by experts in this field.

Versioning

The temporary solution to versioning the releases is (as was the case with 2015 Q1 release, to time stamp the publishing version. Other solutions are under discussion, but need to be made in the context of the use case of release and re-release of draft outputs, the interaction between the various components of that release and the software development costs of implementing the solution.

XML Representation (annotated)

The main output will be an XML schema that describes the entire model (the normative scheme). Additional convenience schemas will also be produced for each Functional View. The Markdown documentation will be converted to HTML.

Normative Schema (Entire Model)

The general idea is, to have a general root element that is defined to contain instances of an overall view element, which will then contain all DDI elements designed in the model. The entire model library will be produced in one single (version based) namespace.

Example XML

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns="urn:ddi.org:4"

xmlns:xs="http://www.w3.org/2001/XMLSchema"

xmlns:vc="http://www.w3.org/2007/XMLSchema-versioning"

xmlns:xhtml="http://www.w3.org/1999/xhtml"

targetNamespace="urn:ddi.org:4"

elementFormDefault="qualified"

attributeFormDefault="unqualified"

vc:minVersion="1.1">

<xs:import namespace="http://www.w3.org/XML/1998/namespace"

schemaLocation="xml.xsd"/>

<xs:import namespace="http://www.w3.org/1999/xhtml"

schemaLocation="ddi-xhtml11.xsd"/>

<xs:complexType name="DDIType">

<xs:annotation>

<xs:documentation/>

</xs:annotation>

. . .

</xs:complexType>

</xs:schema>

Convenience Schema (Functional Views)

A functional view contains a subset of the Normative Schema, within the same namespace.

Example XML

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns="urn:ddi.org:4"

xmlns:xs="http://www.w3.org/2001/XMLSchema"

xmlns:vc="http://www.w3.org/2007/XMLSchema-versioning"

xmlns:xhtml="http://www.w3.org/1999/xhtml"

targetNamespace="urn:ddi.org:4"

elementFormDefault="qualified"

attributeFormDefault="unqualified"

vc:minVersion="1.1">

<xs:import namespace="http://www.w3.org/XML/1998/namespace"

schemaLocation="xml.xsd"/>

<xs:import namespace="http://www.w3.org/1999/xhtml"

schemaLocation="ddi-xhtml11.xsd"/>

<xs:complexType name="DDIType">

<xs:annotation>

<xs:documentation/>

</xs:annotation>

. . .

</xs:complexType>

</xs:schema>

RDFS/OWL Representation (annotated)

The main output will be an RDF Schema/OWL Model that describes the entire model (the normative scheme). Additional convenience “schemas” will also be produced for each Functional View. The documentation will be converted from Markdown to HTML.