IBM Support

What can Resource Shapes do for you? A Beginner's Guide to Resource Shapes in Registry Services

Technical Blog Post


Abstract

What can Resource Shapes do for you? A Beginner's Guide to Resource Shapes in Registry Services

Body

OSLC Resource Shapes

Resource Shape is a concept defined in the OSLC Core specification that is used to represent metadata about a resource type. It describes the properties that are allowed or required in a resource, their value types, and cardinality. Clients can use Resource Shape definitions to determine how to construct and to query for records of the corresponding resource type. For example, let's imagine that we want to define a Resource Shape for ATM (automatic teller machine) resources with the following properties:

Name: ATM

URI: http://example.com/ns/oslc_atm#ATM

Properties:

        oslc_atm:tid (integer, zero-or-one) - Terminal Identification Number

        crtv:assetTag (string, zero-or-one) – ATM asset tag

        crtv:manufacturer (string, zero-or-one) - ATM manufacturer

        crtv:model (string, zero-or-one) – ATM model

        crtv:serialNumber (string, zero-or-one) - Serial number assigned by the manufacturer

        dcterms:description (XML literal, zero-or-one) – ATM description

 

Below is an example RDF/XML representation of a Resource Shape for an ATM resource.

<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"

    xmlns:dcterms="http://purl.org/dc/terms/" xmlns:rr="http://jazz.net/ns/ism/registry#"

    xmlns:oslc="http://open-services.net/ns/core#" xmlns:crtv="http://open-services.net/ns/crtv#"

    xmlns:oslc_atm="http://example.com/ns/oslc_atm#">

    <oslc:ResourceShape rdf:about="http://example.com/shapes/ATM">

	<rr:version>1.0</rr:version>

	<dcterms:title>ATM</dcterms:title>

	<dcterms:identifier>oslc_atm:ATM</dcterms:identifier>

	<oslc:describes rdf:resource="http://example.com/ns/oslc_atm#ATM"/>


 
	<oslc:property>

	    <oslc:Property>

		<oslc:name>TID</oslc:name>

		<dcterms:title>Terminal Identification Number</dcterms:title>

		<oslc:propertyDefinition rdf:resource="http://example.com/ns/oslc_atm#tid"/>

		<oslc:valueType rdf:resource="http://www.w3.org/2001/XMLSchema#integer"/>

		<oslc:occurs rdf:resource="http://open-services.net/ns/core#Zero-or-one"/>

		<dcterms:description>

                        Number that identifies the ATM machine on the ATM network.

                </dcterms:description>

	    </oslc:Property>

	</oslc:property>

	<oslc:property>

	    <oslc:Property>

		<oslc:name>assetTag</oslc:name>

		<dcterms:title>Asset Tag</dcterms:title>

		<oslc:propertyDefinition rdf:resource="http://open-services.net/ns/crtv#assetTag"/>

		<oslc:valueType rdf:resource="http://www.w3.org/2001/XMLSchema#string"/>

		<oslc:occurs rdf:resource="http://open-services.net/ns/core#Zero-or-one"/>

		<dcterms:description>

			The asset tag for a physical equipment (readable by barcode and/or RFID).

		</dcterms:description>

	    </oslc:Property>

	</oslc:property>

	<oslc:property>

	    <oslc:Property>

		<oslc:name>manufacturer</oslc:name>

		<dcterms:title>Manufacturer</dcterms:title>

		<oslc:propertyDefinition rdf:resource="http://open-services.net/ns/crtv#manufacturer"/>

		<oslc:valueType rdf:resource="http://www.w3.org/2001/XMLSchema#string"/>

		<oslc:occurs rdf:resource="http://open-services.net/ns/core#Zero-or-one"/>

		<dcterms:description>>Name of the ATM manufacturer.</dcterms:description>

	    </oslc:Property>

	</oslc:property>

	<oslc:property>

	    <oslc:Property>

		<oslc:name>model</oslc:name>

		<dcterms:title>Model</dcterms:title>

		<oslc:propertyDefinition rdf:resource="http://open-services.net/ns/crtv#model"/>

		<oslc:valueType rdf:resource="http://www.w3.org/2001/XMLSchema#string"/>

		<oslc:occurs rdf:resource="http://open-services.net/ns/core#Zero-or-one"/>

		<dcterms:description>Value of the ATM model.</dcterms:description>

	    </oslc:Property>

	</oslc:property>

	<oslc:property>

	    <oslc:Property>

		<oslc:name>serialNumber</oslc:name>

		<dcterms:title>Serial Number</dcterms:title>

		<oslc:propertyDefinition rdf:resource="http://open-services.net/ns/crtv#serialNumber"/>

		<oslc:valueType rdf:resource="http://www.w3.org/2001/XMLSchema#string"/>

		<oslc:occurs rdf:resource="http://open-services.net/ns/core#Zero-or-one"/>

		<dcterms:description>

			Serial number assigned by the manufacturer.

		</dcterms:description>

	    </oslc:Property>

	</oslc:property>

	<oslc:property>

	    <oslc:Property>

		<oslc:name>description</oslc:name>

		<oslc:propertyDefinition rdf:resource="http://purl.org/dc/terms/description"/>

		<oslc:valueType rdf:resource="http://www.w3.org/1999/02/22-rdf-syntax-ns#XMLLiteral"/>

		<oslc:occurs rdf:resource="http://open-services.net/ns/core#Zero-or-one"/>

	    </oslc:Property>

	</oslc:property>

    </oslc:ResourceShape>

