Open Content Model Example

Created by: Arthur Ryman

Introduction

This example is part of User Story S24: Open Content Model. The purpose of this example is to provide a concrete illustration of the way that resource shapes are used in practice by implementers of Linked Data specifications that support an open content model. A Linked Data specification is a specification that conforms with Linked Data design principles, which include the provision of RDF representations of information resources. The term open content model means that the specification defines the representations of some types of information resources but allows implementers to add content to the representation in a controlled way. For example, an implementation might allow additional properties. This example is based on how OSLC uses resource shapes. This pattern of usage is consistent with the W3C Linked Data Platform.

The goal of OSLC is to enable interoperability of tools from multiple vendors while allowing for vendor differentiation through value-added capabilities. OSLC specifications tend to be minimalistic, only specifying features that are readily supported by multiple vendors, but allowing vendor extension. OSLC selected Linked Data as a core technology because of the openness of the RDF data model. This ability to extend the data model also applies within a given tool implementation since it is common for tools to allow local customization by tool administrators. The scope of customization may be limited to some subset of the resources hosted by a tool. For example, a tool may allow its resources to be divided in a set of projects, each with their own access control and customization.

An OSLC specification typically defines one or more resource shapes that define a core set of resource properties for some domain. For example, in the Change Management (CM) domain, there is one type of resource, namely a Change Request. The core properties of a Change Request include name, title, and status as well as several types of relations with other resources. This example illustrates how Change Requests are described by a resource shape, and how an implementation would extend it.

Overview

This example involves two hosts:

• open-services.net is the OSLC website where the CM and other specifications are published. The example uses highly simplified versions of the resources associated with the actual CM specification.
• cm.acme.example.com represents an instance of a tool that implements the OSLC CM specification at Acme, a fictitious company. This tool has extended the CM specification by adding one or more properties.

Client applications may require a machine-understandable description of the extensions provided by cm.acme.example.com, i.e. its resource shape for Change Requests. For example, suppose Acme publishes a suite of mobile applications and includes code that can create enhancement requests and bug reports at cm.acme.example.com. The code in a mobile application may generate a user interface based on the resource shape, and perform some validity checks on the data before POSTing it to cm.acme.example.com.

Resources Hosted at open-services.net

The following resources are hosted at open-services.net:

• http://open-services.net/bin/view/Main/CmSpecificationV2 An HTML version of the CM specification. This resource is intended for human readers. It refers to some machine-understandable resources, such as an RDF vocabulary and a resource shape.
• http://open-services.net/ns/cm# An RDF vocabulary for terms defined by the CM specification. This resource is available in HTML, RDF/XML, and other RDF formats using standard HTTP content negotiation. The usual prefix for this vocabulary is oslc_cm:. The vocabulary defines the RDF type oslc_cm:ChangeRequest for Change Requests which includes enhancement requests, bug reports, etc.
• http://open-services.net/bin/view/Main/CmSpecificationV2Shapes An HTML version of the shape that describes resources of type oslc_cm:ChangeRequest.
• http://open-services.net/pub/Main/CmSpecificationV2Shapes/oslccm-change-request-shape.xml An RDF/XML representation of the shape that describes resources of type oslc_cm:Change Request.

Listing of simplified http://open-services.net/pub/Main/CmSpecificationV2Shapes/oslccm-change-request-shape.xml

The actual shape at OSLC specifies around 36 properties of oslc_cm:ChangeRequest resources. For simplicity, only two are shown in the following listing and it has been converted to Turtle to improve readability:

@prefix rdf:     <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix dcterms:  <http://purl.org/dc/terms/> .
@prefix oslc:    <http://open-services.net/ns/core#> .
@prefix oslc_cm:  <http://open-services.net/ns/cm#> .
@prefix xsd:     <http://www.w3.org/2001/XMLSchema#> .

<http://example.com/oslc/shapes/ChangeRequest>
      a       oslc:ResourceShape ;
      dcterms:title "CM V2 Change Request" ;
      oslc:describes oslc_cm:ChangeRequest ;
      oslc:property
              [ a       oslc:Property ;
                oslc:name "title" ;
                oslc:occurs oslc:Exactly-one ;
                oslc:propertyDefinition
                        dcterms:title ;
                oslc:valueType rdf:XMLLiteral
              ] ;
      oslc:property
              [ a       oslc:Property ;
                oslc:name "status" ;
                oslc:occurs oslc:Zero-or-one ;
                oslc:propertyDefinition
                        oslc_cm:status ;
                oslc:valueType xsd:string
              ] .
 

