Reference Data development procedures

Introduction

The creation of Reference Data is very similar to any other modelling exercise. The procedures to be used are therefore similar to those for the collaborative development of information models. The basic concepts are:

• Each developer has control of their own work-space, which is an extension to the group work-space.
• Each Reference Data item goes through a process of increased consensus, level of stability and control.
• There is a defined development process to be followed including tasks such as creation, review, raising issues, agreeing resolutions and incorporating resolutions.
• Team members play various roles during the process (e.g. creator, reviewer).
• After the team processes are completed, the Reference Data must be agreed within the OASIS PLCS TC based on OASIS guidelines. Once that has occurred, then the OASIS standards-making process takes over.

The purpose of the PLCS DEX Reference Data is to add semantics to an already existing model, the AP239 Product Life Cycle Support schema. At the end of the day, adding semantics to that schema is the goal, not creating an isolated, green field ontology covering the scope of PLCS. It is also the case that some of the Reference Data is to be adopted and adapted from existing standards. Therefore, allowing different viewpoints on the same concepts in the AP239 schema needs to be taken into account. For these reasons, the RD development process defines the RD development steps within the context of DEX development. It is possible to define RD outside the scope of a DEX, however that task is expected to be more difficult until the point in time when the framework within which the RD must be created is mature and stable.

The guidelines spelled out in this document are not frozen. Continuous improvement in the Reference Data development process is expected as experience is gained. If at any point, the guidelines make the process unnecessarily cumbersome, they should be reviewed and modified accordingly.

These guidelines do not include those steps required by OASIS define a standard. The OASIS standards process states that the following:

• Before the TC can submit its Committee Draft to OASIS membership for review and approval as an OASIS Standard, the TC must conduct a public review of the work. The decision by the TC to submit the work for public review requires a majority vote. The review must be announced by the TC Administrator on the OASIS members mail list and optionally on other public mail lists. Review must take place for a minimum of 30 days, during which time no changes may be made to the document. Comments must be collected via the TC's archived public comment facility. The TC must record the comments received as well as the resolution of those comments.

RD development process

In this section, the concept of the steps involved is described first. Once the concepts are understood, then the specifics of managing the process and the OWL files involved are described. The tasks involved in the managing process should always be considered with the more conceptual step in mind.

While any conforming OWL software tool can be used to create Reference Data, to facilitate development within the PLCS TC, guidelines for the use of the Protégé Ontology Editor and its OWL plug-in software are described. Learn about the installation and usage of Protégé in the Software area of DEXlib.

The concepts

The basic steps involved in developing the PLCS standard Reference Data are as follows:

1. Once the subset of the PLCS schema to be used for a DEX is defined, then the scope of the required RD is known - the RD will be subclasses of the classifiable entity types included within the DEX. Additionally, the RD must be appropriate to the usage scenario of the DEX.
   ISSUE 1 : Two additional types of Reference Data are possible as follows.
   • RD Classes that overlap with, but are not strict subclasses of, the PLCS EXPRESS classes - an example from DODAF is the "To-Be" and "As-Is" temporal viewpoints that could classify both an Organization with a substructure and an Activity_method with a substructure.
   • RD Individuals that are not classes at all - an example is the ISO standard Country Codes such as 'UK' and 'SW' that are not classes but that are constraints on valid attribute values for PLCS entity instances in an exchange file. ISOCountryCode might be a Reference Data class applied to an identification_assignment where 'UK' is the 'id' attribute value.
2. Once the scope of the RD is identified, existing sources for RD (including the PLCS standard and non-standard RD) that may be adopted or adapted are investigated and the applicable RD is identified. If the existing RD does not satisfy the DEX requirements, then new RD must be created.
3. For each new or existing Class to be added to the RD, where it fits in the PLCS schema or an existing class of which it is a subclass must be identified. It is possible that a class may have more than one superclass, in other words multiple inheritance is allowed.
4. Given the superclass(es) and sibling classes of the class in question, the definition of the class is written such that its usage is clear and helps users decide when to use the class and when not to use the class.
5. The class is added to the developers ontology and the tasks involved in managing the process are applied. Each class must also have the required annotation created at this point in order to support the management of the RD Library as a whole.

