Review of OSLC Delegated Dialogs 3.0

[Ian Green1 <ian.green@uk.ibm.com>]

Here's a review of 

https://tools.oasis-open.org/version-control/svn/oslc-core/trunk/specs/dialogs.html

as at svn revision 323.

General comments
Reference links are not working - it
seems that fragment identifiers are not right: eg https://tools.oasis-open.org/version-control/svn/oslc-core/trunk/specs/dialogs.html#bib-RFC2119
.  (I know this is a known problem.)

Section 4 - It is not clear whether
the spec admits that other Link Relations are permitted for uses other
than selection and creation.  (The wording "Each dialog type,
creation or selection, has its own link relation" suggests that only
the two listed link relations is acceptable.)

The examples of the three mechanism
do not show what happens when there is more than one dialog resource of
a given behaviour (create/select).  In the service document, these
would be distinguished by different oslc:usage (or could be indistinguishable).
  Is this an intended  limitation of the Link and Prefer header
mechanisms?  If the Prefer header mechanism is permitted to indicate
oslc:usage in those representations, it would be helpful in the examples
for this to be shown.

Section 5
Typo: "The user has created or selected a resource
or canceled the dialog" - should be plural since more than one can
be created/selected.
I struggled with the wording of "JSON follows the
prefix in the message string " - i think this means "a stringified
json object will be concatenated to the message prefix."

Even though it is non-normative, I would prefer that we
don't suggest that the "olsc:label" in an oslc-response be a
substitute for information which ought to be obtained from the resource.
 Putting information from the selected/created resource into the oslc:label
encourages that information to be stored in another resource (and/or repository);
potentially this information is in a different security context from the
original.  A common use case for oslc:label from a dialog is when
a link is being created, and there is a temptation to use that label as
the link label (but that same label can be used in other ways, too).  Apps
should be wary of enabling this kind of denormalization.  IBM has
some guidance on the link label issue at https://jazz.net/wiki/bin/view/Reference/LinkLabels.
 There are already known security issues in existing OSLC deployments
because of this denormalization.

Section 5.4
This section could do with some editing.  It talks
about ServiceProvider, but is really referring to any dialog.  It
also mentions compact resource, which seems out of place in this spec.

Typo: "delegates dialog"

I don't much of this analysis/recommentation -- I cannot
usefully review this material..  Does item 1 refer to the dialog resource,
or the URI of the dialog resource?  To my reading, items 2 and 3 seem
to have nothing to do with clickjacking.  Is there a clickjacking
vulnerability in any implementation which does not do this?

If 2&3 were implemented, and 4 occurred, why would
SAMEORIGIN be a recommended X-Frame-Options - this system is being attacked
- why play along?  5 seems to be covering a different kind of resource
- not a dialog - why is that recommendation in this document?


Section 6
What does "effective" mean in "The context
URI is the effective request URI"?

Section 6.1.4 doesn't seem to be about discovery - in
the wrong section?  Also, in this section, the term "target resource"
is incorrect, it should be "resource".

Section 6.1.5 Is this not better in Appendix A - Resource
constraints?

Section 6.1.6 seems out of place in this document.  Is
this not just good http practice?  

Section 6.1.7 Is it clear what ServiceProvider and Service
resources are in this document?  I don't see any references or definitions.

Section 6.3.2 I don't see how a client wanting to use
windowname protocol would discover that a server supported it.  Since
a server is not REQUIRED to support windowname, clients are compelled to
support postMessage, or face failure.  I wonder then the utility of
optional support of windowname.

Since the OSLC 2.0 use of a fragment identifier is not
mentioned in this document, is some comment on backward compatibility needed
or are we okay leaving unsaid that a dialogue MUST be robust to unknown
fragment identifiers in window.location?  There is a tension here
with 6.3.4, which does not specify what happens when a client DOES use
#oslc-core-post-message-1.0?

Section 6.3.5 Example 22 seems superfluous and
it is also a duplicate of Example 11.  Shouldn't all of the examples
be in the non-normative sections of the document?

Section 6.4.3 should indicate a resource of RDF type oslc:ResourceShape
rather than just "resource shape".  Are there constraints
on the values of the oslc:resourceShape (if any) and the value of the oslc:resourceType
(if any)?  Since this spec allows prefilling of a selection dialog,
servers could offer constraints to be POSTed that constrain the selection
of resources.  Such constraints would have a different shape from
the shape of those of the resources being selected.  Is this intentional?

Section 6.4.6 I think "Clients SHOULD NOT
cache dialog URIs from prefill requests since they are often temporary.
" is beyond the scope of this document. A server can use whatever
cache-control headers it sees fit, and a well-behaved client will do the
right thing

Section 6.4.7 I'm not sure what this means.  Is this
stating that a prefilled dialogue URI should be treated as opaque by clients?
 If it is about ways to support prefill other than by POSTing a resource
representation to the dialog descriptor, how would a client know what those
parameters were or how to discover that the server supported this mechanism?



Apppendix A does not indicate
the use of oslc:usage - it should be zero-or-many. I expect this has been
omitted deliberately, but I'll raise it anyway just to be sure because
I can't think why.  oslc:resourceShape was oslc:Range oslc:ResourceShape
in 2.0 - was there a deliberate decision for this to be oslc:Any in 3.0?




best wishes,
    -ian

ian.green@uk.ibm.com (Ian Green1/UK/IBM@IBMGB)
IBM
Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number
741598. 
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6
3AU