Subject: Comments on hierarchy draft

From: James M Snell <[email-masked]>
Date: Mon, 08 Jun 2009 11:34:17 -0700

Great to see a bunch of activity on the list... I'm finally starting to 
find time to catch up on what's been going on. The hierarchy draft looks 
good at first read but I had a few comments and concerns...

Forgive me if any of this has already been discussed, there have been a 
significant number of posts on the hierarchy draft and I simply have not 
yet had time to dig through them all.

Section 2.1

The cardinality model really isn't all that clear to me upon first read 
of this draft so please bear with me. The draft would seem to indicate 
that any given entry can have multiple parent entries. Does this mean 
that the entry can have multiple "up" links, each pointing to a 
different parent Atom entry document, or a single "up" link pointing to 
a single Atom feed document containing all of the parent entries?

Section 3.2 If the ae:inline element is supposed to allow arbitrary 
content then it is underspecified. For instance, the atom:content 
element contains a specific type attribute used to indicate whether the 
content is text, html, xhtml or some specific media type. If the 
media-type is binary based, atom:content requires that the contained 
data be Base64 encoded.  If the media-type is text based, atom:content 
requires that the characters be included as inline-text. If the 
media-type is xml based, atom:content requires that the xml be in-lined 
directly. I know the specification indicates that the optional type 
attribute of the enclosing atom:link element is intended to provide the 
necessary information, I think it would make far more sense for the 
ae:inline element to have it's own type attribute modeled after the 
atom:content type attribute. e.g. <ae:inline type="text">, <ae:inline 
type="application/atom+xml;type=entry">.

It would also make sense to explicitly spell out the processing model as 
is done in RFC 4287 for atom:content rather than just saying "process 
the value of ae:inline per the processing model for atom:content as 
specified in Section 4.1.3.3 of [RFC4287]".

Section 4

I'm not sure I'm comfortable with all the restrictions placed on the 
hierarchy model. "up" and "down" links should be able to point to 
individual Atom entry documents as well as feeds, for instance... it 
would make sense to be able to do something like...

 <entry>
   ...
   <link rel="down" type="application/atom+xml;type=entry" 
href="childentry1.xml" />
   <link rel="down" type="application/atom+xml;type=entry" 
href="childentry2.xml" />
   <link rel="down" type="application/atom+xml;type=entry" 
href="childentry3.xml" />
   ...
   <link rel="up" type="application/atom+xml;type=entry" 
href="parententry1.xml" />
   <link rel="up" type="application/atom+xml;type=entry" 
href="parententry2.xml" />
   <link rel="up" type="application/atom+xml;type=entry" 
href="parententry3.xml" />
   ...
 </entry>

This would imply also that each "down" and each "up" link point to 
distinct resources as opposed to alternate representations of the same 
resource... in other words, it expands the hierarchy model out to allow 
any single element to potentially have multiple child trees and multiple 
parent trees.

 <entry>
   ...
   <link rel="down" type="application/atom+xml;type=feed" 
href="childfeed1.xml" />
   <link rel="down" type="application/atom+xml;type=feed" 
href="childfeed2.xml" />
   ...
   <link rel="up" type="application/atom+xml;type=feed" 
href="parentfeed1.xml" />
   <link rel="up" type="application/atom+xml;type=feed" 
href="parentfeed2.xml" />
   ...
 </entry>

Yes, this increases the potential complexity of the hierarchy model, but 
restricting the model to only a single child tree and single parent tree 
feels like needless premature optimization.

I think the difference between "down" and "down-tree" and "up" and 
"up-tree" needs to be spelled out with more clarity.

Section 5.3: There is a bug in the example. The </ae:inline> and 
</atom:feed> closing tags have been transposed.

- James

---

From: "Nikunj R. Mehta" <[email-masked]>
Date: Mon, 8 Jun 2009 13:26:22 -0700

On Jun 8, 2009, at 11:34 AM, James M Snell wrote:

