FPLinkedData < LinkedData

---+!! IBM Rational Focal Point Linked Data and RDF REST API

%TOC%

---++ Introduction

The purpose of this article is to describe the design for making Focal Point a Linked Data source. This will enable improved integration with other Jazz applications. This will also enable cross-application query and reporting via the Lifecycle Query Engine. 

---++ Status

Focal Point has an XML REST API, which was introduced in Focal Point 6.4. Since the XML REST API already defines a set of resource URIs and XML representations, we build on that by adding RDF representations. Note that there are some limitations in the XML REST API. For example, it does not yet provide XML representations for the recently introduced !TimeGrid attribute type. We will address these limitations.

The Focal Point 6.4 [[http://publib.boulder.ibm.com/infocenter/rsdp/v1r0m0/topic/com.ibm.help.download.focalpoint.doc/pdf64/Rational_Focal_Point_RESTful_API_Reference_Manual.pdf][documentation]] for the XML REST API says that it is provisional. We should also make this Linked Data enhancement provisional until we get validation of its capability. For example, if other applications are able to use this enhancement, e.g. for linking, reporting, or compact rendering, then we can upgrade its status to be a supported API. 

Our current plan is to release the RDF REST API in Focal Point 6.5.2. Based on our experience with integration, query, and reporting, we will make any necessary changes, and then promote the full REST API to supported status.

---++ Overview of Conceptual Model

The conceptual model of Focal Point is based on the following primary resource types: workspace, module, view, element, and attribute. A Focal Point instance contains a set of workspaces. A workspace contains a set of modules. A module contains a set of elements. An element contains a set of attributes. An attribute has a name, type, and value. A module defines the names and types of the attributes that its elements may have. A view selects a subset of elements and attributes within a module. 

Focal Point is highly configurable. Developers define workspaces, modules, views, attributes, and an initial set of elements to implement applications. Users create, modify, and delete elements as they use the workspace.

Focal Point provides a small set of built-in modules that are included in every workspace. These modules represent users, criteria, baselines, etc. However, from a data model viewpoint, they are represented the same way as the user-defined modules.

---++ Overview of Resource URIs

Examination of the XML REST API shows that there are two types of resource URI. It is important to make a distinction between them for the purposes of the RDF data model. The two types of URI are 1) those that identify the primary resource types, such as elements and modules, and 2) those that aggregate or filter the primary resources.

The REST API introduces URIs for the primary resources. The URIs for the primary resources have a distinguished role in the RDF data model since they become the subjects of triples. All information in Focal Point can be regarded as information about these primary resources.

The REST API also introduces some convenience URIs that make application programming more efficient. For example, there are four URIs that list the elements of a module, namely the indexList, indexTree, fullList, and fullTree. These URIs therefore represent different aggregates of the primary resources. In RDF terms, they represent entire graphs rather than individual subjects.

In addition, the REST API allows modules to be filtered by views. The set of elements in a view is a subset of the those in the module. Furthermore, the attributes of an element can also be filtered by a view. Again, the attibutes in the filtered element are a subset of those in the unfiltered element.

Focal Point has two kinds of views, namely Add Views that allow elements to be added and Display Views that allow elements to only be displayed. In either case the view is based on some module. 

Of course, all URIs should support HTTP GET. When RDF is requested, the response to the GET will be some set of triples. In all cases, only the URIs of the primary resources will appear as the subject of the triples, i.e. the graph contains information about some set of primary resources.

---++ URIs That Request a Content Type

HTTP content negotiation uses the Accept header to specify the preferred content type of the response. As a convenience, the REST API supports type-specific URIs. These are formed by appending an extension to the URL as follows:

| *Content Type* | *Extension* |
| HTML | .html |
| RDF/XML | .rdf |
| Turtle | .ttl |
| XML | .xml |

---++ RDF Vocabulary Approach

---+++!! Background

The REST API introduces the XML namespace http://schema.ibm.com/focalpoint/resources.  This URI is not suitable for RDF vocabulary terms since it doesn't end in a slash (/) or a hash (#).  Furthermore, the policy for Jazz applications is to host RDF vocabulary documents at jazz.net. See [[PublishingRdfVocabularies][Publishing RDF Vocabularies on jazz.net]] for more information. 
Focal Point is part of the Rational Portfolio Strategy and Management initiative which uses http://jazz.net/ns/psm as its base URI. 

Refer to [[FPVocabularyPrefixes][Focal Point Vocabulary Prefixes]] for a summary of the vocabulary prefixes we'll be using in RDF representations.

---+++ Using Standard vocabulary

