Open Services for Lifecycle Collaboration Reconciliation Specification Version 2.0

Status: 2.0 Draft Specification - 22 June 2012

NOTE: This version of the specification has version 2.0 to indicate that it is an OSLC Core 2.0 compliant specification. This specification is the initial version of an OSLC Reconciliation specification.

This Version

• http://open-services.net/bin/view/Main/ReconSpecificationV3

Latest Version

• http://open-services.net/bin/view/Main/ReconSpecificationV3

PreviousVersion

• N/A

Authors

• TuanDang
• JacobYackenovich

Contributors

• See Contributors section below.

Table of Contents

License

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)

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.

Reconciliation resources define records such that disparate tools can identify and reconcile their data. Reconciliation resources represent individual resources as well as their relationships to other resources and to other linked resources outside of the Reconcilation Workgroup. The goal of this effort is to define the resources, constraints and methods useful for answering this category of questions, so that multiple tools can have a common understanding of their data when they integrate. The capabilities of the interface definitions are driven by key integration scenarios and therefore don't represent a complete setup of operations on resources or resource types. The resource formats and operations may not match exactly the native models supported by existing implementations but are intended to be compatible with them.

Reconciliation, as referenced in this specification, refers the case where there exists a need to combine (or reconcile) the perspectives from multiple observations on the same resource instance. See the ReconScenarios? page for several specific examples.

Importance of Identity

(this section is informative)

Whenever there is a situation where one product is communicating with another product about a resource instance, it is important to the user using both products to understand how to identify the resource is the "same thing" across multiple systems. For example, if a user launches in context to another product, without proper identity information the user does not know the context view is correct for the resource. Imagine viewing an application resource in Product "A", then launching in context to obtain more information about the application resource from Product "B", but the information returned back (unbeknownst to the user) describes a completely different resource!

Identity allows users to know they have visibility, control, or apply automation on the correct "thing" when there are multiple products in use to perform those operations.

A solution could use 1 of the product-specific names for a resource, but that is a challenging solution. Each tool has a different name for the same thing, so a user is left to writing down the name from Product "A" and then looks for the same resource in Product "B" and writes that name down. Multiply this effort by 5 different products and 1000000 resources, and the problem rapidly demonstrates a need to do this automatically.

How we propose solving this is through a solution that can receive resource information from each of the products, process this information, and then make a determination as to which resource data should combine together and create a reconciled representation of the resources across the various products. It's just as hard for a machine (if not, harder) to evaluate product-specific names of resources and try to combine the right resources together, so using the product-specific names for a common resource identity is difficult. What we offer in this Vocabulary is the set of properties that are not only common across multiple products, but these properties create a way to uniquely identify a resource instance when the properties are combined as a set.

Terminology

Base Requirements

Compliance

This specification is based on OSLC Core Specification. OSLC Reconciliation Workgroup consumers and service providers MUST be compliant with both the core specification and this Reconciliation Workgroup 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 some (but not all) additional requirements specific to Reconciliation. See the full content of the Reconcilation specification and Common Resource Type Vocabulary for all requirements.

Note that this specification further restricts some of the requirements for 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
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	MUST	Core	OSLC service providers MUST 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	Perf Mon, Core	OSLC service providers SHOULD provide query capabilities to enable clients to query for resources
Query Syntax	MUST2	Perf Mon, Core	If a service provider supports a OSLC query capabilities, the query capabilities MUST support the OSLC Core Query Syntax
Query Syntax	MAY	Core	OSLC query capabilities MAY support other query syntax
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

• ¹The OSLC Core Specification indicates service providers MAY provide Query Capabilities. This specification strengthens the requirement.
• ²The 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.

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 the namespace URI of http://open-services.net/ns/recon# with a namespace prefix of oslc_recon. This namespace URI and prefix are used to designate the resources defined in this specification and their properties.

Resource Formats

Service Providers that wish to use the specifications for ensuring reconciliation use the contents of the Reconciliation Workgroup specification within the context of another OSLC Domain. In addition to the requirements for OSLC Defined Resource Representations, Refer to the Domain-specific statements regarding Resource Format requirements.

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.