</rdf:RDF>

ATM Resource Shape.

 

In summary, each Resource Shape resource is formed by a list of Property resources in which is specified for each property its name (oslc:name), URI (oslc:propertyDefinition), value type (oslc:valueType), the number of times the property is expected to occur and whether the property is required or not (oslc:occurs). For more information, refer to the OSLC Core Specification Version 2.0, which describes with details the ResourceShape and Property resources, and where you can find a complete list of supported values for oslc:valueType and oslc:occurs.

 

Resource Shapes in Registry Services

Registry Services uses the Resource Shape definitions to validate incoming registration payloads and to provide information for the reconciliation algorithm. For that, Registry Services extends the OSLC Resource Shape format to include identification rule information that is used by the reconciliation algorithm to construct reconciled Resource Records from Registration Records. A Resource Record is only created if the Registration Record satisfies at least one of the identifying rules that are specified in the Resource Shape.

Identification rules are formed by a list of properties whose values must match in order for the Resource Records to be merged. You can register two Registration Records and, if the values of the identifying properties are the same, Registry Services detects that they refer to the same resource, and then the application merges the Resource Records.

In a Resource Shape, you can specify as many identification rules as you want. When resource types have multiple identification rules, it is possible for two resources to match by using one rule, but not by using another rule. The Registry Services application resolves this type of conflict by using identification rule priorities, which are specified in the Resource Shape.

For example, below are definitions for three identification rules for the ATM resource type, each one with a different priority:

