[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [oslc-core] OSLC Discovery top-to-bottom read feedback (sorry it's late)
----- 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: Wed, Dec 9, 2015 5:30 PM
Comments below yours in green.
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>
...
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" target="_blank" >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>
<MPP>If they're using branded ones, then it's vendor-specific, and I don't believe there's a need for it to be under .well-known. It can be any path they choose.
My understanding of the reason for .well-known is this: that the meaning/purpose/use of URIs is defined by the server (authority) identified in that URI, with the sole exception of .well-known paths, which can be registered by other parties (such as OSLC). If other parties & specifications only define paths in .well-known, and individual servers only define paths outside of that, then there will be no collisions. For example, it would be perfectly valid for a server to respond to GET /robots.txt (c.f. http://www.robotstxt.org/) with a text document saying "R2D2, Bender, Marvin, Robot Santa", even if this would confuse web crawlers. However, it would not be valid for them to respond to requests under .well-known paths in any way other than defined by the well known paths registry.
Therefore (to get to my point), if a given server or vendor wanted to define their own discovery path (e.g. /rootservices) then they could use any path, as they own the URIs under that server so can choose any of them. However, having said that, I suppose there would be a benefit to registering a .well-known one as they you know that if you get a response it really should be for the expected purpose.
In any case, I think it has very narrow applicability here and is adding more "noise" than useful information. Perhaps we can talk about it at the meeting today, but I'd be happy just to see if there's an initial consensus (or majority) and go with that.</MPP>
...
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>
<MPP>Slight suggested modification in 2nd sentence:
"Servers SHOULD NOT include discovery information in entity response bodies if the information is already available in HTTP headers. Including discovery information in entity response bodies may also be useful for scenarios where it would be valuable to have the discovery data readily available for purposes such as query."
However, aren't we now contradicting ourselves between the 1st and 2nd sentences?
</MPP>
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>
<MPP>That's good, go for it.</MPP>
...
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" target="_blank" >http://www.w3.org/TR/ldp/#ldpr-gen-pubclireqs">section about server published constraints</a>.
</jra>
<MPP>That's good, go for it.</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>
<MPP>I disagree with the Service one, as I don't expect that the creationFactory/queryCapabilitie/dialogs/etc will be members of the LDPC. Instead, I see them as just having links/triples from the Service (with their own properties inlined, of course). If the creation factory's creation URI is expected to point to the Service's URI, to use the LDP-defined creation semantics:
1. Do we tell the readers that?
2. That means that the Service is an LDPC whose members are the resources that are created by the creation factory/ies and creation dialog/s in that Service (and probably also the resources that are retrievable by the query capability/ies and selection dialog/s). So we could say that.
Revised suggestion:
"A resource that describes the creation and discovery (selection) of resources of one or more specific types in the context of that ServiceProvider. The scope of a Service may be an entire OSLC domain (or 3rd party-defined domain) within that ServiceProvider, or a server may have a Service for each LDPC in its existing or desired architecture. Each Service may itself be the LDPC of the resources are created or discovered through it."
However I don't like the idea of allowing arbitrary separation of resources between Services. My understanding of v2 is that a user never needs to select a Service resource (where they may have to select a SP or a nested SPC based on their title) - the client should know what domain it is looking for, so it selects Service from the SP in question based on that domain. According to OSLCCORE-23, we agreed that "Service is the point at which Domain specifications specify their specific service capabilities." - which suggests the tie between domains and Service resources. Of course, it doesn't have to be an OSLC-defined domain, but in my opinion it must be a value of the oslc:domain property on the Service. And that it is unreasonable to expect clients to be able to work with two Service resources with the same oslc:domain value, unless explicitly permitted by that domain.
So I think we have a question to answer, which probably requires its own ticket: Do we keep the one-to-one relationship between Service resources and oslc:domain values from v2 (within the context of a single SP, and if that understanding of v2 is correct), or do we re-define it and suggest/require that a Service is one-to-one with an LDPC (if not exactly the same resource) in the server's desired organisation of containers?
The benefit of the former is that clients have fewer options to present to users, and that v3 servers are more likely to work with v2 clients (although that could do with verification). The benefit of the latter is that the server's organisation of containers is exposed in the OSLC data, but this comes at the cost of complexity for the clients.
I've raised OSLCCORE-53 for this.</MPP>
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]