Resources Hosted at cm.acme.example.org

The following resources are hosted at cm.acme.example.org:

• https://cm.acme.example.org/catalog is the OSLC Service Provider Catalog as specified by OSLC Core V2.0. This resource is the starting point for client applications to discover available services. The term service provider is used to describe a set of related services provided by a web application. For example, a CM application may allow administrators to define projects, each with their own customizations and access control lists. Each such project would be described as a service provider. For simplicity, cm.acme.example.org will have a single service provider, https://cm.acme.example.org/services, that implements the OSLC CM V2.0 specification. The details of the catalog are not significant so no listing is given here.
• https://cm.acme.example.org/services is the OSLC Service Provider resource that described the instance of the OSLC CM V2.0 application. This resource lists the available services. For simplicity, cm.acme.example.org will just provide a creation service. The creation service is referred to as a creation factory. The description of the creation factory includes a URI that accepts HTTP POST requests and a reference to a shape resource that describes the contents of the HTTP request body. A listing of this resource is given below.
• https://cm.acme.example.org/creation-shape is the OSLC Resource Shape resource that describes what to POST to the creation URI. A listing of this resource is given below.
• https://cm.acme.example.org/change-requests is the creation URI for resources of type oslc_cm:ChangeRequest. Clients POST requests to this URI. The HTTP request body contains the RDF representation of the oslc_cm:ChangeRequest resource to be created. No listing is given here.
• https://cm.acme.example.org/change-requests/1 etc. are the URIs of created oslc_cm:ChangeRequest resources. No listing is given here.

Listing of https://cm.acme.example.org/services

The following listing shows how oslc:resourceShape associates the locally customized shape with the URI that HTTP POST requests are sent to create new change request resources.

@prefix rdf:     <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix dcterms:  <http://purl.org/dc/terms/> .
@prefix oslc_cm:  <http://open-services.net/ns/cm#> .
@prefix oslc:    <http://open-services.net/ns/core#> .

@base <https://cm.acme.example.org/> .

<services>
      a       oslc:ServiceProvider ;
      dcterms:title "Acme Change Requests"^^rdf:XMLLiteral ;
      oslc:service
              [ a       oslc:Service ;
                oslc:creationFactory
                        [ a       oslc:CreationFactory ;
                          oslc:creation <change-requests> ;
                          oslc:resourceShape <creation-shape> ;
                          oslc:resourceType oslc_cm:ChangeRequest ;
                          dcterms:title """Location for creation
				of change requests """^^rdf:XMLLiteral
                        ] ;
                oslc:domain oslc_cm: ;
              ] .
 

Listing of https://cm.acme.example.org/creation-shape

The creation factory at Acme requires the presence of exactly one, string-valued dcterms:type property. This demonstrates the Open Content model of OSLC specifications. An implementation is free to add properties, or to restrict core properties in a way consistent with the OSLC domain.

@prefix rdf:     <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix dcterms:  <http://purl.org/dc/terms/> .
@prefix oslc:    <http://open-services.net/ns/core#> .
@prefix oslc_cm:  <http://open-services.net/ns/cm#> .
@prefix xsd:     <http://www.w3.org/2001/XMLSchema#> .

<https://cm.acme.example.org/creation-shape>
      a       oslc:ResourceShape ;
      dcterms:title "CM V2 Change Request" ;
      oslc:describes oslc_cm:ChangeRequest ;
      oslc:property
              [ a       oslc:Property ;
                oslc:name "title" ;
                oslc:occurs oslc:Exactly-one ;
                oslc:propertyDefinition
                        dcterms:title ;
                oslc:valueType rdf:XMLLiteral
              ] ;
      oslc:property
              [ a       oslc:Property ;
                oslc:name "status" ;
                oslc:occurs oslc:Zero-or-one ;
                oslc:propertyDefinition
                        oslc_cm:status ;
                oslc:valueType xsd:string
              ] ;
      oslc:property
              [ a       oslc:Property ;
                oslc:name "type" ;
                oslc:occurs oslc:Exactly-one ;
                oslc:propertyDefinition
                        dcterms:type ;
                oslc:valueType xsd:string
              ] .