<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"

	xmlns:dcterms="http://purl.org/dc/terms/" xmlns:rr="http://jazz.net/ns/ism/registry#"

	xmlns:oslc="http://open-services.net/ns/core#" xmlns:crtv="http://open-services.net/ns/crtv#"

	xmlns:oslc_atm="http://example.com/ns/oslc_atm#">

    <oslc:ResourceShape rdf:about="http://example.com/shapes/ATM">

	.......

	<oslc:property>

	    <oslc:Property>

		<oslc:name>description</oslc:name>

		<oslc:propertyDefinition rdf:resource="http://purl.org/dc/terms/description"/>

		<oslc:valueType rdf:resource="http://www.w3.org/1999/02/22-rdf-syntax-ns#XMLLiteral"/>

		<oslc:occurs rdf:resource="http://open-services.net/ns/core#Zero-or-one"/>

	    </oslc:Property>

	</oslc:property>


 
	<rr:identificationRule>

              <rr:IdentificationRule>

              	<rr:priority>1</rr:priority>

              	<rr:ruleProperty>

                     <rr:RuleProperty>

                  	   <oslc:propertyDefinition rdf:resource="http://example.com/ns/oslc_atm#tid"/>

                     </rr:RuleProperty>

              	</rr:ruleProperty>

              </rr:IdentificationRule>

	</rr:identificationRule>

	<rr:identificationRule>

              <rr:IdentificationRule>

              	<rr:priority>2</rr:priority>

              	<rr:ruleProperty>

                     <rr:RuleProperty>

                  	   <oslc:propertyDefinition rdf:resource="http://open-services.net/ns/crtv#assetTag"/>

                     </rr:RuleProperty>

              	</rr:ruleProperty>

              </rr:IdentificationRule>

	</rr:identificationRule>

	<rr:identificationRule>

              <rr:IdentificationRule>

              	<rr:priority>3</rr:priority>

              	<rr:ruleProperty>

                     <rr:RuleProperty>

                  	   <oslc:propertyDefinition rdf:resource="http://open-services.net/ns/crtv#manufacturer"/>

                     </rr:RuleProperty>

              	</rr:ruleProperty>

              	<rr:ruleProperty>

                     <rr:RuleProperty>

                  	   <oslc:propertyDefinition rdf:resource="http://open-services.net/ns/crtv#model"/>

                     </rr:RuleProperty>

              	</rr:ruleProperty>

              	<rr:ruleProperty>

                     <rr:RuleProperty>

                  	   <oslc:propertyDefinition rdf:resource="http://open-services.net/ns/crtv#serialNumber"/>

                     </rr:RuleProperty>

              	</rr:ruleProperty>

              </rr:IdentificationRule>

	</rr:identificationRule>

    </oslc:ResourceShape>

</rdf:RDF>

ATM Identification Rules.

 

In this example, the first identification rule formed only by the TID property has higher priority than the others. This higher priority means that if two Registration Records have the same value of TID, their Resource Records will always be merged, even if they have conflicts in other identification rules.

To illustrate, let's image that we have registered two ATM Registration Records:

<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"

    xmlns:crtv="http://open-services.net/ns/crtv#" xmlns:dcterms="http://purl.org/dc/terms/"

    xmlns:oslc="http://open-services.net/ns/core#" xmlns:oslc_atm="http://example.com/ns/oslc_atm#">

	<oslc_atm:ATM rdf:about="http://atm.example.com/resource/atm-1">

	    <oslc:serviceProvider rdf:resource="http://oslc-registry/oslc/providers/1373998024416"/>

	    <oslc_atm:tid>345789123</oslc_atm:tid>

	    <crtv:assetTag>1000000100010001</crtv:assetTag>

	    <crtv:model>Super ATM 4000</crtv:model>

	    <dcterms:description>24hrs ATM, only accepts smart cards with chip.</dcterms:description>

	</oslc_atm:ATM>

</rdf:RDF>

Registration Record ATM1.

 

<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"

    xmlns:crtv="http://open-services.net/ns/crtv#" xmlns:dcterms="http://purl.org/dc/terms/"

    xmlns:oslc="http://open-services.net/ns/core#" xmlns:oslc_atm="http://example.com/ns/oslc_atm#">

	<oslc_atm:ATM rdf:about="http://atm.example.com/resource/atm-2">

	    <oslc:serviceProvider rdf:resource="http://oslc-registry/oslc/providers/1373998024416"/>

	    <oslc_atm:tid>345789123</oslc_atm:tid>

	    <crtv:assetTag>8111</crtv:assetTag>

	    <oslc_atm:location>14th avenue, 1234, New York</oslc_atm:location>

	</oslc_atm:ATM>

</rdf:RDF>