It is often the case that the above steps are performed in a workshop. A process of recording the results of the above steps should be adopted for the workshop so that decisions are not lost. Unless a minor change is made, these should be recorded outside the RD itself, or at least only on a local copy of the RD used only for the workshop. Trying to apply change to an ontology during the workshop may affect other issues and decisions in a workshop are often overturned upon deeper review.

The details

Figure 1 shows the normal life cycle for an RD class going through development in DEXlib.

Figure 1 —  Normal RD DEXlib Process

The tasks involved in managing the development process are as follows:

1. Individual modellers develop Reference Data as part of the appropriate DEX team but within their own OWL file in the "developer-draft" folder, plcs-rdl-dpe.rdf-xml.owl for example. This involves developing classes including their definition and relevant annotation properties. The class needs to be placed in the correct place in the RD class hierarchy. This involves making classes subclasses of the EXPRESS OWL classes or of an existing RD class. (See Issue 1 above for other possible kinds of Reference Data)
2. When the private developer Reference Data is ready for review, it is cut and paste from the modeller OWL file in the "developer-draft" folder to the plcs-std-rdl.rdf-xml.owl OWL file in the "developer-draft" folder. The following annotations properties for the class are set at this point to help manage the process: OASIS_stage = "DeveloperDraft", owl:versionInfo = "1" and OASIS_revision = "0". It is possible that the new RD is actually a repair being made to an existing class that was published as a Version 1 , in which case the owl:versionInfo is set as appropriate (e.g. owl:versionInfo = "2").
3. The classes developed by the modellers are then reviewed by the team comprising the modeller who developed the Reference Data, a business user from the DEX team and at least one other modeller not involved in the development of that class; This review involves checking that:
   • the required annotation properties are used;
   • the class definition is understandable and unambiguous;
   • the class is a subclass of the appropriate PLCS schema classes (directly or indirectly through other RD classes);
   • the class is a subclass of all appropriate RD classes;
   • the class does not replicate other classes within the same context . Because of the possibility of PLCS adoption of multiple existing standards covering the same scope, it is possible that the class may overlap with classes defined in other standards. For example, both DEF STAN 00-60 and NATO standards may result in classes that are subclasses of the PLCS entity type "product" and those classes may overlap. However, in that case, the classes that overlap are not considered to be "within the same context". Note that it is possible to classify the same data instance any number of times in a DEX-based data exchange so both the 00-60 and NATO classes might be used at the same time.
4. The results and the rationale of the review are recorded in an issue log with the classes either: deleted, returned to the private developer OWL for more work or accepted as being ready for the next stage. If the modeller is expected to revise and resubmit the particular RD class, when it is revised and/or reappears in the plcs-std-rdl.rdf-xml.owl file the OASIS_revision annotation is incremented (e.g. OASIS_revision = "1"). Figure 2 shows that revisions can occur within a development stage.
   
   
   
   
   
   Figure 2 —  Revisions within an RD Stage
   
   
5. Review continues on other new Reference Data until the point is reached where a set exists that might be considered as ready to proceed through the more formal stages of the process. When the plcs-std-rdl.rdf-xml.owl OWL file in the "developer-draft" folder has reached that state the following happens:
   1. the annotation properties for the new RD are reset to OASIS_stage = "CommitteeDraft", owl:versionInfo = "1" and OASIS_revision = "0". This Committee Draft stage means the techical content is proposed by the DEX/RD team to the entire OASIS PLCS TC for review and consideration for potential ballot.
      WARNING : This use of the stage "Committee Draft" is different from the ISO STEP/SC4 stage with that same name.
   2. The entire plcs-std-rdl.rdf-xml.owl file is copied over to the "committee-draft" folder.
   3. The plcs-std-rdl.rdf-xml.owl in the "developer-draft" folder can now be used for new developments but the RD that is at the OASIS_stage = "CommitteeDraft" should not be edited.