Pagination

The Reconciliation Workgroup does not specify a Service Provider Resource. Service Providers that wish to use the specifications for ensuring reconciliation use the contents of the Reconciliation Workgroup specification within the context of another OSLC Domain. Refer to the Domain-specific statements regarding pagination of query results.

Labels for Relationships

Relationships to other resources are represented as properties whose values are the URI of the object or target resource. When an 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 Recommendation where it occurs informatively.

Resource Definitions

The Reconciliation Workgroup resource properties are not limited to the ones defined in this specification; service providers may provide additional properties. 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. Any exceptions are noted. Relationship properties refer to other resources. These resources may be in any OSLC domain (including Reconciliation Workgroup).

The diagram below shows the relationships between Reconciliation Workgroup Resources and Resources from other Domains. We need to draft a diagram showing this assocation.

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 are returned - both those defined in this specification as well as any provider-specific ones. See Selective Property Values in OSLC Core Specification.

Consumers of 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 encouraged to use the oslc.properties parameter to limit the properties returned from a request to the subset required. See Selective Property Values in OSLC Core Specification.

Prefixed Name	Occurs	Read-only	Value-type	Represen-tation	Range	Description
OSLC Reconciliation : Start of additional properties

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

The Reconciliation Workgroup does not specify a Service Provider Resource. Service Providers that wish to use the specifications for ensuring reconciliation use the contents of the Reconciliation Workgroup specification within the context of another OSLC Domain. Refer to the Domain-specific statements regarding the Service Provider Resource requirements.

Creation Factories

The Reconciliation Workgroup does not specify support statements regarding Creation Factories. Service Providers that wish to use the Reconciliation Workgroup specifications for ensuring reconciliation use the contents of the Reconciliation Workgroup specification within the context of another OSLC Domain. Refer to the Domain-specific statements regarding Creation Factory requirements.

Query Capabilities

The Reconciliation Workgroup does not specify support statements regarding Query Capabilities of resources as defined by Query Capabilities in OSLC Core. Service Providers that wish to use the Reconciliation Workgroup specifications for ensuring reconciliation use the contents of the Reconciliation Workgroup specification within the context of another OSLC Domain. Refer to the Domain-specific statements regarding Query Capability requirements.

Delegated UIs

The Reconciliation Workgroup does not specify support statements regarding the selection and creation of resources as defined by Delegated UIs in OSLC Core. Service Providers that wish to use the Reconciliation Workgroup specifications for ensuring reconciliation use the contents of the Reconciliation Workgroup specification within the context of another OSLC Domain. Refer to the Domain-specific statements regarding the selection and creation of resources when communicating about resource definitions within the contenxt of a specific Domain.

Service Provider HTTP Method Support

The Reconciliation Workgroup does not specify support statements regarding HTTP method support for resource definitions. Refer to the Domain-specific statements when communicating about resource definitions within the contenxt of a specific Domain.

Appendix A: Samples

(this section is informative)

See ReconSpecificationV3Shapes?

Appendix B: Resource Shapes

(this section is informative)

See ReconSpecificationV3Shapes?

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 ReconSpecificationV3Issues? .

Authors and Contact Information

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

• OSLC Core - OSLC Core Specification 2.0
• Dublin Core 1.1 - Dublin Core Metadata Element Set, Version 1.1
• FOAF - Friend of a Friend (FOAF) v0.98
• HTTP 1.1 - Hyper-text Transfer Protocol (HTTP/1.1)
• OAuth 1.0a - RFC5849 - The OAuth 1.0 Protocol
• RDF/XML Concepts - RDF/XML Concepts and Abstract Syntax
• RDF/XML Syntax - RDF / XML Syntax Specification (Revised)
• URI Syntax - URI Generic Syntax
• XML Namespaces - Namespaces in XML 1.0 (Third Edition)
• XSD Datatypes - XML Schema Part 2: Datatypes Second Edition