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).
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...).
2. Section 5 typo?
"A ServiceProviderCatalog members include" -> "A ServiceProviderCatalog's members include" or "The members of a ServiceProviderCatalog include"
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.
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.
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.
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)".
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.
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."
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?
10. § 5.3.2. Same query about "the target URI of..." as in my point 6 above.
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?
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.
13. §5.6 Authentication Discovery: Should this also describe the oslc:OAuthConfiguration resource as referenced in A.1 (ServiceProviderCatalog shape)?
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."
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?)
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".
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.
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).
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.
Martin Pain