Re: [oslc-core] OSLC Discovery top-to-bottom read feedback (sorry it's late)

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

Comments below yours in green.

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




From:      
 Martin P Pain/UK/IBM
To:      
 Jim Amsden/Raleigh/IBM@IBMUS
Cc:      
 oslc-core@lists.oasis-open.org
Date:      
 12/09/2015 07:12 AM
Subject:    
   Re: [oslc-core]
OSLC Discovery top-to-bottom read feedback (sorry it's late)

---

Comments embedded below (with parts that
I'm not responding to deleted for ease of reading).
 
Martin
 
----- Original message -----
From: "Jim Amsden" <jamsden@us.ibm.com>
Sent by: <oslc-core@lists.oasis-open.org>
To: oslc-core@lists.oasis-open.org
Cc:
Subject: Re: [oslc-core] OSLC Discovery top-to-bottom read feedback (sorry
it's late)
Date: Tue, Dec 8, 2015 6:42 PM
 
Martin,
Thanks for the thorough review. Comments embedded below...


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




From:        "Martin
P Pain" <martinpain@uk.ibm.com>
To:        oslc-core@lists.oasis-open.org
Date:        12/04/2015
08:34 AM
Subject:        [oslc-core]
OSLC Discovery top-to-bottom read feedback (sorry it's late)
Sent by:        <oslc-core@lists.oasis-open.org>

---

...
I've only raised one ticket (OSLCCORE-38)
for the one thing that is probably best to have a discussion on without
holding up v3. 
<jra>OSLCCORE-38 is Create a Quickstart guide for OSLC. Did you mean
a different issue? Maybe OSLCCORE-50, Should we omit "read-only"values
in the discovery resource shapes?</jra>
<MPP>Correct, OSLCCORE-50</MPP>
 
 
 
...
 
3. There's still nothing about bootstrapping discovery. Perhaps we could
just add a non-normative comment somewhere saying that "Discovery
will always have to start with a URI to some resource on the server. Servers
MUST provide a way for those who are implementing clients against them
to learn how to find such a URI. For example, this could be in their user
documentation or UI. Such a URI could be for a ServiceProviderCatalog resource
(on which either static up-front discovery can be performed or, if the
server supports it, dynamic incremental discovery can be performed) or
an LDPC on which dynamic incremental discovery can be performed."
I thought about re-opening OSLCCORE-9 for this, but there's probably too
much history on that ticket already. I know we agreed to close it, but
on reading the document now I think we should put some of the results of
that discussion in the document - not the approaches we disregarded, but
the fact that we can't/don't specify anything standard.
<jra>Your summary is very good. I've included it in a new paragraph
at the end of section 5. Discovery Capabilities with some changes and additions:
p>Discovery will always have to start with at least one discovery resource
URI to bootstrap discovery on that server. Servers must provide some way
for clients learn about, find, or discover such LDPC URIs. For example,
servers could provide such information:
    <ul>
      <li>In their user documentation or UI</li>
      <li>Using HTTP <code>OPTIONS *</code>
to return a ServiceProviderCatalog or link headers to root LDPCs describing
the discovery capabilities offered</li>
      <li>Using <a href="">https://tools.ietf.org/html/rfc5785">/.well-known/
locations</a></li>
    </ul>
    The URI could be for a ServiceProviderCatalog or context
LDPC resource on which either static up-front or dynamic incremental discovery
can be performed. Different server implementation architectures and extensibility
mechanisms may require different approaches for discovering OSLC discovery
resource URIs.</p>
</jra>
<MPP>I don't think mentioning
.well-known is useful, as we haven't defined any well-known path to use.
OPTION * is a valid option that they could use, but they would still need
to say that that's what they're using in their user documentation or UI
somewhere.</MPP>

<jra>But these are only
examples of things servers could use, not anything we are standardizing,
and this is a non-normative section anyway. /.well-know/ would be a useful
alternative, and different service providers may wish to use their own
branded URIs.</jra> 
...
 
5. "5.1.3 Servers SHOULD only use LDPR representations for
additional discovery details that are not already available within HTTP
response headers. It is also useful for scenarios where it would be valuable
to have the discovery data readily available for purposes such as query."
Do we have something we can link to that explains what this is talking
about? i.e. that would say how to use LDPR representations for additional
discovery details.
</jra>5.2.5. But I think 5.1.3 could be clarified. Discovery information
is suppose to be the same for static and dynamic. However, servers might
have additional custom discovery information that would be in the LDPRs.
Clarified this by including "additional custom discovery details"</jra>
<MPP>A) I think the "only"
is still a bit ambiguous. Is it saying that LDPR representations and nothing
else should be used for custom discovery details? Or is it saying that
LDPR representations should be used only for custom discovery details and
nothing else? (I don't think this one makes sense, but it's one possible
reading from the way it's written). Or is it that custom discovery details
should only appear in LDPR representations when they are not available
in the headers? (I guess it's this 3rd one, but I only understood that
from reading 5.2.5, not from reading 5.1.3). If it's the third one, I'd
suggest "If servers make custom discovery details available to clients,
the servers SHOULD only place this information ni LDPR representations
if the details are not already available within HTTP response headers."
B) Also, would "discovery details not defined by OSLC" (or "defined
by a vendor or standard other than OSLC") be better than "additional
custom discovery details?
C) Is there any reason why we say "LDPR representations" rather
than "resource response body" as we do in 5.2.5? Or is 5.1.3
specific to LDP in some way that 5.2.5 isn't?
Putting all these together, my
suggested text would be "If servers make available to clients discovery
details that are defined by a vendor or standard other than OSLC, then
the servers SHOULD only place this information in the resource representation
(that is, in the HTTP response body) if the details are not already available
within HTTP response headers."</MPP>

<jra>I think the purpose
of this clause, and the "only", is to simplify what clients have
to do to get discovery information. That is, if the discovery information,
standard or custom, is already in Link and other headers (Accept) headers,
then the information shouldn't be repeated in LDPR properties. I suggest
the following updated wording.

Servers SHOULD NOT include
discovery information in entity response bodies if the information is already
available in HTTP headers. LDPR representations
of discovery information may also be useful for scenarios where it would
be valuable to have the discovery data readily available for purposes such
as query.
</jra> 

6. "5.2.4 Servers SHOULD include the target URI of a Link:
<type-URI>; rel="http://open-services.net/ns/core#resourceType"
header on an HTTP response to a given Request-URI to indicate the type-URI
(i.e., rdf:type) for the type of resources that can be created by the LDP
Container."
Why "include the target URI of a Link"? Why not say "include
a Link header:...". Or perhaps you meant "include type URI(s)
as the target URI(s) of Link:... header(s)".
<jra>The target URI of the llink header is <type-URI>; as defined
by https://tools.ietf.org/html/rfc5988#page-7.
 Target URI is refering to RFC5988, not OSLC discovery</jra>
<MPP>I still don't understand
why we are telling them to "include the target URI". What does
that mean? I read this as telling them to include the Link header that
has a particular target URI. If that's true, I suggest we re-word it to
say that. For example:
"Servers SHOULD include the a Link: <type-URI>; rel="http://open-services.net/ns/core#resourceType"
header on an HTTP response to a given Request-URI with its target URI set
to the type-URI (i.e., the value of rdf:type properties) for the type of
resources that can be created by the LDP Container."</MPP>
 
<jra>Maybe I'm missing
your point. In 5.2.4, "Link: <type-URI>: rel='httpL//open-services.net/core#resourceType",
<type-URI> is the target URI of the link as per section 5.1 of https://tools.ietf.org/html/rfc5988#page-7.
Reworded to:

In a response to Request-URI on an LDPC,
servers SHOULD include a <code>Link</code> header with the
relation-type set to rel="http://open-services.net/core#resourceType"
and the Target URI set to the <code>rdf:type</code> of resources
that can be created in the LDPC. Note: since there is always some time
between when the test is done and when the creation request is sent, and
that there may be additional server enforced constraints on the creation
resource representation, there is no guarantee that a future creation request
will succeed.
</jra>
 
...
 
10. § 5.3.2. Same query about "the target URI of..." as in my
point 6 above.
<jra>Same answer - using Target URI as defined in RDF5988</jra>
<MPP>As above, I suggest:
"Servers SHOULD include Link: <constraints-URI>; rel="http://www.w3.org/ns/ldp#constrainedBy"
header on an HTTP response to a given Request-URI with its target URI set
to the constraint-URI of a resource that defines the constraints about
the to-be created resource representation against a LDP Container."</MPP>
 
<jra>Updated to:

In a response to an HTTP <code>POST</code>
or <code>PUT</code> method on a given Request-URI referencing
an LDPC, servers SHOULD include a <code>Link</code> header
with the relation-type set to rel="http://open-services.net/core#constrainedBy"
and the Target URI set to the URI of a resource that defines constraints
on the to-be created or updated resource representation in the LDPC. The
resource referenced by Target URI is RECOMMENDED to be a machine-readable
representation such as OSLC Resource Shape [[OSLCCoreVocab]], but MAY be
some variant or other constraint document. See [[LDP]] <a href="">http://www.w3.org/TR/ldp/#ldpr-gen-pubclireqs">section
about server published constraints</a>.
</jra>
...
 
12. §5.2.3: The requirement for this constrainedBy Link header to be on
the response to a failed creation request is not clear whether it is normative
or not, as it is attached to the example, not the compliance clause 5.2.3.
12b. It is also not clear whether we are explicitly saying whther the Link
header can be in a response to a GET on the LDPC itself or not.
<jra>You mean 5.3.2? The clause is normative since it is in normative
section 5.3, is not marked as non-normative, and isn't within the example
(all of which are non-normative). The clause doesn't specify the method
but would only apply to POST or PUT to create a resource.</jra>
<MPP>Thanks for adding the
clarification</MPP>
 
...
 
19. §5 intro and §A.3 (Service shape): A.3 says that a Service is an LDPC,
but I can't find anything that says what its members should/could be. SPCs'
and SPs' members are described at the end of the first bit of §5.0.
19b. The descriptions of the shapes for SPCs and SPs should probably re-state
what their members are expected to be.
<jra>I added LDPC to the descriptions of all shape properties that
are LDPCs: SPC: serviceProvider, serviceProviderCatalog; SP: service; Service:
creationFactory. queryCapability might be an LDPC too, but that might be
implementation dependent and/or depend on what the eventual LDP Query Syntax
becomes.</jra>
<MPP>I'd like to suggest
these further changes:
A.1 SPC:
"An LDPC describing an OSLC Server that offers one or more Service
Provider LDPCs (see below), MAY also organize the Service Providers in
one or more Service Provider Catalog LDPCs to enable OSLC clients to find
Service Providers offered. The members of these catalogs may include other
nested catalogs as well as service providers."
A.2 SP:
"A Service Provider LDPC whose members are the services offered by
an OSLC implementation"
A.3 Service:
"A Service LDPC whose members are the resources owned by the Service's
Service Provider and that are also of types defined by the oslc:domain
value on the Service. The Service resource also describes specific services
offered by a Server that implements an OSLC domain specification, and the
URIs to use for those services in the context of that OSLC domain and that
Service Provider." (please review this suggestion carefully, as it
may not be what we agreed as a TC when discussing LDPCs).</MPP>

<jra>Done, with some
slight modifications. In particular, we did not specify what domain (or
other) resources must be in a Service LDPC, leaving that choice up to the
server. All that is required to do that is for the server to include the
right link hearders, and for the creationFactory URI to be the URI of the
Service. From the client's perspective, it doesn't matter what LDPC the
domain resources are in. They will just use the LDPC URI in the creationFactory
or as discovered through link headers on LDPCs they might navigate to.

Also, there's no need to restrict
a Service to OSLC domain resources. Any resouce could be discovered.


A.1 SPC:
"An LDPC describing an OSLC server
that offers one or more ServiceProvider LDPCs. Servers MAY also organize
the ServiceProviders in one or more ServiceProviderCatalog LDPCs to enable
OSLC clients to find ServiceProviders offered. The members of these catalogs
may include other nested catalogs as well as service providers."

A.2 SP:
"An LDPC whose members are the
Service LDPCs offered by an OSLC server"

A.3 Service:
"An LDPC whose members describe
specific services offered by a server, and the URIs to use for those services
in the context of that ServiceProvider.
</jra>
 
Martin Pain

--------------------------------------------------------------------- To
unsubscribe from this mail list, you must leave the OASIS TC that generates
this mail. Follow this link to all your TCs in OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php