oslc-core message
[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)
- From: "Jim Amsden" <jamsden@us.ibm.com>
- To: "Martin P Pain" <martinpain@uk.ibm.com>
- Date: Fri, 18 Dec 2015 08:52:43 -0500
3. Should I remove the reference to .well-known
since we're not actually specifying any URIs?
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."
I suggest removing this clause. Its trying
to encourage a potential optimization. But LDP says that Link relationships
can be included in assertions in the LDPR response body. We've introduced
the ServiceProvider and Service resources which are LDPRs that do indeed
contain the same information that's in the Link headers. And the point
on being able to query discovery capabilities (which would not be possible
if the information is only in link headers) is a good one.
19.
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.
Should have been:
A.3 Service:
"An LDPC whose properties describe specific services
offered by a server, and the URIs to use for those services in the context
of that ServiceProvider.
That was a copy/paste error. Further discussion
in the comments on OSLCCORE-53.
Jim Amsden, Senior Technical Staff Member
OSLC and Linked Lifecycle Data
919-525-6575
From:
"Martin P Pain"
<martinpain@uk.ibm.com>
To:
Jim Amsden/Raleigh/IBM@IBMUS
Cc:
oslc-core@lists.oasis-open.org
Date:
12/10/2015 07:03 AM
Subject:
Re: [oslc-core]
OSLC Discovery top-to-bottom read feedback (sorry it's late)
Sent by:
<oslc-core@lists.oasis-open.org>
My comment in red again, and again removed
parts I'm not replying to.
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: 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">/.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">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-53for 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
--------------------------------------------------------------------- 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]