6. The Committee Draft review cycle then occurs. It is on a wider scale involving the same roles but from other DEX teams. This supports the harmonization of RD across DEXs.
7. The results and the rationale of the Committee Draft broader review are recorded in an issue log with the classes either deleted, returned to the developer for consideration in the future or accepted as ready for an OASIS ballot.
8. When the point is reached where the new RD set in the plcs-std-rdl.rdf-xml.owl OWL file in the "committee-draft" folder might be considered for ballot, the following happens:
   1. the annotation properties for the new RD are reset to OASIS_stage = "PublicReviewDraft", owl:versionInfo = "1" and OASIS_revision = "0". This Public Review Draft stage means the technical content is proposed by entire OASIS PLCS TC for review and consideration by the public as an OASIS standard.
   2. The entire plcs-std-rdl.rdf-xml.owl file is copied over to the "public-review-draft" folder and the plcs-std-rdl.rdf-xml.owl in the "committee-draft" folder is emptied (i.e. all classes are deleted from it) to ensure confusion does not exist with respect to the state of the RD.
   3. the annotation properties of the classes published as part of the Public Review Draft are reset in the plcs-std-rdl.rdf-xml.owl in the "developer-draft" folder to be OASIS_stage = "PublicReviewDraft", owl:versionInfo = "1" and OASIS_revision = "0".
9. Upon completion of the Public Review stage, the ballot closes and the ballot comments are reviewed and addressed.
10. When the point is reached where the new RD set in the plcs-std-rdl.rdf-xml.owl OWL file in the "public-review-draft" folder might be considered complete and ready for publication, the following happens:
    1. the annotation properties for the new RD are reset to OASIS_stage = "CommitteeSpecification", owl:versionInfo = "1" and OASIS_revision = "0". This Commiteee Specification stage means the technical content is an official OASIS publication.
    2. The entire plcs-std-rdl.rdf-xml.owl file is copied over to the "committee-specification" folder and the plcs-std-rdl.rdf-xml.owl in the "public-review-draft" folder is emptied (i.e. all classes are deleted from it) to ensure confusion does not exist with respect to the state of the RD.
    3. the annotation properties of the published classes that are also in the plcs-std-rdl.rdf-xml.owl in any of the other folders are reset to be OASIS_stage = "CommitteeSpecification", owl:versionInfo = "1" and OASIS_revision = "0".

OWL files

For the purposes of PLCS RD development, the unabbreviated RDF-XML format of OWL file has been chosen. It is more regular and enables simpler processing by the DEXlib infrastructure. The OWL files involved in RD development are as follows:

plcs-arm-lf-express.rdf-xml.owl

one file representing the AP239 PLCS EXPRESS schema entity types as OWL classes (developers do not edit this file)

plcs-dc-elements-1.1.rdf-xml.owl

one file containing the Dublin Core elements used for annotation (developers do not edit this file)

plcs-dc-terms.rdf-xml.owl

one file containing the Dublin Core terms used for annotation (developers do not edit this file)

plcs-std-rdl.rdf-xml.owl

the file that contains the PLCS Reference Data itself as OWL classes and that imports the EXPRESS and Dublin Core files (see below for more about the multiple files of this name in the various folders for managing the development process)

plcs-rdl-<developer>.rdf-xml.owl

one file that contains the in-work, not yet sharable RD for each <developer>, where for example <developer> is "dpe" for David Price so his file is named plcs-rdl-dpe.rdf-xml.owl (this is where the developers do most of their work)

Only a single copy of the one EXPRESS and two Dublin Core OWL files is required, and that is placed in the "committee-specification" folder. Once finalized for OASIS publication, these OWL files can appear directly on the OASIS Web site for use by anyone.

Multiple copies of the PLCS Reference Data OWL file are used during the development of RD. At any one time, there may be up to five copies in the process: one OASIS standard on the Web, one in the "committee-specification" folder, one in the "public-review-draft" folder, one in the "committee-draft" folder and one in the "developer-draft" folder. Each file that is in an earlier stage in the development contains a superset of the content of the RD files in the later stages of the process. For example, the file in the "committee-specification" folder would contain all RD that has reached the Committee Specification stage while the file in the the "public-review-draft" folder would contain the RD that had reach the Committee Specification stage plus the RD that had reached the Public Review Draft stage.

Only a single copy of the one <developer> file for each RD developer is used and it always resides in the "developer-draft" folder.

OWL developer files

Although the approach assumes that each developer only shares their in-process RD when it is ready for broader review by moving it into the "developer-draft" plcs-std-rdl.rdf-xml.owl file, it is of course possible for developers to directly import other files from "developer-draft" folder to view in-process RD from anyone. Each user has control of the imports within their <developer> file. Figure 3 shows the simplest case where a developer file does not import another developer file (note that the rdf-xml.owl extension is omitted to simplify the figure).