Registration Record ATM2.

 

ATM1 and ATM2 do not have the same value of crtv:assetTag, but their Resource Records are merged, since they match in a higher identification rule (same TID). The resulting Resource Record is shown below. (Note that only properties that are included in the Resource Shape definition are included in the reconciled Resource Record.)

<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dcterms="http://purl.org/dc/terms/"

    xmlns:rr="http://jazz.net/ns/ism/registry#" xmlns:j.0="http://example.com/ns/oslc_atm#"

    xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#" xmlns:crtv="http://open-services.net/ns/crtv#"

    xmlns:oslc="http://open-services.net/ns/core#">


 
    <j.0:ATM rdf:about="http://oslc-registry/oslc/resources/1373998024230">

	<rr:providerRecord>

	   <rr:ProviderRecord>

	      <rr:registrationRecord rdf:resource="http://oslc-registry/oslc/registration/1373998024230"/>

	      <oslc:serviceProvider rdf:resource="http://oslc-registry/oslc/providers/1373998024416"/>

	      <rr:sourceRecord rdf:resource="http://atm.example.com/resource/atm-1"/>

	   </rr:ProviderRecord>

	</rr:providerRecord>

	<rr:providerRecord>

	   <rr:ProviderRecord>

	      <rr:registrationRecord rdf:resource="http://oslc-registry/oslc/registration/1373998024231"/>

	      <oslc:serviceProvider rdf:resource="http://oslc-registry/oslc/providers/1373998024416"/>

	      <rr:sourceRecord rdf:resource="http://atm.example.com/resource/atm-2"/>

	   </rr:ProviderRecord>

	</rr:providerRecord>

	<dcterms:description rdf:parseType="Literal">24hrs ATM, only accepts smart cards with chip.</dcterms:description>

	<crtv:model>Super ATM 4000</crtv:model>

	<j.0:tid>345789123</j.0:tid>

	<crtv:assetTag>8111</crtv:assetTag>

	<dcterms:modified>2013-07-16T18:27:56.278Z</dcterms:modified>

    </j.0:ATM>

</rdf:RDF>

Reconciled Resource Record.

 

In Registry Services, we can have relationships between Resource Records. For that, the OSLC Resource Shape was also extended to support the rr:isRelationship property to indicate whether or not an http://open-services.net/ns/core#Resource property represents a relationship that Registry Services must try to resolve.

For example, we can add the following crtv:dependsOn relationship in the ATM Resource Shape to denote that the ATM cannot function properly without a target resource (e.g. a Computer System):

        <oslc:property>

            <oslc:Property>

                <oslc:name>dependsOn</oslc:name>

                <dcterms:title>Depends On</dcterms:title>

                <oslc:propertyDefinition rdf:resource="http://open-services.net/ns/crtv#dependsOn"/>

                <oslc:valueType rdf:resource="http://open-services.net/ns/core#Resource"/>

                <oslc:occurs rdf:resource="http://open-services.net/ns/core#Zero-or-many"/>

                <rr:isRelationship>true</rr:isRelationship>

            </oslc:Property>

        </oslc:property>

ATM dependsOn Relationship.

 

When registering an ATM Registration Record with a crtv:dependsOn relationship that refers to another resource, the Resource Registry will attempt to construct a corresponding relationship between Resource Records:

<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"

    xmlns:crtv="http://open-services.net/ns/crtv#" xmlns:dcterms="http://purl.org/dc/terms/"

    xmlns:oslc="http://open-services.net/ns/core#" xmlns:oslc_atm="http://example.com/ns/oslc_atm#">

	<oslc_atm:ATM rdf:about="http://atm.example.com/resource/atm-3">

	    <oslc:serviceProvider rdf:resource="http://oslc-registry/oslc/providers/1373998024416"/>

	    <crtv:assetTag>01012001103854</crtv:assetTag>

	    <crtv:manufacturer>ATM MAN inc.</crtv:manufacturer>

	    <crtv:model>ATM 5500</crtv:model>

	    <crtv:dependsOn rdf:resource="http://atm.example.com/resource/comp-125"/>

	</oslc_atm:ATM>

