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

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

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 know that we were supposed to review the
Discovery spec a while back, but I've only just got round to doing a fresh
top-to-bottom read. Sorry for the delay. (Also, apologies for my absence
without notice from the previous meeting - I was off ill for a number of
days that week).
 
I've got a number of points of feedback.
Most are things that I think could be worded clearer. There are a few things
that look like typos. And there are a couple of things that I think are
missing (namely, the results of the discussion on bootstrapping discovery,
and any mention of the OAuthConfiguration resource in the authentication
section). 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. The other
things hopefully can be addressed quickly (although he bootstrapping one,
if we do anything about it, might require some agreement on how to say
where to start, given that it's not standard).

<jra>I'll look at putting
something in for bootstrapping discovery and OAuthConfiguration (other
that what will be provided in core-vocab.html). I need to check if the
OAuthConfiguration properties in OSLC2 were based on OAuth1.0 and may not
be something we want to standardize on in OSLC3 other that the statements
already in the authentication discovery section. Why were these properties
included at all in OSLC2? Why are they needed for integration and interoperability,
or not defined by OAuth itself?

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>
 
 
 
1. Typo:On the discovery
spec, the abstract says "This
document outlines a common approach for HTTP/LDP-based server to be able
to publish their RESTful API capabilities and how clients discover and
use them."
I expect it should either be "for HTTP/LDP-based
servers" or "for an HTTP/LDP-based server" (or "a"
in place of "an", depending on how you read it...).
<jra>changed server to
servers</jra>
 
2. Section 5 typo?
"A ServiceProviderCatalog members include"
-> "A ServiceProviderCatalog's members include" or "The
members  of a ServiceProviderCatalog include"
<jra>Changed to: The
members of a ServiceProviderCatalog resource include</jra>
 
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>
 
4. "5.1.1 Clients SHOULD use
HTTP OPTIONS to fetch various headers and other configuration information
that may be exposed in the response content body." - the combination
of talking about OPTIONS along with "the response content body"
is a little confusing - to what response content body is it referring?
The response if you were to make a GET request? How would you get that
information from an OPTIONS request? It doesn't tell the reader.
</jra>... in the response
content body from other HTTP methods.</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>
 
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>
 
7. (5.2.4 again) Also, in place of "(i.e.
rdf:type)", I probably would have said "(i.e. rdf:type values)"
or, more verbosely, "(i.e. the values of rdf:type properties)"
or "(see rdf:type)". So as to avoid implying that the "rdf:type"
predicate is the "type-URI" itself.
<jra>changed to: (i.e.
the values of rdf:type properties)</jra>
 
8. § 5.2.5 "...when converting HTTP
response headers for the same Link-relation type, into an RDF triple".
I don't understand why the words "the same" are in there. Does
it mean "...when converting HTTP Link headers which have "rel=type"
into an RDF triple". Under that reading I'm assuming that "the
same" means that the header and predicate will have the same type-URI,
but if you're converting the header then I take that as a given.
Ok, I've now looked at the example that follows
it. I'd suggest "...when converting HTTP Link headers that have "http://open-services.net/ns/core#resourceType"
as the Link-relation ("rel" value) into RDF triples."
<jra>applied the recommended
change</jra>
 
9. The example following 5.2.5 doesn't make
it clear what it is an example of. It looks liek it is demonstrating 5.2.2
(Accept-Post), 5.2.3 (LDPC "type" Link header) and 5.2.4 (resourceType
Link header).
9b. As It isn't demonstrating 5.2.5, is there
a way to give it is own section number without making it appear like it
is a compliance clause itself?
<jra>Changed the intro
to the example to: "The following
example is an OPTIONS request on the /bugs/ resource that demonstrates
some of the discovery capabilities.".
The text following the example provides the detailed explanation.</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>
 
11. §5.3.2 again: It refers to [OSLCShapes2].
Did we decide to move resource shapes into Core v3? In which case should
this be referring to shapes v3 instead? Or did we just move the resource
shapes for the resource shape resource types into v3?
<jra>This should refer
to core-vocab.html where ResourceShape is defined. I removed the reference
to OSLCShapes2, it is no longer used.</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>
 
13. §5.6 Authentication Discovery: Should
this also describe the oslc:OAuthConfiguration resource as referenced in
A.1 (ServiceProviderCatalog shape)?
<jra>Yes, I added a reference
to OAuthConfiguration in core-vocab.html</jra>
 
14. §A.1 SPC shape. The oslc:serviceProvider
description reads "A service offered by the service provider."
which is wrong. Perhaps it should be "An oslc:ServiceProvider that
is listed in this catalog."
<jra>This was copied
from OSLC2. Changed to: "A service provider offered by this server".</jra>
 
15. §A.1 again (SPC shape): This was the
case in v2 (so perhaps we can defer this), but I don't see why we set "read-only"
to true for these properties. I would have thought some servers might allow
clients to create new ServiceProviders, or modify ones they previously
created. e.g. a generic ServiceProviderCatalog server that acts as a registry
of other servers. I'd suggest we have read-only as not specified (if that
won't be problematic), but this is probably too big a thing to consider
at this stage. It's not really causing a problem.
(Note: dcterms:identifier on oslc:Publusher
- §A.6 - has an "unspecified" read-only value. Should it be consistent
with the others?)
Raised ticket: https://issues.oasis-open.org/browse/OSLCCORE-38
<jra>oslc:Publisher dcterms:identifier
read-only is unspecified in OSLC2. Probably useful to leave it that way
since that might be the preferred value for many of these constraints.</jra>
 
16. All shapes: I expect the "representation"
for properties of value-type "XMLLiteral" should not be "either",
as they currently are. Other specs list it as "n/a" (presumably
in the shape RDF the representation property should be omitted). Also for
ones of type "string".
<jra>This is a ReSpec
bug. Representation is not specified for any Property whose valueType is
XMLLiteral. I raised an issue: OSLCCORE-51
</jra>
 
17. §A.2: oslc:details: I know we changed
this to not require it to point to a web page, but now we don't
even offer that as a suggestion. I'd suggest appending "such as a
web page describing it" to the end of the description.
<jra>Added this to the
description</jra>
 
18. §A.3: Service shape, oslc:usage property.
The description reads "default". v2 said "An identifier
URI for the domain specified usage of this service. If a service provider
has multiple services, it may designate the primary or default one that
should be used with a property value of http://open-services.net/ns/core#default".
Similarly on CreationFactory (A.4) and QuryCapability
(A.5).
<jra>The description
in the Service-shape.ttl file is "If
a resource has multiple uses, it may designate the primary or default one
that should be used with a property value of http://open-services.net/ns/core#default."
ReSpec doesn't like that # in the property value, seems to make it ignore
everything before the #. Using oslc:default works correctly and translates
the oslc: prefix properly.</jra>
 
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>
 
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