Re: [oslc-core] Delegated Dialogs 3.0 Ready for Review

[Samuel Padgett <spadgett@us.ibm.com>]

Martin Pain writes:

> "Resource selection: when a user of a web application and needs to
> pick a resource managed by another application " - remove "and".

I'll fix.

> What about a selection dialog that allows creation? It would be
> useful to be able to indicate that to the client so they can offer a
> single option (if that's what they want to do). As this stands, they
> could have three Link headers: one selectionDialog to dialog A, one
> creationDialog to dialog A, and one creationDialog to dialog B (the
> creation-only one). But clients not looking out for the creation-
> and-selection-dialog-at-same-URI might not know which of the
> creationDialog ones to pick for the standard creation dialog. Does
> anyone think this use case would be worth supporting? It's already
> on the use cases wiki page: https://wiki.oasis-open.org/oslc-core/
> DelegatedUIUseCases#Selection

It's a good use case and probably not hard to add. A few ways we could
do it:

1. Add a new Link relation that indicates both creation and selection.
2. Add a multivalue RDF property in the descriptor to indicate the type,
   possibly in addition to (1). Clients can then see it's both.
3. Let clients simply check if the same dialog descriptor URI is in both
   the creation and selection links.

Thoughts on what's best?

> Example 7 dialog URI is the descriptor URI from the previous
> example. should end with "/form2

Yes, I'll fix.

> ex 8 " Make sure the message originated from example.com." might be
> better to say "from the expected OSLC Server".

I'll reword.

> 5.2 "Once the user has created, selected, or cancelled, send
> notification using postMessage to the page's parent window, passed
> in event.data string, that is prefixed with "oslc-response:"."
> "canceled" -> "cancelled"

They're both correct. US vs British spelling :)

> Also I suggest: "...parent window, passing the URI of the created or
> selected resource in the oslc:results JSON format in the event.data
> string, that is prefixed..."
> or just omitting the bit about "event.data" in the sentence as it
> stands - if we're not saying everything about how to put the data in
> the postMessage call, then mentioning event.data seems to have no
> value. The terms "oslc:results", "oslc:label" and "rdf:resource"
> seem to only be in the example, not in the text (at least having
> only read to this point), so I don't see why event.data needs to be
> any different, and it seems to stick out a bit where it is.
> (A link to appendix C might also be appropriate.)

Thanks, I'll rework this.

> 5.3 is ambiguous as to whether it's talking about the dialog URI or
> the dialog descriptor URI. The examples use the URI used for the
> descriptor by the previous examples, which I expect is inconsistent.

It should be the descriptor. I'll make it clear.

> 5.3: We mention oslc:resourceShape and then immediately follow it by
> an example which is not related. It might be useful to have an
> example, but even if we don't I'd suggest we put a sentence before
> the example saying what we're about to show an example of.

Agree, I'll rework this.

> 6.3.10: Should we mention dynamic resizing earlier, in the non-
> normative text? Otherwise the only reference to it is buried in the
> normative compliance statements.

Yes, I'll add something.

> 6.4.1: Slight improvement in clarity: "Servers MAY allow clients to
> prefill creation dialogs by the client sending an HTTP POST request
> to the dialog descriptor URI where the entity body is a resource
> representation describing the initial values. "

Agree.

> Appendix A doesn't mention the term "dialog descriptor". I'd suggest
> it should, probably in the summary, possibly in the section title as
> well if possible.

I'll fix.

> Appendix B - vocab: selectionDialog and creationDialog could say
> something about the type of resource they are likely to be pointing
> to (e.g. "expected to point to a dialog descriptor"), and possibly
> about the meaning of the subject URI on the contect of the dialog,
> e.g. that the dialog is to select/create a resource from/in the
> context of the subject/anchor of the link.

I'll defer to Steve and Author on best practices here for the
vocabulary. I'm not sure we should discuss Link header in the context of
an RDF vocabulary, though. This section is generated from

http://tools.oasis-open.org/version-control/browse/wsvn/oslc-core/specs/dialogs-vocab.ttl

> Appendix C mentions the "oslc-response:" prefix but the example
> doesn't use it. As that is the only place this JSON is used, I
> suggest we include the pefix in the example.

Since this section is about the JSON format, I wanted it to be valid
JSON. Maybe I can update the wording to make things very clear.

> We could also mention in this appendix that this JSON goes in the
> "data" property of the postmessage event, if we remove the mention
> of event.data further up as I have suggested.

Makes sense.

> Also, looking through the DelegatedUIUseCases wiki page:
>
> General.1: It mentions "mobile-specific guidance", which we haven't addressed.

Yes, I have prototyped something and plan to follow up with an email.

> Have we agreed as a TC which use cases are in scope & out of scope?

I think we should discuss at the next TC call.

San