>
> Great to see a bunch of activity on the list... I'm finally starting  
> to find time to catch up on what's been going on. The hierarchy  
> draft looks good at first read but I had a few comments and  
> concerns...

Good to have you back in active participation on this list.

>
> Forgive me if any of this has already been discussed, there have  
> been a significant number of posts on the hierarchy draft and I  
> simply have not yet had time to dig through them all.
>
> Section 2.1
>
> The cardinality model really isn't all that clear to me upon first  
> read of this draft so please bear with me. The draft would seem to  
> indicate that any given entry can have multiple parent entries. Does  
> this mean that the entry can have multiple "up" links, each pointing  
> to a different parent Atom entry document, or a single "up" link  
> pointing to a single Atom feed document containing all of the parent  
> entries?

The cardinality model is defined in Section 4. Section 2 only  
introduces the meanings of certain relation type and a model for  
relating entries and feeds.

The I-D could have claridfied that a multi-parent relation is  
expressed through @type="application/atom+xml;type=feed" in  
combination with @rel=up.

> element contains a specific type attribute used to indicate whether  
> the content is text, html, xhtml or some specific media type. If the  
> data be Base64 encoded.  If the media-type is text based,  
> atom:content requires that the characters be included as inline- 
> text. If the media-type is xml based, atom:content requires that the  
> xml be in-lined directly. I know the specification indicates that  
> the optional type attribute of the enclosing atom:link element is  
> intended to provide the necessary information, I think it would make  
> far more sense for the ae:inline element to have it's own type  
> attribute modeled after the atom:content type attribute. e.g.  
> <ae:inline type="text">, <ae:inline type="application/atom 
> +xml;type=entry">.

Wouldn't this merely repeat information from the atom:link element?  
Why is it a better model? What happens if the atom:link @type and  
ae:inline @type differ from each other?

>
> It would also make sense to explicitly spell out the processing  
> model as is done in RFC 4287 for atom:content rather than just  
> saying "process the value of ae:inline per the processing model for  
> atom:content as specified in Section 4.1.3.3 of [RFC4287]".

Of course, the full processing model can be specified in the I-D, but  
we intentionally referred to the atom:content processing model as the  
archetype. If the best way to specify this behavior is to repeat the  
text in hierarchy I-D, that can be easily done.

> Section 4
<snip>

We are separately discussing this topic, so omitting here

> Section 5.3: There is a bug in the example. The </ae:inline> and </ 
> atom:feed> closing tags have been transposed.
>
Noted. Thanks!

---

From: James M Snell <[email-masked]>
Date: Mon, 08 Jun 2009 13:43:52 -0700

Nikunj R. Mehta wrote:
>> to find time to catch up on what's been going on. The hierarchy draft 
>> looks good at first read but I had a few comments and concerns...
>
Good to actually have the time to do so ;-)
>>
>> Forgive me if any of this has already been discussed, there have been 
>> a significant number of posts on the hierarchy draft and I simply 
>> have not yet had time to dig through them all.
>>
>> Section 2.1
>>
Ok...
>> atom:content requires that the characters be included as inline-text. 
>> If the media-type is xml based, atom:content requires that the xml be 
>> in-lined directly. I know the specification indicates that the 
>> optional type attribute of the enclosing atom:link element is 
>> <ae:inline type="text">, <ae:inline 
Yes and no. The sematics of the atom:link type attribute currently only 
apply to the media type of the linked resource and is intended only as a 
hint. It is possible that the linked resource is a completely different 
media type than that specified by the type attribute. Further, the type 
attribute does not utilize the special "text", "html" and "xhtml" values 
used in atom:content. Therefore, if the link uses type="text/html", 
should the content of the ae:inline element be processed using the rules 
for atom:content/@type="html" or atom:content/@type="text/html"? There 
are subtle yet important differences between the two. The differences 
become even more pronounced when dealing with type="xhtml" vs. 
type="application/xhtml+xml". I think that if you're going to point to 
the atom:content processing model as the rule for ae:inline, then you 
need ae:inline to have it's own type attribute and not rely on the link 
elements type attribute.  If the two are mismatched, then you treat it 
no differently than if the value of the atom:link/@type does not match 
the actual content type of the linked resource.
>>
>> It would also make sense to explicitly spell out the processing model 
>> as is done in RFC 4287 for atom:content rather than just saying 
>> "process the value of ae:inline per the processing model for 
In the past, I've used both approaches in drafts I've authored. The 
feedback I've received from others has consistently favored repeating 
the text in order to make the requirements absolutely clear.