Figure 3 —  Developer File Importing Standard RD

Figure 4 shows where one developer imports another developers RD file too (note that the rdf-xml.owl extension is omitted to simplify the figure).

Figure 4 —  Developer File Importing Standard RD And Second Developer File

Figure 3 shows that a developer has control over which of the Standard RD files they want to import. The dashed line indicates that any one of the plcs-std-rdl files can be chosen as the basis for the developer at any point in time. This capability is available by treating each of the folders as an "Ontology Repository" and changing the order in which the repositories are searched. Once the first set of RD has become an OASIS standard, the option of importing directly from the OASIS Web site becomes possible as well - although that option is not shown in Figure 5. (note that the rdf-xml.owl extension is omitted to simplify the figure).

Figure 5 —  Options for Importing Standard RD

Managing the development process

Issue management

Issues can be raised and recorded in the 'Reference Data issues log' against classes at any stage during the development of the Reference Data. Details on issue management are provided in the Raising issues against Reference Data section of the 'Instructions for DEX developers - Developing PLCS Reference Data' chapter.

In addition to issues being raised against classes, a less formal capability for commenting is supported. The Protege tool has a capability to add TODO comments as part of the OWL:versionInfo annotation property. DEXlib RDL Viewing includes support for that TODO capability in the OWL itself. A versionInfo that begins with the string "TODO" is shown as a Protege TODO, not a Version.

Versioning ontologies

When the set of OWL files that make up the PLCS Reference Data are published, each file will have a version number associated with it that is incremented. The first version will be "1" and each following version will increment that value by 1 (e.g. version "1" to "2").

NOTE: At one point minor releases (e.g "1.1") were considered but there seems to be little rationale for not just using "1", "2", etc.

The version of a particular class within the RDL is independent of the version of the entire RDL as a whole (i.e. RDL version 2 may contain classes that are unchanged and therefore are at Class version 1).

The OWL files developed as PLCS Reference Data are placed under configuration management using CVS. Consequently, CVS will manage the versioning of a file every time it is committed to CVS.

This is done by setting the annotation property owl:versionInfo on the ontology to be: $Id: dvlp_refdata.xml,v 1.20 2010/02/10 16:56:25 annmeads Exp $ which will be automatically updated by CVS when the file is checked in. E.g.

<owl:Ontology rdf:about="">
  <owl:versionInfo rdf:datatype="http://www.w3.org/2001/XMLSchema#string">
    $Id: dvlp_refdata.xml,v 1.20 2010/02/10 16:56:25 annmeads Exp $
  </owl:versionInfo>
</owl:Ontology>

At certain points in the standardization process, the owl:versionInfo value is reset to be managed manually for the Ontology and for the individual RD Classes.

Versioning classes

Versioning classes is actually the versioning of the definition of the classes. Versions of classes is not a well-accepted concept. If a version of a class has different membership, then it is a new class, not a version of an existing class. Versions of classes are acceptable when repairing an error in the definition, adding example and similar changes that do not change the intended membership of the class. If a change in intended membership is desired, then a new class should be created that may be a superclass or subclass of the existing class.

Each class will have a version number associated with it. The form of the version will be "n" and for the initial release of the RDL all classes will be version "1". Updates cause in increment in the value (i.e. "1" to "2", etc.).

The version of the class is set by the class annotation property owl:versionInfo. E.g.

<owl:Class rdf:ID="picometre">
  <owl:versionInfo rdf:datatype="http://www.w3.org/2001/XMLSchema#string">
    1
  </owl:versionInfo>
</owl:Ontology>

Naming classes

The class names must be unique within the context of the entire Reference Data Library. Given that the practice in the ontology community is to give meaningful names (i.e. URI fragment identifiers) for classes, the PLCS RD class names follow that practice.

As the class names are also part of a URI in the OWL language, they may not contain spaces or special characters. The convention for the name is that the first character of the first word is upper case and all other characters are lower case. Words in the class name are separated by the underscore character.

Other general guidelines/practices include the following.

• It is not recommended to put the word class or category or classification in the name of the class. (e.g. a subclass of "Activity" is not "Maintenance_task_class" but "Maintenance_task").

The name of the class is set by the OWL rdf:ID construct. E.g.

<owl:Class rdf:ID="activity"/>

