-
Notifications
You must be signed in to change notification settings - Fork 10
Use Cases & Requirements: OSLC v2 Interoperability and Compatibility
There are a large number of existing OSLC 2.0 clients and servers, and still some OSLC 1.0 clients and servers. Experience with developing the OSLC 2.0 specifications indicated that lack of compatibility between OSLC 1.0 and 2.0 resulted in high costs for client and server implementers and lost interoperability. Some of these clients and servers may be built in an API or using an SDK such as eclipe Lyo. Others are built on the raw protocols using REST and direct RDF/XML resource parsing. Those implementations experienced the greatest impact from OSLC version incompatibilities since there was no API that isolated their applications from the underlying protocol differences. Existing OSLC 2.0 clients and servers may also depend on capabilities that are not (yet) included in OSLC 3.0 such as:
-
Query
-
Paging
-
Resource Shapes
-
Tracked Resource Set
-
Actions (deferred from OSLC3.0 Core in TC vote 2015-04-16)
-
Automation (possibly, there is a TC, but it has no chair)
In other areas where OSLC 2.0 and 3.0 are functionally equivalent, they are currently implemented quite differently. e.g., Discovery in 2.0 is based on GETting service provider catalog resources while in 3.0 it is based on HTTP OPTIONS method and Link headers on LDP-co. Resource Preview is also implemented quite differently.
The value propositions for upgrading to OSLC 3.0 are:
-
Integration is based on an open standard, and not controlled by any single vendor
-
OSLC 3.0 is based on the new W3C Linked Data Platform standard which provides a solid foundation for reading and writing linked data resources
-
The specifications are simpler, more consistent and will potentially be more attractive to, and easier to consume by new integrations
-
There are some new capabilities including Attachments, Inverse link labels, traceability and impact types.
-
improving domain vocabularies for data consistency and removing data gaps
Some existing clients and servers may view the required effort and potential risks of re-implementing their integration code on three new standards (OSLC Domain, OSLC Core, and LDP) is not consistent with the above value propositions, and may choose to stay with OSLC 2.0 until new OSLC 3.0 clients and servers are available to establish a more compelling business need. The various OSLC vendor client and server components are likely evolve and migrate to OSLC 3.0 at unpredictable and uncoordinated times. Lack of interoperability could be a barrier to OSLC 3.0 adoption.
All these observations imply a need for OSLC 2.0 and 3.0 interoperability. That is, OSLC is intended to provide a foundation for (lifecycle) application interoperability. This goal is difficult to achieve if different versions of OSLC break interoperability. We cannot predict when and/or if clients and servers will upgrade. Thus to maintain interoperability we need a strategy to support OSLC 2.0 and 3.0 compatibility.
OSLC 2.0 compatibility with 1.0 was handled by the server/provider implementations. An implementation could choose to support both versions and use the OSLC-Core-Version HTTP header to determine which version to use in responding to a particular client request. This put the cost of technical debt into the provider implementations, and allowed the OSLC Core 2.0 working group additional freedom in developing the Core 2.0 specification since compatibility was not a primary constraint. This may have worked well for the transition from v1 to v2 where where were limited client and server implementations, and a lot was learned in the v1 specifications and implementations that resulted in significant changes in v2. The initial v2 to v3 compatibility approach as described in OSLC Core Compatibility 3.0 was similar. However, this approach may not be as applicable for compatibility between v2 and v3 because:
-
v2 is a more complete and mature set of specifications
-
There are more domain specifications built on OSLC Core v2
-
There are many more existing v2 clients and servers and many vendors involved
-
Integrated products utilizing OSLC v2 are in common use
-
There is limited demand for v3 specifications
Given the number of existing OSLC Core 2.0 domains, client/consumer and server/provider implementations, the high potential cost to update those implementations to Core 3.0 with limited business value, and the potential negative impact to end users resulting from interoperability issues between 2.0 and 3.0 implementations, OSLC Core 3.0 should have a requirement for OSLC Core 2.0 compatibility and interoperability. Specifically:
- A new version of an OSLC specification is not allowed to introduce changes that will break old clients
This requirement is spelled out in the OSLC Core 2.0 Specification, section Specification Versioning. A similar section needs to be added to the OSLC Core 3.0 Overview specification.
OSLC Core 2.0 and 3.0 capability or content compatibility can be categorized as:
-
Compatible: OSLC 3.0 uses the same protocol as OSLC 2.0 for the same capability.
-
New capability: A new capability introduced and defined by OSLC Core 3.0.
-
Out of Scope: OSLC 2.0 capability not currently in scope for OSLC 3.0.
-
Incompatible: OSLC Core 2.0 and 3.0, as currently specified, define similar capabilities but implement them differently
Capabilities that are compatible present no interoperability issues for OSLC 2.0 clients. New OSLC Core 3.0 capabilities do not introduce incompatibilities since an OSLC 2.0 client would not be expected to access them.
OSLC domains can have MAY, SHOULD or MUST normative references to existing OSLC Core 2.0 capabilities that are not currently covered by OSLC Core 3.0, and server implementations built on Core 3.0 are free to implement these 2.0 capabilities as needed. The OSLC Core 3.0 Overview specification may include normative references to OSLC Core 2.0 capabilities that are currently out of scope so that domain designs, and client and server implementations can have guidance on the use of these existing capabilities. Some capabilities, such as the OSLC query service, may be deprecated in the future, and OSLC Core 3.0 need not reference or provide any guidance on the query service. The OSLC 2.0 query service specification can be used directly if needed.
Of these capability categories, only the last one, Incompatible, would create an issue for existing OSLC 2.0 clients. The compatibility requirement above means that we must update the OSLC Core 3.0 specifications to remove these incompatibilities in order to preserve interoperability. The incompatibilities fall into two broad groups:
-
Capabilities that are MAY, SHOULD, or MUST in v2 that are not in v3 (or are implemented differently)
-
Minor differences in the current v3 specifications that introduce incompatibilities that need to be fixed
Addressing these incompatibilities will require changes in the v3 specifications. The following sections summarize the current compatibility issues between Core 2.0 and 3.0 that will need to be addressed to meet the compatibility requirement. Once these issues are addressed, the TC will no longer need to produce any compatibility Committee Notes since compatibility is addressed in the Core specifications.
The Core 3.0 Overview document should have sections describing each of these capabilities. The section on compatibility with v2 should highlight the guidance for utilizing capabilities defined in v2, but not included in v3, and using v2 capabilities that have different implementations in v3.
Minor changes: ensure HTTP challenge/response is sufficient for OAuth2, other OAuthConfiguration URIs would be covered under discovery below.
Significant change: provide two discovery mechanisms in Core 3.0, one that supports more static discovery using Service Provider Catalog compatible with Core 2.0 and another that supports more dynamic, incremental discovery based on LDP and link headers. OSLC 2.0 vocabulary and resource definitions would need to be supported, and specific RDF/XML resource representations (that clients might be relying on for parsing) would need to be supported.
OSLC v2 also supports content type application/xml: application/xml CM Provider MUST respond with OSLC-defined abbreviated XML representation as defined in the OSLC Core Representations Guidance. OSLC v2 clients may require this content type, and requiring a v3 server to provide it may be an issue. In addition, some existing v2 clients expect XMl or RDF/XML to be in a very specific format, and rely on things like XPath to parse the entity response body to extract specific information rather than relying on standard XML or RDF/XML parsers. This could add additional risks since it will be difficult to know exactly what these dependencies are. It may be impossible to know or address these compatibility issues, and may not be desirable to do so for v3.
Resource operations include: Create, Read, Update, Partial Update, Delete. Some minor updates to address If-Match header on update, partial update and paging.
Getting selected properties is another compatibility issue. OSLC v2 defines the ability to specify selective properties on GET using the oslc.properties query string. This overlaps somewhat with the Query Service and is not currently defined for Core 3.0.
Minor changes - just ensure Dialog resource is consistent with v2. Discovery changes are handled above. windowName protocol isn't included in 3.0 for dialog interaction with the parent window. postMessage format is a little different.
Minor changes: besides those already addressed by Discovery, Preview.initialHeight is not included in OSLC 3.0 and the resize messages are a little different.This property was considered a mistake in v2, and is an example of problems in the v2 spec that we would want to correct in v3, even though it might result in some incompatibilities.
Specific compatibility issues:
-
OSLC2 Compact resource is an XML document. It may also be RDF/XML but clients are suppose to process it as an XML document <-> OSLC3 Compact resource is RDF and MUST support json and turtle --> 7.4 requires an additional clause for the XML format (and/or RDF/XML)
-
OSLC2 GET on a resource that supports Preview uses the application/x-oslc-compact+xml header to request the Compact resource instead of the resource itself <-> OSLC3 uses HEAD or OPTIONS on the resource and gets the URI for the Preview from a Link header. This takes two HTTP requests. Cleints can get the Compact resource in one step by using the Prefer: return=representation; include="" header on the GET to get the Compact resource in a single request --> the OSLC2 application/x-oslc-compact+xml header would be a third way to get the Compact resource. Should all three be supported, or is the OSLC2 approach actually the simplest and most HTTP consistent? Headers are used to negotiate resource representations, and a Compact resource is an indirect representation of a resource for display purposes.OSLC3 Resource Preview likely used Link and Prefer headers to be consistent with Delegation Dialog (which used Service and oslc:selectionDialog property to discover the selection dialog). Preview is sufficiently different than Delegation that it may not be necessary for these to be implemented the same.
-
OSLC2 resize message is "oslc-preview-height: <newHeight>" <-> OSLC3 resize message is oslc-resize: {"oslc:hintHeight": <newHeight>, "oslc:hintWidth": <newWidth>} --> OSLC3 could have 2 resize messages, one for just hieght that would work with 2.0 clients, and one that includes height and width in the oslc-resize message
1. Preview Discovery
OSLC2 does Preview Discovery via GET on a resource that supports Preview using an Accept: application/x-oslc-compact+xml header to request the Compact resource representation of the resource.
OSLC3 uses HEAD or OPTIONS on the resource and gets the URI for the Preview from a Link header. This takes two HTTP requests. Clients can get the Compact resource in one step by using the Prefer: return=representation; include="" header on the GET to get the Compact resource in a single request.
Note however that RFC 7240 Prefer Header for HTTP says “The Prefer request header field is used to indicate that particular server behaviors are preferred by the client but are not required for successful completion of the request. Prefer is similar in nature to the Expect header field defined by Section 6.1.2 of [RFC7231] with the exception that servers are allowed to ignore stated preferences."
Discussion: The OSLC2 application/x-oslc-compact+xml header would be a third way to get the Compact resource. Should all three be supported, or is the OSLC2 approach actually the simplest and most HTTP consistent?
The OSLC2 use of the Accept header is a simple, consistent and well practiced way of clients requesting specific resource representations of a given URI. OSLC3 preview discovery is somewhat more complex and was designed to be consistent with delegation dialog discovery. But compact resource representations and delegated dialogs for resource selection and creation are quite different things, and may not need utilize the same discovery approach. Accept headers are used to negotiate resource representations, and a Compact resource is an indirect representation of a resource for display purposes.
Resolution: For OSLC2 compatibility, continue to support the Accept: application/x-oslc-compact+xml to get the Compact resource. Also support the OSLC3 Link header with rel and the Prefer header with include=",
2. Compact Resource Representation
Compact resource is an XML document in OSLC2, although it may be RDF/XML it should be processed as XML. This format will also need to be supported and return when the media-type requested through the Accept header is application/x-oslc-compact+xml.
OSLC3 Compact resource representation MUST be application/json and text/turtle, SHOULD be application/ld+json. Clients would generally use the Accept header to get the representation they want. However, based on the resolution above, we have already used the Accept header to indicate that the Compact resource representation is being requested rather than the resource referenced by the URI. There needs to be some way to indicate in addition what form the Compact resource is returned in: XML, RDF/XML, Turtle, JSON, etc. There are a number of possible ways to do this, each of which has benefits and issues.
2.1 Use additional MIME type extensions
OSLC Core 2.0 uses an unregistered, experimental media type to access the Compat resource: application/x-oslc-compact+xml. RFC 4288 discourages this, but indicates they are ok for use only with the active agreement of the parties exchanging them - that certainly applies to an OASIS Standard. However RFC 6838 says: “+suffix" constructs for as-yet unregistered structured syntaxes SHOULD NOT be used, given the possibility of conflicts with future suffix definitions.” The currently registered suffices include +xml and +json, but not turtle.
Given that these are unregistered, we could easily create other variants for application/x-oslc-compact+turtle, application/x-oslc-compact+xml+rdf, application/x-oslc-compact+ld-json, etc. This is certainly contributing to a bad practice. But even if we decided to retain the OSLC3 Link and Prefer header approach to Preview discovery, we'd stll need to support Accept: application/x-oslc-compact+xml for backward compatibility. Given that, it seem like the simplest and most straight forward solution is to hold our noses and start cluttering the media type space as needed:
-
application/x-oslc-compact+xml - OSLC 2.0 specific XML format
-
application/x-oslc-compact-turtle - Turtle
-
application/x-oslc-compact-rdf+xml - RDF/XML
-
application/x-oslc-compact+json - JSON
-
application/x-oslc-compact-ld+json - JSON-LD
This uses only registered suffixes with the rest of the MIME type modeled after the existing type specified in OSLC2.
2.2. Use a parameter on the Accept header
See section 14.1 of RFC 2616. The semantics of Accept header parameters doesn’t appear to be a good match. These parameters are used to tell the server, of all the representations supported, which ones are preferred by the client in what order. We need application/x-oslc-compact+xml to indicate we want the Compact resource, then something else to indicate what form that resource should be in. Its not a selection of different forms.
For example, say the client sent Accept: application/x-oslc-compact-xml, text/turtle. The server could respond with the resource at the URL in text/turtle, not the Compact resource representation.
2.3 Use a MIME profile parameter.
See RFC 2425. However, application/json and text/turtle do not appear to officially support a profile parameter.
2.4. Use the Prefer Header
See RFC 7240. Clients GET the Compact resource in the desired representation using: GET /bugs/7 HTTP/1.1 Accept: text/turtle Prefer: return=representation; include=""
Resolution: add OSLC3 Compact resource MUST support media-type application/x-oslc-compact+xml in addition to the JSON and RDF representations. The prefer header is the best way to tell the server the client prefers the compact resource, and uses the accept header to indicate what format is desired.
3. Preview Resize message
OSLC2 resize message is "oslc-preview-height: <newHeight>"
OSLC3 resize message is oslc-resize: {"oslc:hintHeight": <newHeight>, "oslc:hintWidth": <newWidth>}
Resolution: OSLC3 supports 2 resize messages, one for just height that would work with 2.0 clients, and one that includes height and width in the oslc-resize message. OSLC 3.0 clients would look for both. OSLC3 servers should send just the height message or both if there is a reason to send height and width information. Servers should send both oslc-preview-height and oslc-resize messages to endure compatibility. The specification can say that oslc-preview-height is deprecated to indicate clients should use oslc-resize.
Minor change: Core 3.0 should include a MAY conformance criteria referencing OSLC 2.0 Query Service as this is something that client and servers currently use. Other query services such as SPARQL may also be provided. Domain specifications are still free to promote Query Service to MUST if it is required to support the domain needs.
Note that OSLC v2 query language was well defined, but the query resources weren’t. This has already created some interoperability issues. e.g., how to query for defects where defect was a dcterms:type string and not an RDF type defined in the Change Management specification. The CM 3.0 specification addresses this issue, but the compatibility issues with v2 may still cause some incompatibility issues.
Should reference OSLC Core 2.0 paging as current 2.0 clients will be using this. This is a candidate for deprecation in the future if LDP supports paging.
Resource paging will need to be supported in Core 3.0 even though it will likely be used mostly by the Query Service and Tracked Resource Sets. W3C Linked Data Platform Paging 1.0 is currently a Candidate Specification. Core 3.0 may need to support the existing Core 2.0 and LDP Paging 1.0 specifications.
Minor change to use ldp:constrainedBy to have the same value as oslc:instanceShape, and say that servers MAY use ResourceShapes to define the constraints.
No change: Not an issue for OSLC Core 3.0 as clients and servers can continue to use OSLC 2.0 TRS.
OSLC Core 3.0 Overview should have a description of the Tracked Resource Set capability, and have a normative MAY reference to the current Tracked Resource Set 2.0 specification on open-services.net.
No change: Not defined in OSLC 2.0 core, so there are no compatibility issues.
No change: Not an issue for OSLC Core 3.0 as clients and servers can continue to use OSLC 2.0 Actions.
No change: Not an issue for OSLC Core 3.0 as this is a domain specification and clients and servers can continue to use OSLC 2.0 Automation.
No change, the error responses are the same.
Some changes and some resources that aren't defined in 3.0 including Discussion, Comment. OSLC Core 3.0 may wish to use something like vs:term_status to indicate that a vocabulary resource/class might be deprecated. There’s no current equivalent for ResourceShape to indicate a property might be deprecated. We could add a new optional predicate on oslc:Property to say this, making the possibility that something might be deprecated machine discoverable. However, deprecation and experimental properties are not concepts that should be included in standards. OASIS specifications already provide mechanisms for flexible implementations over time using MAY and SHOULD keywords to specify and qualify requirements. In particular, capabilities, types or properties that should be deprecated can be designated with SHOULD NOT keywords. Non-normative guidance documents can also be used to guide implementators in the use of optional or legacy capabilities.
Changes to properties of domain types requre additional consideration. Adding new properties that are consistent with existing properties is not an issue. Existing optional properties, or properties with cardinality 0..1 or * could conceptually be dropped since existing clients cannot rely on the property being asserted. However, there should be a very good reason for dropping anything, and if there is any doubt, the property should be retained. An optional property indicates that if the property is provided, the vocabulary defines what it looks like.