</rdf:RDF>

Example of Registration Record with a dependsOn relationship to another resource.

 

<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    	xmlns:dcterms="http://purl.org/dc/terms/"

    	xmlns:rr="http://jazz.net/ns/ism/registry#" xmlns:j.0="http://example.com/ns/oslc_atm#"

	xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#" xmlns:crtv="http://open-services.net/ns/crtv#"

    	xmlns:oslc="http://open-services.net/ns/core#">


 
    <j.0:ATM rdf:about="http://oslc-registry/oslc/resources/1373998024234">

	<rr:providerRecord>

	   <rr:ProviderRecord>

	      <rr:registrationRecord rdf:resource="http://oslc-registry/oslc/registration/1373998024234"/>

	      <oslc:serviceProvider rdf:resource="http://oslc-registry/oslc/providers/1373998024416"/>

	      <rr:sourceRecord rdf:resource="http://atm.example.com/resource/atm-3"/>

	   </rr:ProviderRecord>

	</rr:providerRecord>

	<crtv:dependsOn rdf:resource="http://oslc-registry/oslc/resources/1373998024232"/>	<!-- resolved relationship -->

	<crtv:assetTag>01012001103854</crtv:assetTag>

	<crtv:model>ATM 5500</crtv:model>

	<crtv:manufacturer>ATM MAN inc.</crtv:manufacturer>

	<dcterms:modified>2013-07-16T18:49:50.356Z</dcterms:modified>

    </j.0:ATM>

</rdf:RDF>

Resource Record with resolved relationship.

 

If the URL value of the relationship property is not a URL previously registered with the Registry Services application, the newly created Resource Record keeps the original URL value for the relationship property:

<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"

    xmlns:crtv="http://open-services.net/ns/crtv#" xmlns:dcterms="http://purl.org/dc/terms/"

    xmlns:oslc="http://open-services.net/ns/core#" xmlns:oslc_atm="http://example.com/ns/oslc_atm#">

	<oslc_atm:ATM rdf:about="http://atm.example.com/resource/atm-4">

	    <oslc:serviceProvider rdf:resource="http://oslc-registry/oslc/providers/1373998024416"/>

	    <crtv:assetTag>01012001103946</crtv:assetTag>

	    <crtv:manufacturer>ATM MAN inc.</crtv:manufacturer>

	    <crtv:model>ATM 5500</crtv:model>

	    <crtv:dependsOn rdf:resource="http://atm.example.com/resource/comp-137"/>

	</oslc_atm:ATM>

</rdf:RDF>

Example of Registration Record with a dependsOn relationship to an unknown resource.

 

<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dcterms="http://purl.org/dc/terms/"

    xmlns:rr="http://jazz.net/ns/ism/registry#" xmlns:j.0="http://example.com/ns/oslc_atm#"

    xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#" xmlns:crtv="http://open-services.net/ns/crtv#"

    xmlns:oslc="http://open-services.net/ns/core#">


 
    <j.0:ATM rdf:about="http://oslc-registry/oslc/resources/1373998024235">

	<rr:providerRecord>

	    <rr:ProviderRecord>

		<rr:registrationRecord rdf:resource="http://oslc-registry/oslc/registration/1373998024235"/>

		<oslc:serviceProvider rdf:resource="http://oslc-registry/oslc/providers/1373998024416"/>

		<rr:sourceRecord rdf:resource="http://atm.example.com/resource/atm-4"/>

	    </rr:ProviderRecord>

	</rr:providerRecord>

	<crtv:dependsOn rdf:resource="http://atm.example.com/resource/comp-137"/>	<!-- not resolved relationship -->

	<crtv:model>ATM 5500</crtv:model>

	<crtv:manufacturer>ATM MAN inc.</crtv:manufacturer>

	<crtv:assetTag>01012001103946</crtv:assetTag>

	<dcterms:modified>2013-07-16T18:56:35.110Z</dcterms:modified>

    </j.0:ATM>