Focal Point uses built-in attributes for the primary resources.  In order to achieve the best interoperability, our goal is to reuse existing, widely adopted vocabularies such as the Dublin Code. We are therefore map as many built-in Focal Point attributes as possible to standard vocabularies. The following table lists the mappings to some existing dcterms: properties. 

| *Focal Point Built-In Attribute* | *Standard URI* | 
| Alias | dcterms:identifier |
| Created Date | dcterms:created |
| Creator | dcterms:creator |
| Description | dcterms:description |
| Last Changed Date | dcterms:modifed |
| Title | dcterms:title |
| User | foaf:Person |
| User name | foaf:name |
| User title | foaf:title |
| User email | foaf:mbox |
| User login name | foaf:accountName |

---+++ Focal Point Core vocabulary

Focal Point defined concepts, built-in attributes that are not mapped into standard vocabulary, and item values are defined in Focal Point core vocabulary.    
   
   | Namespace URI  | [[http://jazz.net/ns/psm/focalpoint#][http://jazz.net/ns/psm/focalpoint#]] |
   | Prefix                | fps:    (Focal Point Schema) to distinguish it from fp: which is used in the XML representation |
   | Details              | [[FocalPointVocabulary][Focal Point Vocabulary]] |

---+++ Focal Point Data Type Vocabulary
Focal Point provides support for a large number of datatypes that may be used as the values of attributes. These datatypes are described in their own vocabulary in order to make the main Focal Point vocabulary smaller and easier to understand. See [[FPDatatypes][Focal Point Datatypes]] for a description of the datatypes. 

   | Namespace URI  | [[http://jazz.net/ns/psm/focalpoint/datatypes#][http://jazz.net/ns/psm/focalpoint/datatypes#]]  |
   | Prefix                | fpdt: (Focal Point Data Type)  |
   | Details              | [[FocalPointDatatypeVocabulary][Focal Point Datatype Vocabulary]] |


---+++ Focal Point Auto Generated Vocabulary

Focal Point allows users to define modules, attributes and choice items.  By default focal point assumes these as user defined and auto generates vocabularies in three scopes.

   | Namespace URI  | http://focalpointserver:port/fp/resources/workspaces/wid/ns#  |
   | Prefix                | workspace_wid: |
   | Scope               | Workspace scope.  Vocabulary for All the user defined modules, in a given Focal Point workspace |

   | Namespace URI  | http://focalpointserver:port/fp/resources/workspaces/wid/modules/mid/ns#  |
   | Prefix                | module_mid_wid: |
   | Scope               | Module scope.  Vocabulary for All the user defined attributes, for given Focal Point module |

   | Namespace URI  | http://focalpointserver:port/fp/resources/workspaces/wid/modules/mid/attributes/aid/ns#  |
   | Prefix                | attribute_aid_mid_wid: |
   | Scope               | Attribute scope.  Vocabulary for All the user defined choice items for given Focal Point attribute |


---++ RDF Data Model for the Primary Resources

The primary resources in Focal Point are workspace, module, view, element, and attribute. In addition, we'll treat each Focal Point web application instance as a resource that contains the other resources. We'll introduce URIs to identify these RDF types.

The following table lists the types and example REST API URIs for the primary resources. In the following, the example URIs are taken from a local instance of Focal Point hosted on ryman.torolab.ibm.com on port 6080. The REST API does not currently provide URIs for views, so new URIs have been designed based on the structure of the other URIs.

| *Type* | *Example REST API URI* | *HTTP GET Supported?* |
| fps:Service | http://ryman.torolab.ibm.com:6080/fp/resources/ | yes |
| fps:Workspace | http://ryman.torolab.ibm.com:6080/fp/resources/workspaces/3 | yes |
| foaf:Person | http://ryman.torolab.ibm.com:6080/fp/resources/users/13 | yes |
| fps:Member | http://ryman.torolab.ibm.com:6080/fp/resources/workspaces/3/members/15 | yes |
| fps:Module | http://ryman.torolab.ibm.com:6080/fp/resources/workspaces/3/modules/1 | yes |
| fps:View | http://ryman.torolab.ibm.com:6080/fp/resources/workspaces/2/modules/2/views/759 | yes |
| fps:Element | http://ryman.torolab.ibm.com:6080/fp/resources/workspaces/3/modules/3/elements/3 | yes |
| fps:Attribute | http://ryman.torolab.ibm.com:6080/fp/resources/workspaces/3/modules/3/elements/3/attributes/38 | yes |
| File | http://ryman.torolab.ibm.com:6080/fp/resources/workspaces/3/modules/3/elements/3/attributes/38/files/0 | yes |

Note that the XML REST API currently does not support HTTP GET for workspaces, modules, and views. This is a design flaw when considering Linked Data. In good Linked Data models, all HTTP URIs should respond to HTTP GET requests by providing some useful information. We should therefore extend the REST API to these resources.

These primary resource URIs form a very simple and easy-to-understand containment hierarchy. We therefore need a way to represent the containment relations among these types. In the previous [[FPWebServicesRDF][design]] we introduced explicit container resources, e.g. a workspace list resource as part of the service resource. However, it is simpler and more direct to express the containment relation by using a multi-value property that relates the primary resources. This avoids the introduction of secondary container resources.


We could use rdfs:member, the generic RDFS membership predicate. However, we'll use predicates that express the type information. The use of more specific predicates improves the readability of the RDF and can improve SPARQL query efficiency. The following table lists the membership predicates.

Element resources is modeled using two graphs.  

---+++ The Natural RDF Graph of an Element

A human designer would naturally define RDF class URIs for module names, RDF property URIs for attribute names, and RDF individual URIs for enumerated value names. We have therefore extended the Focal Point admin UI to allow users to enter URIs for module, attribute, and enumerated value names. If URIs for user-defined names are defined then the RDF representation will use them. However, there are a large number of Focal Point workspaces in production at customer sites, so we need a way to generate URIs automatically too. If the user does not define a URI then Focal Point will generate one. 

Since in Linked Data, all URIs should be deferenceable, Focal Point will host the generated URIs and return a vocabulary document when they are dereferenced, either in HTML or RDF as per normal HTTP content negotiation. The generated vocabulary document will contain descriptive information about the module, attribute, or enumerated value that the user supplies in the admin UI.

The default RDF graph for elements is the natural one that a human would design. The following list summarizes the rules for generating the natural graphs. These rules enable Focal Point to generate OSLC-compliant RDF graphs for elements:
   * The element URI is given an rdf:type property whose value is the user-defined module URI if it exists. Otherwise it is the generated module URI.
   * Each attribute of an element is represented as a triple as follows:
      * The subject of the triple is the element URI. 
      * The predicate of triple is the user-defined attribute URI if it exists. Otherwise it is the generated attribute URI. 
      * The object of the triple is the value of the attribute. 
         * If the type of the attribute is an enumeration, then the value is the user-defined enumerated value URI if it exists. Otherwise it is the generated enumerated value URI. 
         * If the type of the attribute corresponds to an RDF literal, then the value is a literal.
         * Otherwise, the type of the attribute is complex, e.g. !TimeGrid, so the value is a URI for the complex value. 

---+++ The Generic RDF Graph Associated with an Element

We define a generic RDF vocabulary for all Focal Point concepts. This has the benefit of providing a fixed way to represent Focal Point application data that is independent of the user-defined module and attribute names. This generic vocabulary simplifies the creation of generic tools that can process any Focal Point workspace. However, this generic vocabulary is somewhat unnatural for representing elements since it treats the user-defined module, attribute, and enumerated value names as string literal property values. 

We introduce a new query string, format=genericrdf, to specify another resource related to the element URI. This URI is the object of the fps:genericLink property of an element and is included in the natural RDF graph of the element. This related resource has the generic RDF graph for the element. This related URI is provided for the benefit of clients that process Focal Point data generically.

The following list summarizes the rules for the generic RDF graph of an element:
   * The element URI is give an rdf:type of fps:Element.
   * Each attribute of an element is represented as a triple as follows:
      * The subject of the triple is the element URI.
      * The predicate of the triple is fps:memberAttribute.
      * The object of the triple is a URI to a resource of type fps:Attribute.
         * The fps:Attribute resource has an rdf:value property whose object is resource whose type is a Focal Point data type.

---+++ List of Primary Resources

| *Subject Type* | *Predicate* | *Object Type* | *Description* |
| fps:Service | fps:memberWorkspace | fps:Workspace | service contains member workspace |
| fps:Service | fps:memberUser | fps:UserModule | service contains member user module|
| fps:Workspace | fps:memberModule | fps:Module | workspace contains member module |
| fps:Workspace | fps:memberModule | fps:MemberModule | workspace contains member MemberModule |
| fps:Workspace | fps:memberModule | fps:<built-in>Module | workspace contains member built-in Modules |
| fps:Workspace | fps:memberView | fps:View | workspace contains member view|
| fps:Module | fps:memberElement | fps:Element | module contains member element |
| fps:Element | fps:memberAttribute | fps:Attribute | element contains member attribute |

The following diagram illustrates the high-level structure of the Focal Point RDF data model: <br />
     <img src="%ATTACHURLPATH%/fps.png" alt="fps.png" width='707' height='692' />

---++ fps:Service

A service is a Focal Point application instance and is a container for all the other primary resources. The containment is organized in a strict hierarchy with workspace being directly contained by the service. 

In the REST API, when the service URI is dereferenced, the result contains not only the list of workspaces, but also the list of modules contained in each workspace. This is related to the fact that neither a workspace URI nor a module URI can be dereferenced in the current REST API. This design was influenced by pragmatic considerations since in general a service will only contain a few workspaces, and each workspace will contain a few modules. Therefore the size of the response will not be too large and multiple HTTP GETs will be avoided. Although this is arguably not a pure design, let's live with it for now. The representation of the service will therefore contain the same level detail for RDF as it does for XML.

See FPLinkedDataServiceExample for an example of the RDF representation of a service resource.

---++ fps:Workspace

A workspace is mainly a set of modules. However, workspaces may also contain views, which are conceptually very similar to modules.

---++ fps:Module

The REST API treats modules and views similarly. They are both members of a workspace and they have associated sets of elements. The REST API provides information about modules and views in the workspace representation. However, modules and views cannot be directly dereferenced. Instead, they provide links to several URIs that return element collections. 

A set of elements from some module is called an element collection. We won't introduce a new resource type for element collections. Instead, we'll represent element collections as sets of triples whose subject is a given module and whose predicate is fps:memberElement. Modules and views have the following properties which link to element collections:

| *Predicate* | *Description* |
| fps:indexList | A list of elements with no attributes included. |
| fps:indexTree | A tree of elements with child element hierarchy but no attributes included. |
| fps:fullList | A list of elements with attributes included. |
| fps:fullTree | A tree of elements with child element hierarchy and attributes included. |

In index list resource contains all the elements in a module or view, but omits the child element triples and the attribute triples. See FPLinkedDataIndexListExample for an example RDF representation of an index list resource.

An index tree resource is like an index list resource except that it also includes the child element triples. See FPLinkedDataIndexTreeExample for an example RDF representation of an index tree resource.

A full list resource is like an index list resource except that it also contains the attribute triples for each element in the list. See FPLinkedDataElementExample for an example RDF representation of the elements with their attribute triples.

A full tree resource is like a full index resource except that is also includes the child element triples.

---+++ fps:count

The XML representation provides a count of the number of elements. We'll represent the count using the integer property fps:count.

| *Subject Type* | *Predicate* | *Object Type* | *Description* |
| fps:Module | fps:count | integer literal | The number of elements in the module. |

---+++ Built-In Modules

Focal Point has built-in modules for several types of resources such as users, members, criteria, plans, and releases. Refer to FPBuiltInModules for a description of the built-in modules and their attributes.

---++ fps:View

---+++ fps:onModule

A view filters the set of elements from some module. Although not explicitly represented by the current REST API, we'll give the relation between views and modules using fps:onModule.

| *Subject Type* | *Predicate* | *Object Type* | *Description* |
| fps:View | fps:onModule | fps:Module | view is defined on module |

---+++ fps:isAddable

There are two kinds of views, namely Add Views and Display Views. We'll distinguish between these kinds of views using the fps:isAddable.

| *Subject Type* | *Predicate* | *Object Type* | *Description* |
| fps:View | fps:isAddable | boolean literal | is view addable? |

---++ fps:Element

---+++ fps:mspLink

The fps:mspLink property links an element to its Microsoft Project representation.

| *Subject Type* | *Predicate* | *Object Type* | *Description* |
| fps:Element | fps:mspLink | resource | The Microsoft project representation of the element. |

---+++ fps:htmlLink

The fps:htmlLink property links an element to its HTML representation.

| *Subject Type* | *Predicate* | *Object Type* | *Description* |
| fps:Element | fps:htmlLink | resource | The HTML representation of the element. |

---+++ fps:elementTypeName

A module contains a set of elements. Each element has the RDF type fps:Element. However, each module defines its own set of attributes and so it is natural to regard each module as defining its own RDF type.
We are enhancing the Focal Point admin UI to allow users to specify an RDF type URI for the module. However, we need to generate an RDF type URI for the module if the user doesn't specify one. The following discussion shows how to generate an RDF type URI for the module.

Within Focal Point, the module is a given a name, e.g. Projects, and the Add button for each module is also given a name, e.g. Project. The Add button name is a more natural choice for the module type. The REST API generates a namespace URI for each module, e.g. 

<verbatim>
xmlns:ns="http://ryman.torolab.ibm.com:6080/fp/namespace/workspaces/3/modules/13/elements"
</verbatim>

This URI is not a suitable RDF URI prefix since it does not end in a hash (#) or slash (/). We could therefore append a hash to it and call the prefix nss:. 
Furthermore, we could shorten the URI by omitting the /elements path: e.g.

<verbatim>
xmlns:nss="http://ryman.torolab.ibm.com:6080/fp/namespace/workspaces/3/modules/13#"
</verbatim>

The URI for the module type might be generated by appending the Add button name to the nss: prefix, e.g. nss:Project.

In the generic RDF representation of elements we'll use the property fps:elementTypeName to give the literal name of the module's Add button.

| *Subject Type* | *Predicate* | *Object Type* | *Description* |
| fps:Element | fps:elementTypeName | string literal | The Add button name for a module. |

---+++ fps:childElement

Some elements are folders and contain other elements. We'll represent the relationship between a folder and its child elements using the property fps:childElement. See FPLinkedDataIndexTreeExample for an example showing these folder relations.

| *Subject Type* | *Predicate* | *Object Type* | *Description* |
| fps:Element | fps:childElement | fps:Element | The subject element folder contains the object element. |

---++ fps:Attribute

Focal Point treats each attribute as a resource. Some attributes are editable. Attributes have names, datatypes, and values.

---+++ fps:attributeName

It is natural to regard an attribute as being an RDF property of its element. However, in the generic RDF representation of elements we link to resources of type fps:Attribute. We'll identify each attribute using its string literal attribute name and the property fps:attributeName.

| *Subject Type* | *Predicate* | *Object Type* | *Description* |
| fps:Attribute | fps:attributeName | string literal | The name of the subject attribute. |

---+++ fps:property

A Focal Point attribute is like an RDF property. Focal Points assigns RDF property URIs to its built-in attributes. Users can assign an RDF property URI to any attribute they define. If none is assigned then Focal Point generates one based on the module context.

| *Subject Type* | *Predicate* | *Object Type* | *Description* |
| fps:Attribute | fps:property | URI | The URI assigned to an attribute. |

---+++ fps:writeable

Attributes are either read-only or read-write. We use the boolean property fps:writeable to indicate this aspect. 

| *Subject Type* | *Predicate* | *Object Type* | *Description* |
| fps:Attribute | fps:writeable | boolean literal | true if and only if the attribute is read-write. |

---+++ rdf:value

The actual value of the attribute is given by the property rdf:value. The object of this property is always a Focal Point datatype resource and is identified by a URI reference based
on the URI of the parent fps:Attribute resource. The fragment part of the URI reference is the name of the Focal Point datatype class in lowercase, e.g. <#matrix> identifies a Matrix datatype resource.
Refer to [[FPDatatypes][Focal Point Datatypes]] for a description of all the supported datatypes.

| *Subject Type* | *Predicate* | *Object Type* | *Description* |
| fps:Attribute | rdf:value | blank node datatype | The subject attribute has value given by the object datatype. |

---++ Examples

Each example consists of a Focal Point REST API XML representation and its corresponding RDF representation in Turtle format. The example source format is Turtle since that is the most readable RDF format. The Turtle source has been validated at the [[http://www.rdfabout.com/demo/validator/][RDF Validator and Converter]] on the [[http://www.rdfabout.com/][rdf:about]] website.

These examples are provided for purposes of illustration. We have tried to keep them consistent with the specification, but some inconsistencies may exist. In these cases, the specification is the authoritative source of information.

   * [[FPLinkedDataServiceExample][Service Example]]
   * [[FPLinkedDataIndexListExample][Index List Example]]
   * [[FPLinkedDataIndexTreeExample][Index Tree Example]]
   * [[FPLinkedDataElementExample][Element Example]]
   * [[FPLinkedDataAttributeExample][Attribute Example]]
Attachments
Topic attachments
I	Attachment	Action	Size	Date	Who	Comment
png	fps.png	manage	13.4 K	2011-04-29 - 11:27	UnknownUser	Focal Point Schema Diagram
This topic: LinkedData > FPWebServicesRDF > FPLinkedData
History: r42 - 2012-06-04 - 03:56:23 - Main.ryman
Copyright © by IBM and non-IBM contributing authors. All material on this collaboration platform is the property of the contributing authors.
Contributions are governed by our Terms of Use
Ideas, requests, problems regarding TWiki? Send feedback
Dashboards and work items are no longer publicly available, so some links may be invalid. We now provide similar information through other means. Learn more here.