ResourceShapes

In general, the validation rules that a particular container may apply in deciding to whether or not to accept a POST of a new resource representation can have unlimited complexity, and OSLC makes no attempt to describe them. Similarly the format of the representation of existing resources can be complex and variable, and the validation of a representation used to update an existing resource via PUT can also be complex. Despite the possibility of unlimited complexity, OSLC recognizes that there is a common pattern that is adopted by many, though not all tools, as described here:

  1. Define a fixed set of types of resources. These are RDF Classes that can be referenced within the representation of a resource using the rdf:type predicate.
  2. For each class, define a fixed list of properties whose values must or may be set when creating or updating a resource of that type. Expected datatypes and values for these properties is also useful information.
  3. Similarly, for each class, define a fixed list of properties whose values may be encountered when reading a resource of that type. It is common for a “read” resource to have more properties than a “written” resource – servers often add properties like last-modification-date, creator and so on to those provided by a client on creation or update, and it’s nice to know what those extra properties are because they can be used in queries.

 

OSLC defines the OSLC ResourceShape resource to allow the specification of a list of properties with allowed values and the association of that list with an RDFS Class. ServiceProviders that implement the simple standard model of “resources of a particular type have a fixed set of properties” can use this feature – ServiceProviders that don’t can ignore it.

Note on relationship of ResourceShape to other standards.

Although we’re all very familiar with this model from relational databases and object-oriented programming, it is not the “natural” model of RDF, nor is it the model of the natural world. This model says that if you are of type X, you must have these properties. RDF and the natural world work the other way around – if you have these properties, you must be of type X. This is why there is no standard RDF vocabulary that can express the equivalent of ResourceShapes.

OWL is a separate RDF-based standard which, at first glance, appears to solve the same problem as ResourceShapes. However, OWL, like RDF Schema, infers new triples from a given set of triples. OWL lets you specify inference rules about properties and types, including rules of the form "if you have these properties, you must be of type X". In contrast, ResourceShapes lets you specify the constraints that a given set of triples must have. In relational database terms, ResourceShapes are similar to TABLE definitions and integrity constraints while OWL rules are similar to VIEW definitions.

To help you understand how ResourceShapes work, below is an example shape for a fictional "Tool A" which exists at the URL http://acme.com/toolA/resourceShape1. You can see, below, the shape describes a Defect resource (http://acme.com/toolA/Defect) and three properties. The first is the standard Dublin Core "title" predicate, which is optional. The second is a Tool A-specific property called "priority" and the third is another Tool A-specific property called "defectiveComponent>." The priority property definition also defines three allowed values for setting severities of high, medium and low.

@prefix oslc:  <http://open-services.net/ns/core#> .
@prefix xsd:   <http://www.w3.org/2001/XMLSchema#> .
@prefix dcterms: <http://purl.org/dc/terms/> .

<http://acme.com/toolA/resourceShape1>
  a     oslc:ResourceShape ;
  oslc:describes  <http://acme.com/toolA/Defect> ;
  oslc:property   [ a      oslc:Property ;
        oslc:name    "title" ;
        oslc:occurs    oslc:Zero-or-many ;
        oslc:propertyDefinition  dcterms:title ;
        oslc:valueType     xsd:String ;
        dcterms:title    "details for dcterms:title property"
      ] ;
  oslc:property   [ a      oslc:Property ;
        oslc:allowedValue  <http://acme.com/toolA/high> , <http://acme.com/toolA/medium> , <http://acme.com/toolA/low> ;
        oslc:name    "priority" ;
        oslc:occurs    oslc:Exactly-one ;
        oslc:propertyDefinition  <http://acme.com/toolA/priority> ;
        oslc:valueType     oslc:Resource ;
        dcterms:title    "details for priority property"
      ] ;
  oslc:property   [ a      oslc:Property ;
        oslc:name    "defectiveComponent" ;
        oslc:occurs    oslc:Zero-or-many ;
        oslc:propertyDefinition  <http://acme.com/toolA/defectiveComponent> ;
        oslc:range     <http://acme.com/toolA/Component> ;
        oslc:valueType     oslc:Resource ;
        dcterms:title    "details for component property"
      ] ;
  dcterms:title   "Shape of resources of type Defect" .

And below is an example Defect resource representation that provides the three properties specified by the shape.


@prefix dcterms: <http://purl.org/dc/terms/>.
@prefix toolA:   <http://acme.com/toolA/>.
toolA:defect1
    a toolA:Defect;
    dcterms:title "Server failure during startup";
    toolA:priority toolA:high;
    toolA:defectiveComponent <http://acme.com/toolA/comp/Server>.
				
				

Guidance – implement simple validations for create and update

OSLC implementations should try to make it easy for programmatic clients to create and update resources. If OSLC implementations associate a lot of very complex validation rules that need to be satisfied in order for an update or creation to be accepted, it becomes difficult or impossible for a client to use the protocol without extensive additional information specific to the tool that needs to be communicated outside of the OSLC specifications. The preferred approach for tools is to allow creation and update based on the sort of simple validations that can be communicated programmatically through a ResourceShape. Additional checks that are required to implement more complex policies and constraints should result in the resource being flagged as requiring more attention, but should not cause the basic create or update to fail.

It is possible that some tools or tool installations will have very strict requirements for complex constraints for data, and that they are unable or unwilling to allow the creation of resources that do not satisfy all those constraints even temporarily. Those tools or tool installations should be aware that as a consequence they may be making it difficult or impossible for external software to use their OSLC protocols without extensive customization.

Learn more about ResourceShapes in the OSLC Core specification

Any problems?

Ask a question on the forums or email the site administrator. If you have questions specifically about Eclipse Lyo, ask the lyo-dev mailing list.