(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 [[!OSLCCore2]] 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.
This Committee Specification Public Review Draft is being developed under the RF on Limited Terms Mode of the OASIS IPR Policy, the mode chosen when the Technical Committee was established. For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the TC’s web page (https://www.oasis-open.org/committees/oslc-domains/ipr.php).
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.
Asset Consumer - 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.
This specification is based on [[!OSLCCore2]]. 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.
| Requirement | Level | Origin(s) | Meaning |
|---|---|---|---|
| Unknown properties and content | MUST | [[!OSLCCore3]] | OSLC clients MUST preserve unknown content |
| Requirement | Level | Origin(s) | Meaning |
|---|---|---|---|
| Unknown properties and content | MAY | [[!OSLCCore3]] | OSLC service providers MAY ignore unknown content |
| Unknown properties and content | MUST | [[!OSLCCore3]] | OSLC service providers MUST return an error code if recognized content is invalid. |
| Unknown properties and content | SHOULD | [[!OSLCCore3]] | OSLC service providers SHOULD NOT return an error code for unrecognized content. |
| Resource Operations | MUST | [[!OSLCCore3]] | OSLC service providers MUST support resource operations via standard HTTP operations |
| Resource Paging | MAY | [[!OSLCCore3]] | OSLC services MAY provide paging for resources |
| Partial Resource Representations | MAY | [[!OSLCCore3]] | 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 | [[!OSLCCore3]] | 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 | [[!OSLCCore3]] | OSLC service providers MAY provide a Service Provider Catalog resource |
| Service Provider Resources | MUST | [[!OSLCCore3]] | OSLC service providers MUST provide a Service Provider resource |
| Creation Factories | MAY | [[!OSLCCore3]] | OSLC service providers MAY provide creation factories to enable resource creation via HTTP POST |
| Query Capabilities | SHOULD1 | Reconciliation, [[!OSLCCore3]] | OSLC service providers SHOULD provide query capabilities to enable clients to query for resources |
| Query Syntax | MUST2 | Reconciliation, [[!OSLCCore3]] | If a service provider supports OSLC query capabilities, the query capabilities MUST support the OSLC Core Query Syntax |
| Query Syntax | MAY | [[!OSLCCore3]] | OSLC query capabilities MAY support other query syntaxes |
| Delegated UI Dialogs | SHOULD | [[!OSLCCore3]] | OSLC service providers SHOULD allow clients to discover, via their service provider resources, any Delegated UI Dialogs they offer. |
| Delegated UI Dialogs | SHOULD | [[!OSLCCore3]] | OSLC service providers SHOULD offer delegated UI dialogs for resource creation |
| Delegated UI Dialogs | SHOULD | [[!OSLCCore3]] | OSLC service providers SHOULD offer delegated UI dialogs for resource selection |
| UI Preview | SHOULD | [[!OSLCCore3]] | OSLC Services SHOULD offer UI previews for resources that may be referenced by other resources |
| HTTP Basic Authentication | MAY | [[!OSLCCore3]] | OSLC Services MAY support Basic Auth |
| HTTP Basic Authentication | SHOULD | [[!OSLCCore3]] | OSLC Services SHOULD support Basic Auth only over HTTPS |
| OAuth Authentication | MAY | [[!OSLCCore3]] | OSLC service providers MAY support OAuth |
| OAuth Authentication | SHOULD | [[!OSLCCore3]] | OSLC service providers that support OAuth SHOULD allow clients to discover the required OAuth URLs via their service provider resource |
| Error Responses | MAY | [[!OSLCCore3]] | OSLC service providers MAY provide error responses using Core-defined error formats |
| RDF/XML Representations | MUST3 | Reconciliation, [[!OSLCCore3]] | OSLC service providers MUST offer an RDF/XML representation for HTTP GET responses |
| RDF/XML Representations | MUST3 | Reconciliation, [[!OSLCCore3]] | OSLC service providers MUST accept RDF/XML representations on PUT requests. |
| RDF/XML Representations | MUST3 | Reconciliation, [[!OSLCCore3]] | RDF/XML representations on POST requests whose semantic intent is to create a new resource instance. |
| XML Representations | MAY3 | Reconciliation, [[!OSLCCore3]] | 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, [[!OSLCCore3]] | 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, [[!OSLCCore3]] | OSLC service providers SHOULD provide HTML representations for HTTP GET requests |
See [[!OSLCCore2]] Specification Versioning section.
In addition to the namespace URIs and namespace prefixes defined in the [[!OSLCCore2]], 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 [[!OSLCCore3]] 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,
For HTTP PUT/POST request formats for Reconciliation resources,
For HTTP GET response formats for Query requests,
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 [[!OSLCCore3]] Representations Guidance.
See [[!OSLCCore2]] Authentication section. This specification puts no additional constraints on authentication.
See [[!OSLCCore2]] 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 [[!OSLCCore2]].
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.)
[[!OSLCCore3]] 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.
OSLC Reconciliation Version 2.0. Part 2: Vocabulary Defines the vocabulary terms and constraints for OSLC Reconciliation resources. These terms and constraints are specified according to [[!OSLCCoreVocab]].
Reconciliation service providers MAY support [[!OSLCCore3]] Resource Shapes as defined in [[!OSLCCore3]] Specification Appendix A
Reconciliation service providers MUST provide a [[!OSLCCore3]] Service Provider Resource that can be retrieved at an implementation dependent URI.
Reconciliation service providers MAY provide a [[!OSLCCore3]] Service Provider Catalog Resource that can be retrieved at an implementation dependent URI.
Reconciliation service providers MAY provide a oslc:serviceProvider property for their defined
resources that will be the URI to a [[!OSLCCore3]] Service Provider Resource.
If an OSLC Reconciliation service provider supports the creation of resources, there MUST be at least one [[!OSLCCore3]] 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.
There SHOULD be at least one [[!OSLCCore3]] 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 [[!OSLCCore3]] RDF/XML Examples to contain the result.
Reconciliation service providers MAY support the selection of reconcilable and reconciled resources as defined by [[!OSLCCore3]] Delegated UIs in OSLC Core.
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.
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.
We make this specification available under the terms and conditions set forth in the site Terms of Use, IP Policy and the Workgroup Participation Agreement for this workgroup.
The following individuals have participated in the creation of this specification and are gratefully acknowledged:
Participants:
Fabio Ribeiro, Koneksys (Editor)
James Amsden, IBM (Chair)
Andrew Berezovskyi, KTH (Chair)
Gray Bachelor, IBM
Tuan Dang, IBM
John Arwe, IBM
Joe Ross, IBM
Julianne Bielski, OSLC PerfMon WG Lead
Marek Smet, OSLC
Martine Wedlake, OSLC
Steve Speicher, OSLC
Ramamohan Chennamsetty, OSLC
| Revision | Date | Editor | Changes Made |
| 01 | 2019-06-12 | Fabio Ribeiro | Draft OASIS format version created |