RE: [xri] Feedback on section 12 of WD11-ED06

["Drummond Reed" <drummond.reed@cordance.net>]

Wil, thanks again for the very detailed feedback. See [=Drummond] inline for
the disposition of each item. A handful may take further discussion. I
marked each of these at the end of my response with *****MORE DISCUSSION
NEEDED?***** to make them easy to spot. I'll leave it up to you to decide
yes or no. Feel free to peel these items into new email threads if that's
easiest -- I'm trying to have all these final decisions documented on the
email list.


> -----Original Message-----
> From: Tan, William [mailto:William.Tan@neustar.biz]
> Sent: Tuesday, October 23, 2007 12:50 PM
> To: XRI TC
> Subject: [xri] Feedback on section 12 of WD11-ED06
> 
> Here are my feedback on the service selection section of ED06. The line
> numbers are based on the word document after accepting all changes.
> 
> 
> 12.1 Line 2211 - "For each xrd:Service element in the final XRD,
> selection MUST follow the service endpoint selection logic defined in
> section 12.2".
> This seems like we are prescribing a single for loop, even though the
> full process is described in 12.2. Perhaps something more like "Section
> 12.2 describes the processing logic for selecting a set of SEPs from the
> final XRD based on the QXRI and other resolution input parameters"?

[=Drummond] I made this clearer by wording it as follows:

3.	For each the set of all service endpoints (xrd:Service elements) in
the final XRD, selection MUST follow the service endpoint selection logic
defined in section 12.2. The outcome of this process will be a selected set
of zero or more service endpoints.



> 12.1 Line 2220 - s/241/221/

[=Drummond] Good catch. Fixed.

 
> 12.1 Line 2222 - I'm not sure if we should be defining Output Formats in
> section 7. The output formats seem very specific to the proxy resolver.
> IMHO the output of core resolution logic should be defined as an
> abstract data type, rather than concrete format.
>  For example, OpenXRI returns a data structure, not a DOM document, for
> the resolveSEPToXRDS method.

[=Drummond] No one has ever raised this issue before. The outputs of XRI
resolution have always been defined to be an instance of one of the 3 media
types we specify in the spec (application/xrds+xml, application/xrd+xml,
text/uri-list), or, for a proxy resolver, an HTTP(S) redirect. I don't think
it's a problem for a local resolver to return something else, but it seems
like it's out of scope for the spec. Maybe in section 7 we should state
something like that. What do you think?

*****MORE DISCUSSION NEEDED?*****


 
> 12.2 Line 2226 - "Selection of service endpoints (SEPs) within an XRD is
> managed using service endpoint selection elements (SELs)."
> Rather than introducing SELs here, we should talk about the general
> processing logic, something to the effect of "Selection of service
> endpoints (SEPs) within an XRD involves applying SEP matching rules
> (12.4) and SEL matching rules (12.3) to the set of all SEPs in the XRD,
> then applying SEP selection rules (12.5) to determine the output".

[=Drummond] Done.


> 12.2 Line 2227 - "As defined in section 4.2.6, xrd:XRD/xrd:Service
> elements may contain three categories of selection elements: xrd:Type,
> xrd:Path, and xrd:MediaType."
> When I first looked at section 12.2, I immediately zoomed in on the
> flowchart (ignoring the introductory paragraph) so I missed the sentence
> above. And when I got to section 12.3.1 line 2236 where it talks about
> "three categories of selection elements" I realized that I've not been
> introduced to the three categories. Some readers may be like me.
> I suggest moving the sentence above into the introductory paragraph of
> section 12.3 because it is the logical place to introduce the three
> categories of SELs.

[=Drummond] Done.

 
> 12.3.1 Table 21 - the precedence column begs some explanation, but I can
> only find mentions of it in 12.3.5. It seems that "precedence" is
> important for two reasons, of which 12.3.5 (multiple SELs matching rule)
> is one of them. The other reason is that Match Option is tri-state, so
> if an SEL is not a positive match, it doesn't automatically make it
> negative. I think there is a tendency for people to think -(+1) = -1

[=Drummond] I added text highlighting your points.

 
> 12.3.2 Table 22 - should we add two other states to the "value" column -
> /other/ and /absent/? This will complete all possible states of the
> match attribute (aside from empty string, which I will list separately
> below). It would be easy for the reader to have a glance at the table
> and know everything about how to process the match attribute.
> If we do that, then the literal values should be quoted, i.e. "any",
> "default", "non-null" and "null", while /other /and /absent /are
> unquoted. We should specify the behavior for the resolver when it
> doesn't recognize the value (/other/).

[=Drummond] I agree we should specify the behaviour if the match attribute
is present but contains another value, or if it is absent, but I don't agree
that we should do it in the table. (I think it's more confusing if a table
of enumerated values includes values that aren't one of the enumerated
values.) So I did it by adding one sentence to the para before the table.

 
> 12.3.3 Line 2253 - s/UNLESS the overriden/UNLESS overriden/