Alternative labels can be provided for the OWL rdfs:label construct. These labels can be used to provide a name for the class in multiple languages. E.g.

<owl:Class rdf:ID="Activity">
  <rdfs:label xml:lang="fr">Activité</rdfs:label>
</owl:Class>

Class definitions

From a user viewpoint, a good definition is straightforward to understand from the text of the definition, does not use any specialist terminology, nor require any specialist knowledge.

The definition associated with an RD class may be seen by PLCS application users and therefore should take into account the DEX(s) and PLCS entity type(s) that are its context.

The definitions are set by the OWL rdfs:comment construct. E.g. the definition for 'Qualified_property';

<rdfs:comment xml:lang="en">
  A property whose values are described rather than being numerically quantified,
  for example the property of a traffic light may be Red, Amber or Green.
</rdfs:comment>

Class status

A class can be in one of the following possible states:

Developer Draft

While not really a formal status, the class exists within an ontology in the "developer-draft" folder on DEXlib in either a user file or the plcs-std-rdl.rdf-xml.owl file. files available on DEXlib. For example, the class might be defined in the personal development ontology of the developer 'rbn';
'plcs-rdl-rbn.rdf-xml.owl' - (../../data/refdata/developer-draft/plcs-rdl-rbn.rdf-xml.owl)
or when ready for review by other team members, removed from the personal developer OWL file and moved to the ontology file;
'plcs-std-rdl.rdf-xml.owl' - (../../data/refdata/developer-draft/plcs-std-rdl.rdf-xml.owl)

Committee Draft

The RD has been reviewed by the DEX team and upgraded to a status of "Committee Draft" ready for review by the entire OASIS PLCS TC and is put in the plcs-std-rdl.rdf-xml.owl file in the "committee-draft" folder. At times this file may be emptied when nothing is in-process and at that stage of development (e.g. when a public ballot is ongoing it may be the case that nothing is under review by the entire OASIS PLCS TC while it supports the public ballot).

Public Review Draft

The RD has been reviewed by the larger PLCS TC and is ready for a ballot known as a public review in OASIS terminology. The class will exist in the plcs-std-rdl.rdf-xml.owl file in the "public-review-draft" folder. At times this file may be emptied when nothing is in-process and at that stage of development (e.g. when not public ballot is ongoing).

Committee Specification

Once the RD Library as a whole has been through the OASIS Public Review process and made available to the general public as an initial, or new, version of the OASIS PLCS TC Reference Data Library (i.e. plcs-std-rdl.rdf-xml.owl(../../data/refdata/committee-specification/plcs-std-rdl.rdf-xml.owl) ). No changes will occur to this RD until the next version of the RDL is published (i.e. until a version 2 is published to address issues raised on a version 1).

OASIS Standard

Adopted Committee Specifications may become OASIS Standards if the OASIS-specified criteria is satisfied.

Additional annotation of classes

In conjunction with the annotation properties available in the OWL language itself, PLCS Reference Data is annotated and managed using another Web standard called The Dublin Core. The use of the Dublin Core in PLCS RD is as OWL annotation properties. Annotation properties are like comments in programming source code in that they have no effect on the technical content of the OWL ontology. A few OASIS-specific additional annotation properties are also defined for use (e.g. OASIS_stage).

Detailed guidance on the appropriate and required use of the Dublin Core as annotation of the ontology definition is found in the Reference Data - Annotation properties chapter.

RD publication process

The standard set of PLCS Reference Data has been balloted and the issues addressed, it is published as an OASIS Committee Specification, or if the relevant criteria are met as an OASIS Standard. This is achieved by making the set of OWL files that make up the Reference Data available at the OASIS-specified Web addresses as follows.

http://docs.oasis-open.org/plcs/<file name> for the most recently approved OASIS PLCS Reference Data Library, where <file name> is plcs-rdl-std.rdf-xml.owl, etc.

http://docs.oasis-open.org/plcs/v<version number>/<file name> for each version-specific OASIS PLCS Reference Data Library, where <file name> is plcs-rdl-std.rdf-xml.owl, etc. and where <version number> is "1", "2", etc. as appropriate to the release of the Reference Data. This allows users and implementors to continue to use earlier versions of the OASIS PLCS Reference Data if they have issues with the latest-and-greatest version or want more control of available Reference Data within their organization, for a specific contract, etc.