</rdf:RDF>

Resource Record with a not-resolved relationship.

 

Relationships can also be part of identification rules. The reconciliation process matches relationship values if the literal URIs are the same or if they refer to the same resource.

You can find more details about the Registry Services reconciliation process in the Jazz for Service Management Information Center.

 

Creating custom Resource Shape definitions in Registry Services

Registry Services will only create Resource Records if a corresponded Resource Shape exists for that resource type. Given that, how can we create new Resource Shape definitions in Registry Services?

There are two types of Resource Shape in Registry Services: default and custom.

Default Resource Shape definitions are derived from the OSLC Reconciliation Specification and they are installed and updated during Registry Services installation process. You cannot create or delete them.

Examples of default Resource Shape definitions are: crtv:ComputerSystem, crtv:Database and crtv:ServerAccessPoint. You can retrieve the complete list of installed Resource Shape definitions by querying the Registry Services Resource Shape collection URL: http://oslc-registry/oslc/rr/shapes/collection

Now, custom Resource Shape definitions are the ones created by an administrator to fit the particularities and needs of his environment. They would typically be created for new custom resource types. However, you can also create any custom Resource Shape for the default shape resource types, so as to add custom properties or identification rules to those shapes. The custom Resource Shape definitions will override the default definitions.

You can create new custom Resource Shapes in Registry Services by using the createResourceShapes CLI command. For that, each new Resource Shape definition must be in a separate XML file, which will be loaded by the CLI command into the Registry Services database.

For example, to create the ATM Resource Shape in Registry Services, you can call:

<registry_home>\bin\frs.bat createResourceShapes -file ATM.xml

where ATM.xml is the file that contains the ATM Resource Shape definition.

Through the createResourceShapes CLI command you can also create several custom Resource Shape definitions at once by passing, in the -dir parameter, the path to the folder where all your Resource Shapes are, for example:

<registry_home>\bin\frs.bat createResourceShapes -dir <dir_name>

It's also possible to update or delete custom Resource Shapes by using the updateResourceShape and deleteResourceShapes CLI commands:

<registry_home>\bin\frs.bat updateResourceShape -file new_ATM.xml -url http://oslc-registry/oslc/rr/shapes/oslc_atm:ATM
<registry_home>\bin\frs.bat deleteResourceShapes -url http://oslc-registry/oslc/rr/shapes/oslc_atm:ATM

After creating, updating or deleting a Resource Shape, if you had previously registered some Registration Records for the given resource type, you will be asked to call the recomputeReconciledState CLI to recompute the reconciliation state of the related Resource Records.

<registry_home>\bin\frs.bat recomputeReconciledState

Note that you don't need to pass the -all parameter to the recomputeReconciledState command. By default, this CLI reprocesses only the Resource Records that were reconciled before a Resource Shape or cleansing rule update.

 

References:

Jazz for Service Management, Version 1.1, Information Center:

http://pic.dhe.ibm.com/infocenter/tivihelp/v3r1/index.jsp?topic=%2Fcom.ibm.psc.doc_1.1.0%2Fpsc_ic-homepage.html

OSLC Core Specification Version 2.0 - Appendix A: Common Properties:

http://open-services.net/bin/view/Main/OSLCCoreSpecAppendixA

OSLC Reconciliation Specification Version 2.0:

http://open-services.net/wiki/reconciliation/OSLC-Reconciliation-Specification-Version-2.0/

[{"Business Unit":{"code":"BU050","label":"BU NOT IDENTIFIED"},"Product":{"code":"SSHPN2","label":"Tivoli"},"Component":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"","Edition":"","Line of Business":{"code":"","label":""}}]

UID

ibm11275688

Page Feedback