[=Drummond] Fixed.

 
> 12.3.4 - why do we need this special rule? Isn't it backwards
> incompatible with WD10? This seems to conflict with the definition in
> section 12.3.2 that when the match attribute is absent, use the content.
> In this case the content is null, so it should just be equivalent to
> match="null".

To the contrary, adoption of this rule solved a big ambiguity in WD10,
because it was unclear what happened with empty elements. There was a lot of
discussion about this last spring, and this was the unanimous decision. The
conclusion was that empty elements were a poor way to express that you
wanted match="null" because that's a relatively rare condition -- it would
be much better in for that specific case to explicitly require match="null".

By contrast, having a particular selection element (e.g., MediaType) simply
not be relevant to selection of a SEP is far more common. And it's more
intuitive that, if a selection element doesn't matter, the XRD author should
just be able to leave it out. Since we have a rule throughout the spec that
the absence of an element or attribute and its presence with an empty value
must mean the same thing, we defined both in this case to mean a DEFAULT
match. It doesn't conflict with 12.3.2 because we explicitly defined this
rule.

*****MORE DISCUSSION NEEDED?*****

 
> 12.3.5 - propose to move into 12.3.1.

[=Drummond] I understand your motivation here, but however we're received
positive feedback about making the rules throughout this section very clear
and easy to reference. The progression within 12.3, for example, currently
goes:

	12.3.3 Absent Element Matching Rule
	12.3.4 Empty Element Matching Rule
	12.3.5 Multiple Element Matching Rule
	12.3.6 Type Element Matching Rules
	12.3.6 Path Element Matching Rules
	12.3.6 MediaType Element Matching Rules 

I'd hate to remove one of the rules that implementers would explicitly look
for on this list -- "What do I do if there are multiple matches on the same
category of element?" -- so I'd much rather leave it explicit in its own
section.

Ping me back if you feel very strongly about this.

 
> 12.3.6 - line 2269 and everywhere else - I propose that we don't allow
> the match attribute to be empty. It seems to be more a programming error
> to me if the match attribute is empty. By allowing this possibility, we
> are giving more ways to express the same meaning to XRD publishers and
> that might hurt interoperability and/or makes XRD harder to understand.

[=Drummond] We just got finished adding the following rule to the Input
section (line 866, section 7.1 of ED06):

	1. The presence of an input parameter or an XRD element with an
empty value is treated as equivalent to the absence of that input parameter
or XRD element.

Although that rule doesn't specifically mention attributes, right now we
treat empty attributes uniformly throughout the spec: it is the same as if
the attribute was absent altogether. That rule is simple and uniform so I
don't think it hurts interoperatiblity at all.

The alternative would be to make a special exception for this attribute and
define a special error condition. Do you think that's worth it?

*****MORE DISCUSSION NEEDED?*****



> 12.3.6 - line 2272 - "if an XRI, IRI, or URI does not include a local
> part, a trailing forward slash MUST be assumed" - that MUST NOT be
> assumed because for certain URI schemes, there simply isn't a local
> part. We should simply defer to the XRI and IRI syntax.

[=Drummond] I clarified that by changing the wording as follows.

	1.	The values of the Service Type parameter and the
xrd:XRD/xrd:Service/xrd:Type element SHOULD be normalized according to the
requirements of their identifier scheme prior to input. In particular, if an
XRI, IRI, or URI uses hierarchical syntax and does not include a local part
(a path and/or query component) after the authority component, a trailing
forward slash after the authority component MUST NOT be considered
significant in comparisions. In all other cases, a trailing forward slash
MUST be considered significant in comparisions.

The reason I don't think we can just "defer to the XRI and XRI syntax" on
this trailing-slash-after-authority-component issue is that neither of thos
specs weigh in on the question of whether a trailing forward slash after the
authority component is significant in comparison. The OpenID folks have
spent hours and hours on that ambiguity. We'll do everyone a favor by being
explicit in our spec that if the identifier uses hierarchical syntax, a
trailing slash after the authority component is NOT significant in
comparison -- and in all other cases it is signficant in comparison.


> 12.3.6 - line 2275 - s/comparisions/comparisons/

[=Drummond] Fixed.


> 12.3.6 - line 2277 - "XRI resolvers MAY perform normalization of these
> values but MUST NOT be required to do so." This seems strange to me. XRI
> resolvers may normalize the value for comparison, but because XRI
> resolution (esp. w.r.t. Type element) is a much more controlled
> environment than the open web, we can probably just specify
> "Syntax-Based Normalization" in RFC3986. However, we are not saying that
> resolver normalize the value and place it back into the element, so we
> need to be clear that normalization is for comparison purposes only. And
> if we normalize, we should also normalize the

[=Drummond] It looks like you forgot the last part of your sentence. In any
case, I added wording to make sure that normalization is only for purpose of
comparison.


> 12.3.6 - Type element is in URI normal form, right? We should probably
> make it clear.

