Re: draft_protocol

[Gary P Cole <Gary.P.Cole@Sun.COM>]

Gearard Woods wrote:

> 3.1.1.3.2 & 3.1.1.3.4
> Spec says that the request ID SHOULD be globally unique. I don't think 
> this is a reasonable requirement especially for a request identifier, 
> which is really conversational state between the client and a specific 
> provider in my view.
>
Done. Removed the offending sentences.

> 3.1.2
> Minor point - Use of the term Singleton. This term is a little 
> overloaded these days with its use in Design Patterns. Should we come 
> up with a better term?
>
Done. A request that describes a single operation is now simply called 
an "individual" request.

> 3.3.1
> We talked about this on the call. PSO-IDs should not be required to be 
> globally unique in my mind.
>
Done.  A PSOIdentifier must uniquely identify the object to the 
provider.  Since a PSO-ID also specifies the target that ultimately 
contains the object, the 'identifier' portion must be unique only within 
(the namespace of) the target.

> 3.4.1.1
> On the question of schemas being necessary in the document, my feeling 
> is that if we remove them then we should include UML diagrams or 
> something else to illustrate the major elements of the schema under 
> discussion.
>
Do you know that we have an entire section (4) dedicated to schema?  
Just to be clear, my question is whether I should continue to have at 
the top of each 'operation' section the schema snippets relevant to that 
section, since these are redundant with the Schema section.

> 3.4.1.1.1
> We talked about this on the call. My opinion is that listTargets MUST 
> be synchronous.
>
Done.  It is now an error to request or to execute listTargets 
asynchronously.

> 3.4.1.1.2
> I'd rephrase the schema section to remove the repetition of "open 
> content". I'd also rephrase the capability section a little:
> "A <target> element MAY contain any number of <capability> elements. 
> Each <capability> element MUST specify (as the value of its identifier 
> attribute) a namespace that contains an XML schema. "
> In my book the namespace doesn't really "contain" an XML schema.
>
Done.  This now says that the required 'identifier' attribute specifies 
an XML namespace and that an (optional) 'location' attribute specifies 
the URL of an XML schema.

> It might also be good to list here (or maybe this belongs in an 
> appendix) the set of approved SPML capability namespaces and what they 
> mean. Perhaps the "Concepts" section might shed some light on this too.
>
The standard capabilities are grouped together in the remainder of the 
protocol section (which I did not send).  This Schema section is 
organized in the same way, with a section that describes the core 
elements that is followed by a section for each of the standard 
capabilities.

If we need it, I'll add a list to the Concepts section upfront.

> Not sure about the relationship between capability operations and 
> SpmlRequest/Response. As a SHOULD this seems a little meaningless.
>
This is probably a good issue for the list.  I thought about this, and 
saying SHOULD was as far as I was prepared to go without group buy-in.  
It seems to me that optional operations should be defined as 
request/response pairs that extend SpmlRequest and SpmlResponse, but I 
don't think we'd ever discussed this.  AFAIK, nothing precludes an 
optional operation being defined "out-of-band"....

> Would it be better to outline the restrictions that apply if the 
> operations do not extend the core SPML operations? For example, for 
> operations to be sent in batch mode they must be derived from the 
> BatchableRequestType.
>
We could do this.  What are the consequences of a request does not 
derive from SpmlRequest type, or of a response that does not derive from 
SpmlResponseType?

> I think the ObjectClassRefType is clunky. I know this name is set to 
> change ( which I agree with whole heartedly) but I would also like to 
> see the attribute names change. I'd also like to see this in an 
> element and perhaps as a union or just a plain string.
>
That sounds great, but that's another one for the list.  Do you have any 
specific suggestions?

> 3.4.1.1.3
> In the example:
> - The XML Processing Instructions should be removed.
> - Capability identifiers should be namespaces.
> - There's no need to have fully-qualified result code values.
> - The documents aren't well-formed (supports inside XML schema 
> element, no terminating XPML schema element)
>
Done (although the examples still may not be well-formed).

> 3.4.1.2.2
> Add response should return (optionally) the PSO state. The PSOType is 
> the problem here. This used to be in the schema but seems to have been 
> removed - and it's not enough to say that it could be returned using 
> the "open content model". This also applies to other operations such 
> as lookup. Is there something I'm missing?
>
No, I erred.  The 'add' operations *does* return a PSOType.  I've now 
corrected this.

> I'd prefer to break out the use of capabilites into a separate section 
> so that the basics are clear.
>
Can we wait and see on this point?  We've defined capabilities as part 
of the core (in that targets can declare support for capabilities and in 
that capability-specific data can flow through the core operations).  I 
think that the examples for core operations should show how 
capability-specific data flows through core operations.  The alternative 
is to show examples of each core operation *again* within each 
capability section.

> 3.4.1.3.1
> Should lookup allow asychronous operation?
>
I cannot imagine wanting an asynchronous lookup, but I didn't feel 
certain enough of this to say that it couldn't.  Should we float this 
one to the list?

> I agree that the identifier should be required.
>
Right; we covered this on the call.  Jeff Bohren will correct the XSD.

> 3.4.1.3.3
> The example is incorrect. If the open content model is used to return 
> the Person element then it must appear in the sequence (because it's 
> defined as a sequence) before the identifier.
>
I've moved the Person element before the identifier.  Still not sure 
that I have it right.

> Again, I'm opposed to the idea of using the open content model to 
> return the state of a PSO. As I said before, I think the open content 
> model should be primarily for things that are beyond the scope of the 
> spec, or are application-specific. We know that we wish to return the 
> state of a PSO so we should state that explicitly. This also, as in 
> this example, has a counter-intuitive implication for ordering of 
> elements.
> the same applies for the capability example.
>
We are using a <pso> element, so the content is not completely open.  Is 
there more I should do?

> 3.4.1.4
> Modify obviously needs work.
>
Yes.  I have corrected the most obvious deficiencies in this section.

>
> - There is no way to provide the actual data to be replaced or added. 
> This leads to the mixed content in the example which is something that 
> we do not want to propose as far as I'm concerned. Again, using the 
> open content model for this is inappropriate in my mind.
>
This sounds like one for the list, right?

> - Shouldn't the reference in the capability example be provided in a 
> capabilityParameter?
>
Yes.  That was my mistake.

> - The SelectionType appears to be unused in modify. How are specific 
> elements identified? An identifier is not enough. I thought we had 
> already agreed to allow XPath 1.0 syntax. In my book, "component" 
> should be a SelectionType not an IdentifierType. However:
> - The SelectionType is inadequate. There is no ability to define a 
> namespace-prefix mapping.
>
Another one for the list.

> - I think we should allow multiple modifications to a PSO without 
> having to issue multiple modify requests in a batch.
>
Well, we did define a Bulk Capability that allows bulk modifications. Is 
this good enough? 

As I read the XSD, a modifyRequest contains exactly one modification.

> 3.4.1.5.2
> Delete should allow the state of the deleted item to be returned (not 
> using the open content feature)
>
I see no provision for this in the current XSD, and I'm not sure that I 
agree.  If you want the state, you can 'lookup' before you 'delete'.  To 
the list?

> In general:
> Capability-related examples should include namespaces to make it clear 
> how the provider and client identify capabilities.
>
That makes sense.