![OSLC_logo.png](../../../../../pub/Main/OslcCoreSpecification/OSLC_logo.png) |
Open Services for Lifecycle Collaboration Reconciliation Specification Version 2.0
|
Status: 2.0 Draft Specification - In finalization phase
This Version
Latest Version
PreviousVersion
- This specification is the initial version of an OSLC Reconciliation specification
Authors
Contributors
Table of Contents
Contents
License
![Creative Commons Attribution license](../../../../../../licensebuttons.net/l/by/3.0/us/88x31.png)
This work is licensed under a Creative Commons Attribution License.
Notation and Conventions
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC2119.
Domain name examples use RFC2606.
Introduction
(this section is informative)
Reconciliation, as referenced in this specification, refers to the case where there exists a need to understand if multiple providers are referring to the same resource, particularly when there is not already a common identifier that all providers populate. For example, an IT environment discovery tool reports that it finds a computer using an IP address of 192.168.0.1 ; and a monitoring tools reports that CPU usage on the machine with hostname example1.domain.com. A system administrator would previously have to rely on experience or have to lookup manually that both tools are referring to the same physical resource. In HTTP terms, we want to determine that a set of URIs refer to the same “non-information resource” entity. See the Reconciliation Scenarios page for several specific examples.
This specification builds on the OSLC Core Specification to define the resources and operations supported by Open Services for Lifecycle Collaboration (OSLC) providers who have a need to reconcile resource instance information with other providers.
The goal of this effort is to define resources, methods and constraints such that disparate tools can recognize that their data describes the same entity or concept (non-information resource). Reconcilable resources describe individual entities, including their relationships to other resources inside and/or outside of the Reconciliation domain.
Terminology
Reconciliation Service Provider - an OSLC Service Provider that exposes reconcilable and/or reconciled resources.
Reconcilable resource - a resource that conforms to this specification, especially the “additional requirements” section for each resource definition. It can be matched to another resource based on the values of a set of properties as defined in this specification
Reconciled resource - A collection of reconcilable resources that the Reconciliation Service Provider has determined to be representations of the same entity.
NOT - When used in the Resource Definitions section of this specification, indicates that the absence of a property is required.
Base Requirements
Compliance
This specification is based on OSLC Core Specification. OSLC Reconciliation domain consumers and service providers MUST be compliant with both the Core specification and this specification, and SHOULD follow all the guidelines and recommendations in both these specifications.
The following table summarizes the requirements from OSLC Core Specification as well as additional requirements specific to the Reconciliation domain.
Note that this specification further restricts some of the requirements from the OSLC Core Specification as noted in the Origin column of the compliance table. See further sections in this specification or the OSLC Core Specification to get further details on each of these requirements.
Any consumer or service provider behaviors are allowed unless explicitly prohibited by this or dependent specifications; conditional permissive requirements, especially those qualified with MAY, are implicitly covered by the preceding clause. While technically redundant in light of that broad permission, OSLC specifications do still make explicit MAY-qualified statements in cases where the editors believe doing so is likely to add clarity.
Requirements on OSLC Consumers
Requirement |
Level |
Origin(s) |
Meaning |
Unknown properties and content |
MUST |
Core |
OSLC clients MUST preserve unknown content |
Requirements on OSLC Service Providers
Requirement |
Level |
Origin(s) |
Meaning |
Unknown properties and content |
MAY |
Core |
OSLC service providers MAY ignore unknown content |
Unknown properties and content |
MUST |
Core |
OSLC service providers MUST return an error code if recognized content is invalid. |
Unknown properties and content |
SHOULD |
Core |
OSLC service providers SHOULD NOT return an error code for unrecognized content. |
Resource Operations |
MUST |
Core |
OSLC service providers MUST support resource operations via standard HTTP operations |
Resource Paging |
MAY |
Core |
OSLC services MAY provide paging for resources |
Partial Resource Representations |
MAY |
Core |
OSLC service providers MAY support HTTP GET requests for retrieval of a subset of a resource’s properties via the oslc.properties URL parameter |
Partial Resource Representations |
MAY |
Core |
OSLC service providers MAY support HTTP PUT requests for updating a subset of a resource’s properties via the oslc.properties URL parameter |
Service Provider Resources |
MAY |
Core |
OSLC service providers MAY provide a Service Provider Catalog resource |
Service Provider Resources |
MUST |
Core |
OSLC service providers MUST provide a Service Provider resource |
Creation Factories |
MAY |
Core |
OSLC service providers MAY provide creation factories to enable resource creation via HTTP POST |
Query Capabilities |
SHOULD1 |
Reconciliation, Core |
OSLC service providers SHOULD provide query capabilities to enable clients to query for resources |
Query Syntax |
MUST2 |
Reconciliation, Core |
If a service provider supports OSLC query capabilities, the query capabilities MUST support the OSLC Core Query Syntax |
Query Syntax |
MAY |
Core |
OSLC query capabilities MAY support other query syntaxes |
Delegated UI Dialogs |
SHOULD |
Core |
OSLC service providers SHOULD allow clients to discover, via their service provider resources, any Delegated UI Dialogs they offer. |
Delegated UI Dialogs |
SHOULD |
Core |
OSLC service providers SHOULD offer delegated UI dialogs for resource creation |
Delegated UI Dialogs |
SHOULD |
Core |
OSLC service providers SHOULD offer delegated UI dialogs for resource selection |
UI Preview |
SHOULD |
Core |
OSLC Services SHOULD offer UI previews for resources that may be referenced by other resources |
HTTP Basic Authentication |
MAY |
Core |
OSLC Services MAY support Basic Auth |
HTTP Basic Authentication |
SHOULD |
Core |
OSLC Services SHOULD support Basic Auth only over HTTPS |
OAuth Authentication |
MAY |
Core |
OSLC service providers MAY support OAuth |
OAuth Authentication |
SHOULD |
Core |
OSLC service providers that support OAuth SHOULD allow clients to discover the required OAuth URLs via their service provider resource |
Error Responses |
MAY |
Core |
OSLC service providers MAY provide error responses using Core-defined error formats |
RDF/XML Representations |
MUST3 |
Reconciliation, Core |
OSLC service providers MUST offer an RDF/XML representation for HTTP GET responses |
RDF/XML Representations |
MUST3 |
Reconciliation, Core |
OSLC service providers MUST accept RDF/XML representations on PUT requests. |
RDF/XML Representations |
MUST3 |
Reconciliation, Core |
RDF/XML representations on POST requests whose semantic intent is to create a new resource instance. |
XML Representations |
MAY3 |
Reconciliation, Core |
OSLC service providers MAY provide a XML representation for HTTP GET, POST and PUT requests that conform to the Core Guidelines for XML. |
JSON Representations |
MAY3 |
Reconciliation, Core |
OSLC service providers MAY provide JSON representations for HTTP GET, POST and PUT requests that conform to the Core Guidelines for JSON |
HTML Representations |
SHOULD3 |
Reconciliation, Core |
OSLC service providers SHOULD provide HTML representations for HTTP GET requests |
- 1The OSLC Core Specification indicates service providers MAY provide Query Capabilities. This specification strengthens the requirement.
- 2The OSLC Core Specification indicates service providers MAY support the OSLC Query Syntax. This specification makes OSLC Query Syntax support a MUST requirement for service providers providing query capabilities.
- 3Support for all common HTTP methods is not required for all resources defined by this specification. See the HTTP Method support table for details.
Specification Versioning
See OSLC Core Specification Versioning section.
Namespaces
In addition to the namespace URIs and namespace prefixes defined in the OSLC Core specification, OSLC Reconciliation Workgroup defines a namespace
http://open-services.net/ns/crtv#
with a default namespace prefix of
crtv
. This namespace URI and prefix are used to designate the
resources defined by the Common IT Resource Type vocabulary. The namespace prefix is used in this specification for consistency but client and provider implementations might use others.
In addition to the requirements for OSLC Defined Resource Representations, this section outlines further refinements and restrictions.
See HTTP Method support table for further clarification on support for HTTP methods and media types for each OSLC resource.
For HTTP GET requests on all OSLC Reconciliation and OSLC Core defined resource types,
- Reconciliation Providers MUST provide RDF/XML representations. The RDF/XML representation SHOULD follow the guidelines outlined in the OSLC Core Representations Guidance for RDF/XML.
- Reconciliation Providers MAY provide other representations. Other representations SHOULD follow the guidelines outlined in the OSLC Core Representations Guidance.
- Reconciliation Consumers requesting RDF/XML SHOULD be prepared for any valid RDF/XML document. Reconciliation Consumers requesting XML SHOULD be prepared for representations that follow the guidelines outlined in the OSLC Core Representations Guidance.
- Reconciliation Providers SHOULD support an [X]HTML representation and a user interface (UI) preview as defined by UI Preview Guidance
For HTTP PUT/POST request formats for Reconciliation resources,
- Reconciliation Providers MUST accept RDF/XML representations and MAY accept XML representations. Reconciliation Providers accepting RDF/XML SHOULD be prepared for any valid RDF/XML document. If XML is accepted, Reconciliation Providers SHOULD be prepared for representations that follow the guidelines outlined in the OSLC Core Representations Guidance.
- Reconciliation Providers MAY accept XML and JSON representations. Reconciliation Providers accepting XML or JSON SHOULD be prepared for representations that follow the guidelines outlined in the OSLC Core Representations Guidance.
For HTTP GET response formats for Query requests,
- Reconciliation Providers MUST provide RDF/XML and MAY provide other representations such as JSON and XML.
When Reconciliation Consumers request:
application/rdf+xml
Reconciliation Providers MUST respond with RDF/XML representation without restrictions.
application/xml
Reconciliation Providers SHOULD respond with OSLC-defined abbreviated XML representation as defined in the OSLC Core Representations Guidance
Authentication
See OSLC Core Authentication section. This specification puts no additional constraints on authentication.
Error Responses
See OSLC Core Error Responses section. This specification puts no additional constraints on error responses.
Reconciliation Providers SHOULD support pagination of query results and MAY support pagination of a single resource’s properties as defined by the OSLC Core Specification.
Labels for Relationships
Relationships to other resources are represented as properties whose values are the URI of the object or target resource. When a relationship property is to be presented in a user interface, it may be helpful to provide an informative and useful textual label for that relationship instance. (This in addition to the relationship property URI and the object resource URI, which are also candidates for presentation to a user.) OSLC Core Links Guidance allows OSLC providers to support a dcterms:title
link property in resource representations, using the anchor approach (reification), but this specification discourages its use (providers SHOULD NOT use it, and consumers SHOULD NOT depend on it). At the time this specification was written, the W3C RDF working group was on a path to remove reification from the next version of RDF, and it was noted that reification never was normatively defined even in the RDF/XML syntax W3C Recommendation, where it occurs informatively.
Resource Definitions
Resources defined by this specification can have properties other than those described here, in any namespace. It is RECOMMENDED that any additional properties exist in their own unique namespace and not use the namespaces defined in this specification.
A list of properties is defined for each type of resource. Most of these properties are identified in OSLC Core Appendix A: Common Properties and in the Common IT Resource Type vocabulary. Any exceptions are noted. Relationship properties refer to other resources. These resources may be in any OSLC domain (including the Reconciliation domain).
For all resource types defined in this specification, all required properties (those defined with an occurrence of exactly-one or one-or-many) MUST exist for each resource and must be provided when requested. All other properties are optional, and might not exist on some or any resources; those that do not exist will not be present in the returned representation even if requested, while those that do exist MUST be provided if requested. Providers MAY define additional provider-specific properties; providers SHOULD use their own namespaces for such properties, or use standard Dublin Core or RDF namespaces and properties where appropriate.
If no specific set of properties is requested, all properties MUST be returned - both those defined in this specification as well as any provider-specific ones. See Selective Property Values in the OSLC Core Specification.
Consumers should note that some resources may have a very large number of related resources, and that some resources may be very large and/or expensive to compute. For this reason, consumers are strongly RECOMMENDED to use the oslc.properties
parameter to limit the properties returned from a request to the subset required. See Selective Property Values in the OSLC Core Specification.
Resource: ComputerSystem
- Name:
ComputerSystem
- Description: An intelligent device, such as a computer, that can perform computing, data collection, and/or communication operations. This includes ( but is not limited to ) general purpose computers, such as laptops, servers, and virtual machines; computers with specific functions, such as Networking and Storage hardware, Voice over IP Telephony devices, HVAC systems; monitoring data collection devices in buildings, automobiles, or electronic grids.
- Type URI
http://open-services.net/ns/crtv#ComputerSystem
ComputerSystem Properties
Prefixed Name |
Occurs |
Read-only |
Value-type |
Representation |
Range |
Description |
OSLC Reconciliation: Start of additional properties |
|
|
|
|
|
|
crtv:manufacturer |
zero-or-one |
False |
String |
n/a |
n/a |
Name of the device manufacturer. |
crtv:model |
zero-or-one |
False |
String |
n/a |
n/a |
Value of the device model. The model number as provided by the device manufacturer. |
crtv:serialNumber |
zero-or-one |
False |
String |
n/a |
n/a |
Serial number assigned by the manufacturer. The value should be provided by the manufacturer of the resource. |
crtv:systemBoardUUID |
zero-or-one |
False |
String |
n/a |
n/a |
The unique identifier of the system board. |
crtv:vmid |
zero-or-one |
False |
String |
n/a |
n/a |
The VMID is a unique identifier for a virtual machine. |
crtv:hostid |
zero-or-one |
False |
String |
n/a |
n/a |
A globally unique ID assigned to their machines by some manufacturers (.e.g Sun Solaris). |
crtv:shortHostname |
zero-or-many |
unspecified |
String |
n/a |
n/a |
A label assigned to a machine and used for communications on the local network. |
crtv:fqdn |
zero-or-many |
unspecified |
String |
n/a |
n/a |
The fully qualified domain name (FQDN). In Internet communications, the name of a host system that includes all of the subnames of the domain name. |
crtv:ipAddress |
zero-or-many |
unspecified |
Resource |
Reference |
any |
an IP address assigned to this system. Typically refers to a resource of type crtv:IPAddress but it MAY refer to other resource types. |
Additional requirements
Reconcilable resources of this type MUST contain at least 1 set of properties in the bulleted list below. All properties within a single bullet point (row) must contain a value in order to be valid. Multiple bullet points (rows) MAY be satisfied.
- crtv:hostid, crtv:vmid
- crtv:hostid, NOT vmid
- crtv:manufacturer, crtv:model,crtv:serialNumber, crtv:vmid
- crtv:manufacturer, crtv:model,crtv:serialNumber, NOT crtv:vmid
- crtv:systemBoardUUID
- (set of) crtv:fqdn
- (set of) crtv:ipAddress
You MUST NOT use an informational
value such as “Unknown” or “Not Available” for any of these bulleted properties. Populate a property only from administrative or configuration information returned from the system itself. If you are unable to obtain such information, omit the property entirely.
Resource: Database
- Name:
Database
- Description: An organized collection of digital data that is managed by a database management system (DBMS).
- Type URI
http://open-services.net/ns/crtv#Database
Database Properties
Prefixed Name |
Occurs |
Read-only |
Value-type |
Representation |
Range |
Description |
OSLC Reconciliation: Start of additional properties |
|
|
|
|
|
|
crtv:name |
zero-or-one |
False |
String |
n/a |
n/a |
The name assigned to the database by the database administrator. |
crtv:dbInstance |
zero-or-many |
False |
Resource |
Reference |
any |
The database instance that manages this database. Typically refers to a resource of type crtv:SoftwareServer but it MAY refer to other resource types. |
Additional requirements
Reconcilable resources of this type MUST contain at least 1 set of properties in the bulleted list below. All properties within a single bullet point (row) must contain a value in order to be valid.
- name, (set of) dbInstance
Resource: IPAddress
- Name:
IPAddress
- Description: Represents an IP address
- Type URI
http://open-services.net/ns/crtv#IPAddress
IPAddress Properties
Prefixed Name |
Occurs |
Read-only |
Value-type |
Representation |
Range |
Description |
OSLC Reconciliation: Start of additional properties |
|
|
|
|
|
|
crtv:address |
exactly-one |
False |
String |
n/a |
n/a |
The canonical string representation of the IP address. |
crtv:contextAddressSpace |
zero-or-one |
False |
Resource |
Reference |
any |
the anchor IP address for an IPAddress in a Network Address Translation (NAT) scenario, that is IPv4 addresses within the set of IANA privately defined address ranges of 10.0.0.0 - 10.255.255.255, 172.16.0.0 - 172.31.255.255, 192.168.0.0 - 192.168.255.255 . Typically refers to a resource of type crtv:IPAddress but it MAY refer to other resource types. |
Additional Requirements
Reconcilable resources of this type MUST contain at least 1 set of properties in the bulleted list below. All properties within a single bullet point (row) must contain a value in order to be valid.
- crtv:address, crtv:contextAddressSpace
Resource: ServiceInstance
- Name:
ServiceInstance
Description: A Service Instance is the representation of a service offering that was selected by the customer and then instantiated for that specific customer. Service Instances are supported by definite and measurable warranties or guarantees that the expected level of service/value will be met. It is common to group or nest ServiceInstances together to form a service hierarchy.
Type URI http://open-services.net/ns/crtv#ServiceInstance
ServiceInstance Properties
Prefixed Name |
Occurs |
Read-only |
Value-type |
Representation |
Range |
Description |
OSLC Reconciliation: Start of additional properties |
|
|
|
|
|
|
crtv:name |
exactly-one |
False |
String |
n/a |
n/a |
The name assigned by the organization that owns and supports this ServiceInstance. |
crtv:parentServiceInstance |
zero-or-one |
unspecified |
Resource |
Reference |
any |
In cases where services are organized in a hierarchy, this refers to the service that is immediately higher in the hierarchy. Typically refers to a resource of type crtv:ServiceInstance but it MAY refer to other resource types. |
Additional Requirements
Reconcilable resources of this type MUST contain at least 1 set of properties in the bulleted list below. All properties within a single bullet point (row) must contain a value in order to be valid.
- crtv:parentServiceInstance, crtv:name
Resource: ServerAccessPoint
- Name:
ServerAccessPoint
- Description: A network endpoint, i.e. the combination of IP address and port number that clients connect to when accessing a server.
- Type URI
http://open-services.net/ns/crtv#ServerAccessPoint
ServerAccessPoint Properties
Prefixed Name |
Occurs |
Read-only |
Value-type |
Representation |
Range |
Description |
OSLC Reconciliation: Start of additional properties |
|
|
|
|
|
|
crtv:ipAddress |
exactly-one |
False |
Resource |
Reference |
any |
The specific IP address which the ServerAccessPoint uses. Typically refers to a resource of type crtv:IPAddress but it MAY refer to other resource types. |
crtv:portNumber |
exactly-one |
False |
String |
n/a |
n/a |
The port number as defined by IETF and IANA |
Additional Requirements
Reconcilable resources of this type MUST contain at least 1 set of properties in the bulleted list below. All properties within a single bullet point (row) must contain a value in order to be valid.
- crtv:portNumber, crtv:ipAddress
Resource: SoftwareServer
- Name:
SoftwareServer
- Description: Represents an instance of software that participates in hosting a particular application.
- Type URI
http://open-services.net/ns/crtv#SoftwareServer
SoftwareServer Properties
Prefixed Name |
Occurs |
Read-only |
Value-type |
Representation |
Range |
Description |
OSLC Reconciliation: Start of additional properties |
|
|
|
|
|
|
crtv:name |
zero-or-one |
False |
String |
n/a |
n/a |
The name assigned by an administrator . |
crtv:serverAccessPoint |
zero-or-many |
False |
Resource |
Reference |
any |
The Server Access Point clients use for communications with this resource. Typically refers to a resource of type crtv:ServerAccessPoint but it MAY refer to other resource types. |
crtv:instancePath |
zero-or-one |
False |
String |
n/a |
n/a |
The directory where the files for this SoftwareServer are stored. |
crtv:runsOn |
zero-or-one |
False |
Resource |
Reference |
any |
The system this SoftwareServer instance is running on. Typically refers to a resource of type crtv:ComputerSystem but it MAY refer to other resource types. |
Additional Requirements
Reconcilable instances of this type MUST contain at least 1 set of properties in the bulleted list below. All properties within a single bullet point (row) must contain a value in order to be valid. Multiple bullets may be satisfied.
- crtv:name, crtv:instancePath, crtv:runsOn
- crtv:name, (set of) crtv:serverAccessPoint
- crtv:name, crtv:runsOn
Resource: SoftwareModule
- Name:
SoftwareModule
- Description:
Represents packaged components that are deployed to a SoftwareServer.
- Type URI
http://open-services.net/ns/crtv#SoftwareModule
SoftwareModule Properties
Prefixed Name |
Occurs |
Read-only |
Value-type |
Representation |
Range |
Description |
OSLC Reconciliation: Start of additional properties |
|
|
|
|
|
|
crtv:deployedTo |
zero-or-one |
False |
Resource |
Reference |
any |
The application server on which this SoftwareModule is deployed. Typically refers to a resource of type crtv:SoftwareServer but it MAY refer to other resource types. |
crtv:fileName |
zero-or-one |
False |
String |
n/a |
n/a |
The file name of the package containing the SoftwareModule. |
crtv:name |
zero-or-one |
False |
String |
n/a |
n/a |
The name of the SoftwareModule. |
Additional Requirements
Reconcilable resources of this type MUST contain at least 1 set of properties in the bulleted list below. All properties within a single bullet point (row) must contain a value in order to be valid.
- crtv:deployedTo, crtv:name, crtv:fileName
Reconciliation Service Provider Capabilities
Service Discovery and Description
Resource Shapes
Reconciliation service providers MAY support Resource Shapes as defined in OSLC Core Specification Appendix A
Service Provider Resource
Reconciliation service providers MUST provide a Service Provider Resource that can be retrieved at an implementation dependent URI.
Reconciliation service providers MAY provide a Service Provider Catalog Resource that can be retrieved at an implementation dependent URI.
Reconciliation service providers MUST provide a oslc:serviceProvider
property for their defined resources that will be the URI to a Service Provider Resource.
Creation Factories
If an OSLC Reconciliation service provider supports the creation of resources, there MUST be at least one Creation Factory entry in its Services definition.
See the HTTP Method support table for further clarification on support for HTTP methods and media types for each OSLC resource.
Query Capabilities
There SHOULD be at least one Query Capability entry in the Services definition.
If provided, the Query Capability MUST support the oslc:where parameter and SHOULD support the oslc:select parameter:
If shape information is NOT present with the Query Capability, service providers SHOULD use the default properties defined in OSLC Core RDF/XML Examples to contain the result.
Delegated UIs
Reconciliation service providers MAY support the selection of reconcilable and reconciled resources as defined by Delegated UIs in OSLC Core.
Service Provider HTTP Method Support
Support for all HTTP methods in the compliance table is not required for all resources. The following table summarizes the requirements for each HTTP method, and media type combination. A value of N/A
means this specification does not impose any constraints on it.
Resource |
RDF/XML |
XML |
JSON |
HTML |
Compact XML |
Other |
GET |
MUST |
MAY |
SHOULD |
SHOULD |
N/A |
N/A |
PUT |
MAY |
MAY |
MAY |
N/A |
N/A |
N/A |
POST |
MAY |
MAY |
MAY |
N/A |
N/A |
N/A |
DELETE |
N/A |
N/A |
N/A |
N/A |
N/A |
N/A |
Reconciliation service providers SHOULD support deletion of any resources for which they allow creation.
Appendix A: Samples
(this section is informative)
See OSLC Reconciliation Version 2.0 Appendix A: Samples
Appendix B: Resource Shapes
(this section is informative)
See OSLC Reconciliation Version 2.0 Appendix B: Resource Shapes
Appendix C: Notices and References
Contributors
Reporting Issues on the Specification
The working group participants who author and maintain this working draft specification, monitor a distribution list where issues or questions can be raised, see Reconciliation Workgroup Mailing List
Also the issues found with this specification and their resolution can be found at OSLC Reconciliation Version 2.0 Issues.
Intellectual Property Covenant
The members of the Working Group (or as appropriate, their employers) have documented a Patent Non-Assertion Covenant and/or Patent License for implementations of the Reconciliation Workgroup 2.0 Specification, as described in the open-services.net Terms of Use.
References