- James

---

From: "Nikunj R. Mehta" <[email-masked]>
Date: Mon, 8 Jun 2009 13:47:22 -0700

All this makes sense. Will incorporate in a new atom-inline I-D  
soon. :-)

Nikunj
http://o-micron.blogspot.com

On Jun 8, 2009, at 1:43 PM, James M Snell wrote:

>>> Great to see a bunch of activity on the list... I'm finally  
>>> starting to find time to catch up on what's been going on. The  
>>> hierarchy draft looks good at first read but I had a few comments  
>>> and concerns...
>>
>>> indicate that any given entry can have multiple parent entries.  
>>> Does this mean that the entry can have multiple "up" links, each  
>>> pointing to a different parent Atom entry document, or a single  
>>> "up" link pointing to a single Atom feed document containing all  
>>> of the parent entries?
>>
>>> Section 3.2 If the ae:inline element is supposed to allow  
>>> arbitrary content then it is underspecified. For instance, the  
>>> atom:content element contains a specific type attribute used to  
>>> indicate whether the content is text, html, xhtml or some specific  
>>> media type. If the media-type is binary based, atom:content  
>>> requires that the contained data be Base64 encoded.  If the media- 
>>> type is text based, atom:content requires that the characters be  
>>> included as inline-text. If the media-type is xml based,  
>>> atom:content requires that the xml be in-lined directly. I know  
>>> the specification indicates that the optional type attribute of  
>>> the enclosing atom:link element is intended to provide the  
>>> necessary information, I think it would make far more sense for  
>>> the ae:inline element to have it's own type attribute modeled  
>>> after the atom:content type attribute. e.g. <ae:inline  
>>> type="text">, <ae:inline type="application/atom+xml;type=entry">.
>>
> Yes and no. The sematics of the atom:link type attribute currently  
> only apply to the media type of the linked resource and is intended  
> only as a hint. It is possible that the linked resource is a  
> completely different media type than that specified by the type  
> attribute. Further, the type attribute does not utilize the special  
> "text", "html" and "xhtml" values used in atom:content. Therefore,  
> if the link uses type="text/html", should the content of the  
> ae:inline element be processed using the rules for atom:content/ 
> @type="html" or atom:content/@type="text/html"? There are subtle yet  
> important differences between the two. The differences become even  
> more pronounced when dealing with type="xhtml" vs. type="application/ 
> xhtml+xml". I think that if you're going to point to the  
> atom:content processing model as the rule for ae:inline, then you  
> need ae:inline to have it's own type attribute and not rely on the  
> link elements type attribute.  If the two are mismatched, then you  
> treat it no differently than if the value of the atom:link/@type  
> does not match the actual content type of the linked resource.
>>>
>>> saying "process the value of ae:inline per the processing model  
>>> for atom:content as specified in Section 4.1.3.3 of [RFC4287]".
>>
>> Of course, the full processing model can be specified in the I-D,  
>> but we intentionally referred to the atom:content processing model  
>> as the archetype. If the best way to specify this behavior is to  
>> repeat the text in hierarchy I-D, that can be easily done.
>>
> feedback I've received from others has consistently favored  
> repeating the text in order to make the requirements absolutely clear.
>
> - James
>>>
>>> Section 4
>>>
>> <snip>
>>