[=Drummond] It's already specified in that section (second to last sentence
of list item 1.)


> 12.3.6 - line 2281 - "Any other result is a NEGATIVE match". Make it
> clear that this is an per-SEL match result (POSITIVE/DEFAULT/NEGATIVE),
> and not the per-category match option. I realize that we don't actually
> talk about the per-SEL match result and it could be confused with the
> per-category one specified in 12.3.1. It's only in the pseudocode that
> the distinction can be discerned.

[=Drummond] I added text to 12.3.6, 12.3.7, and 12.3.8 to clarify that the
match is a per-SEL match only.


> 12.3.7 - line 2287 - "If the value is a relative XRI or an IRI"
> s/or an IRI/or IRI/
> OR
> s/or an IRI/or a relative IRI/

[=Drummond] Fixed.


> 12.3.7 - line 2293 - s/, with the exception that it is not necessary to
> perform normalization after case folding.//
> This probably originated from me, and I've tried to look for clues as to
> why we specified this way several times, and I looked _everywhere_ but
> couldn't find any reason. I know section 3.13 of Unicode did say
> "Normalization is not required before case folding, except for the
> character U+0345...", but that is _before_, and we don't save much by
> saving that step because implementations still have to normalize after
> case folding. In any case, I'm also thinking to change the MUST into a
> SHOULD, because it would be hard for scripting languages to comply, and
> I'm not sure if we want to call them non-conformant to the spec.

[=Drummond] You're the expert on this one, Wil. I made both changes. 


> 12.3.7 - line 2302 - "MUST be a NEGATIVE match", as above (line 2281)

[=Drummond] Done.


> 12.3.7 - table 23
> See my previous email in reply to Gabe regarding the stripping of
> leading slash from the Path value.
> I have issues with a few examples, but would like to first discuss the
> above before delving into them.

[=Drummond] Yes, let's close on this via the thread on the list; whatever
the decision is there I'll reflect in ED07.


> 12.6 - line 2369-2371: s/Matched/Seen/
> I think the semantic of these flags is more accurately conveyed as
> "seen" rather than "matched".

[=Drummond] Good point. After looking it over, I suggest that "Present" is
even better than "Matched" or "Seen" as it lines up directly with the
wording in the spec. I'll make that change unless you think something else
is even better.


> 12.6 - pseudocode - I think this is great - very readable and clear.
> Should you want to shorten it, though, I managed to save 13 lines by
> doing some optmization (which may sacrifice a bit of readability). Let
> me know if you're interested.

[=Drummond] 13 lines! That's a lot. I'd love to see it just to understand
how you did it. As far as the spec goes, though, the primary purpose of
pseudocode is readability, so my intuition is only to shorten it if it
becomes *more* readable, not less. But please do post it, to the list or the
wiki if you get a chance
(http://wiki.oasis-open.org/xri/XriCd02/SepSelection is the page to add it
to).


> 12.7.2 Table 25 - s/plus/including/g - "plus" may sound like a
> concatenation operator.

[=Drummond] Good call. Done.


> 12.7.2 Table 25 - should we explicitly say that fragment should not be
> included for the "local" value?

[=Drummond] It's already defined in section 7.1.1 of ED06 that a fragment is
never part of a QXRI, but I put a reminder in the table anyway.


> 12.7.6 line 2476 - should not allow append value to be empty.

[=Drummond] See my response above. Again, if you feel strongly enough, we
could make this an exception to the spec-wide rule, and define a special
error for it, but IMHO there would need to be a very, very strong case to do
this.

*****MORE DISCUSSION NEEDED?*****



> 12.7.6 line 2482 - s/QXRI component specified/QXRI component in URI
> Normal Form specified/

[=Drummond] Done.


> 12.7.6 line 2487 - "If the value of the QXRI component specified in
> Table 25 is null ..."
> Do we need this sentence? It's more explicit but seems redundant to me.

[=Drummond] Explicit is good. Victor pounds on me to be ultra-clear about
stuff like this.


> 12.7.6 line 2497 - By applying URI construction during authority
> resolution, we are allowing components of the QXRI other than the
> authority to be used as inputs to authority resolution, which I'm
> nervous about.

[=Drummond] Ah, there's a different way to think about this: that you're NOT
allowing "components of the QXRI other than the authority to be used as
inputs to authority resolution", but only that you're allowing the SEP
author to dynamically compose the URI for their authority resolution service
endpoint. That's different than changing what actually gets resolved: that
input is always just the remaining authority subsegments.

I hope this makes you more comfortable.



> I apologize if some of these had already been raised by Gabe or someone
> else.

[=Drummond] Not a problem. I think only one of them on the whole list was
raised by someone else.


> p.s. I should read the spec and type out comments right away, rather
> than marking with pen and then transcribing, because the latter takes
> too long.

[=Drummond] Yes! Anything to get the feedback in quickly - time to get this
DONE DONE DONE.

Thanks again for the super detail.

=Drummond