Summary of Discovery Issues

["Jim Amsden" <jamsden@us.ibm.com>]

Core TC members,
I'm going to try to summarize the OSLC3
Discovery issues we have raised and that we discussed today in the TC meeting.
Hopefully covering all the issues in one place will help understand how
the relate and/or overlap. I may not get this right, so this is really
just a starting point for discussion. However, in the interest of making
as much progress as possible, I'm including recommendations where I have
them. 

There seem to be three broad issues
with OSLC3 discovery:

1. How do clients discover the URLs
supporting discovery?
2. Given a resource, how would a client
discover information about capabilities on that resource?
3. What discovery information is actually
available from a ServiceProvider and/or LDPC?

Each of these is elaborated below.

1. How do clients discover the URLs
supporting discovery?

This is related to OSLCCORE-9Bootstrapping discovery .
This issue describes the need for, and a proposal to support, the ability
of a client application to discover what resources are available for discovery
by a server. The proposal is for servers to provide one or more link headers
on their home (or other well-known) pages that provide the URLs to Service
Provider Catalogs and/or LDPCs that support OSLC capability discovery for
that server.

Discussion:  Servers are likely
to partition the resources they support, and therefore the discovery of
those resources based on their client needs and privileges. They are therefore
likely to provide more than one entry point for discovery, using Servicer
Provider Catalogs and/or LDPCs. There is possibly little relationship between
these discovery resources and some indeterminate "home" page
for the server, and this could possibly expose information that should
only be available to select users.

Servers are well equipped to provide
information to their clients about distinguished URLs that expose their
services. This can be anywhere from hyper links in home pages to Swagger
representations of their RESTful services. Its not clear that URL discovery
is something OSLC needs to standardize, and might be something useful to
avoid. 

Recommendation: Defer this new feature,
but keep the proposal, perhaps in a new Wiki page for future consideration.
See if this becomes a popular requirement in future versions. The motivation
is less-is-more for OSLC, keeping things as simple as possible and avoiding
creation of features that could have unintended consequences.


2. Given a resource, how would a
client discover information about capabilities on that resource?

This is David's issue OSLCCORE-20Service
provider should describe domain/scope. The problem is that if a user has a link to a resource (e.g., an RTC
Project Area) that has OSLC capabilities, there's no way to navigate from
that resource to the Service Provider that describes those capabilities.
For example, if a user had a URL for JKE Banking (Change Management) Project
Area, there is no easy way to find the Service Provider resource that would
provide the URL for the query capability for that project area. A client
could read the Service Provider Catalog, and search for a Service Provider
with dcterms:title that matches the project area name, but that is inconvenient
and informal.

Discussion: For OSLC3, this is not an
issue since a resource that supports discovery would be an LDPC. Clients
can use an OPTIONS or HEAD request directly on the LDPC to get discovery
information from the link headers. There's no need to locate the Service
Provider resource (or the LDPC is the Service Provider).

For servers that provide discovery information
only in Service Provider and Service resources, a Service Provider oslc:details
property could be used to link to the resource being described. The Resource
Shape description of the oslc:details property is "A URL that may
be used to retrieve a web page to determine additional details about the
service provider." The valueType is Resource, so content negotiation
could be used to get different representations of the resource. In the
scenario above, oslc:details could be the URL to the project area.

This may be an abuse of oslc:details
if it is commonly used for a URL to a human readable description of the
services provided by the service provider. That might not be the same as
the project area URL as a GET on a project area URL with Accept: application/html
would likely return a web page displaying something about the change requests
in that project area.

Recommendation: Since this is not currently
provided in OSLC2, and is already supported in OSLC3 using LDPC discovery,
this issue should be considered closed as already supported. It is not
clear there is a need to retrofit the capability back into the OSLC2 Service
Provider resource too. Just use the new OSLC3 feature to realize the requirement.


3. What discovery information is
actually available from a ServiceProvider and/or LDPC?

This is related to issues OSLCCORE-23Should
a ServiceProviderCatalog or ServiceProvider resource be an LDPC?and OSLCCORE-26Linking
from Service resource to read-only LDPC. It is also related to URI discovery in that once a URI is discovered
to a Service Provider, then accessing the Service Provider resource discovery
information would be the same as the LDPC discovery information available
from the same URI.

Although this simplicity is appealing
it has some potential issues. First it commingles Service Provider and
LDPC types making it more difficult for OSLC3 servers who only want to
support OSLC3 clients to only use the simpler, more dynamic LDPC discovery.
Second, it potentially increases the complexity of OSLC discovery by encouraging
overlapping implementations of the same discovery capability. The intent
of compatibility was to enable the continued use of existing OSLC2 clients,
but to still encourage future clients and servers to utilize the simpler
LDPC-based discovery. Keeping these separate may help facilitate the achievement
of that objective. Third, this overloads the meaning of GET on an LDPC.
What does the server return, the Service Provider resource, or the LDPC
properties and content? There is no content-type or prefer header to distinguish
these, and we probably don't want to introduce one.

Recommendation: Keep
Service Provider Catalog, Service Provider, and Service resources separate
from LDPCs and using separate URIs. This avoids ambiguity and makes it
easier to deprecate service provider resources sometime in the future.
Examine all the properties of OSLC2 Service Provider Catalog, Service Provider
and Service, and ensure the values are accessible somehow from link headers
or response representations of an LDPC. 

Ok, after writing this down, I no longer
believe it myself. The last sentence in the recommendation above essentially
contradicts the first one!

Recommendation2: LDPCs Link headers
can specify rel='type' with values: ldp:Container and/or ldp:BasicContainer,
and oslc:ServiceProviderCatalog, oslc:ServiceProvider, or oslc:Service.

This essentially adds OSLC2 discovery
by simply adding some additional properties to LDPCs. All the OSLC3 discovery
approaches and OSLC2 discovery approaches work on the same resource, without
any change. Clients are free to ignore information they don't need to use.

The only issue is that OSLC2 clients
accessing an OSLC3 Service Provider will now get the service provider properties,
but will also get the contents of the LDPC. There is a Prefer header to
control what information is returned on an LDPC, but an OSLC2 client wouldn't
be expected to know those headers.

The other possible issue is that current
OSLC2 clients might depend on the specific RDF/XML representation of these
discovery resources (what's in-lined where). This would be a bad practice
to enforce on OSLC3 LDPCs, but might be necessary.

Sorry for the long note, and changing
the recommendation on the last one. But I though it would be useful to
capture the thought process so we don't have to repeat it too many times.

Thoughts?







Jim Amsden, Senior Technical Staff Member
OSLC and Linked Lifecycle Data
919-525-6575