Subject: Review of Section 6

From: David Powell <[email-masked]>
Date: Thu, 9 Jun 2005 17:22:15 +0100

Apologies for the rubbish timing, but I've been reviewing section 6, and found a
number of problems.

Firstly, there are some mismatches between the RelaxNG grammar and the
specification text.  I know that the RelaxNG grammar isn't normative; but this
doesn't mean that it can be contradictory:

a) Section 6.4 omits atom:source as a valid location for Metadata Extensions,
but it is allowed by the RelaxNG in 4.2.11.  I believe that the RelaxNG
reflects our intent to allow extensions to be preserved in atom:source.

b) Section 6.4.1 and Section 6.4.2 don't place any restrictions on what elements
may be used as Metadata Extensions, but the RelaxNG grammar explicitly excludes
elements in the Atom namespace.  The Atom namespace should be reserved for
future forwards-compatable revisions of Atom.

I actually raised these issues before the new draft was published but I didn't
receive any comments.  I am surprised that nothing has been fixed, these two
issues are simply bugs.

c) It isn't the intent of Section 6.4.1/6.4.2 that namespace declarations should
be considered among the "attributes and child elements" that determine whether
an extension is "Simple" or "Structured".  This should be made explicit, many
implementors don't have control over their placement (luckily).

I also have some problems with the structure of the whole section:

Section 6.3 describes "unknown foreign markup" as markup not defined by the
specification and describes how it should be processed; but Section 6.4
specifies the behaviour of another type of markup.  Is Section 6.4 markup
described by the specification, and therefore distinct from "unknown foreign
markup"?  If so why is it described after describing the catch-all - this
non-linearity is very confusing.  Or is it a subset?  I think that the
definition is rather ambiguous.  I find the distinction between "metadata
elements", "foreign markup", and "unknown foreign markup" to be extremely
confusing.  I wouldn't be surprised if a Venn Diagram of them was totally
different to my interpretation.

It would be better if this section was re-ordered, so that the catch-all
definition of non-Metadata Element extensions was placed after the definition
of Metadata Elements.

The two subsections of Section 6.4 are intended to describe the two subclasses
of Metadata Element.  It would make more sense if the terminology for these
subclasses was uniform.  Why not call them "Metadata Extensions", "Simple
Metadata Extensions", and "Structured Metadata Extensions"; rather than
"Metadata Elements", "Simple Extension Elements", and "Structured Extension
Elements".

I think it is insufficient to describe these subclasses purely in terms of their
syntactic characteristics, rather than in terms of their intent.  It would be
beneficial for publishers if a paragraph was introduced into Section 6.4 to
describe why a publisher/extension author would favor one of these classes. 
The intent is that a given extension would belong to a fixed class, and the
Simple class is designed to offer the advantages of easy generic processing by
simpler implementations (eg storage by servers in custom attributes), amongst
other things.

Finally, on a more fundamental level, I am worried by the class of markup that
is an extension, but isn't a "Metadata Element".  This, I think, is limited to
children of atom:link, and additional attributes on atom elements.

If this markup was reserved for future revisions of Atom, that would be fine,
but it doesn't appear to be the case - I can't really tell?

Acording to the charter Atom should have a seperate model and syntax.  Metadata
Elements were proposed to ensure that extensions could be part of the model, so
that they could be represented in RDBMS/OO/RDF/WebDAV implementations as custom
properties.

This other class of extension, if it is intended to be one, can only be
represented as part of the Atom's XML syntax.  To provide support for
extensions that use this class of markup would require changes to every stage
of the publishing and processing process.

A better alternative would be if these attribute extensions were just
treated as an alternative way of expressing Simple Metadata Extensions - at
least then some generic support for them could be implemented.  Either that or
they should be reserved for use by future Atom specifications.

There are other areas that should be clarified too.  I assume that "Atom
markup vocabulary" is intended to be current and future elements in the Atom
namespace, and un-namespaced attribtues on Atom elements, but this is just my
guess, it isn't defined in the specification.

--
Dave

---

From: Tim Bray <[email-masked]>
Date: Thu, 09 Jun 2005 09:51:57 -0700

> doesn't mean that it can be contradictory:

I've asked Paul, and in fact we can fix typos and outright bugs later  
on in the process.  If you're right about the Relax mismatch (Rob?   
Norm?) then let's fix that.

On the other hand, a general re-organization of section 6 is right  
out; it is our finding that the format-09 draft (modulo errors)  
reflects the rough consensus of the WG.  If you disagree, the IETF  
provides appeal procedures.

> reflects our intent to allow extensions to be preserved in  

Sounds right to me.

> future forwards-compatable revisions of Atom.

I find this surprising too, will check further.  -Tim

---

From: David Powell <[email-masked]>
Date: Fri, 10 Jun 2005 00:31:42 +0100

> provides appeal procedures.

Last week I thought about how to rework Section 6. Although some of
this reworking might be not acceptable now, I'll post it anyway. It
might be that there are some actual ambiguities in the current draft;
if so, then I guess that ambiguities might be considered to be "bugs",
that still need fixing.

It would be good if people could give section 6 a check to see that it
makes sense, and that the text matched their impression.

This rework itself was done fairly quickly, so it might have made some
things worse, but the major changes are:

1) Namespace attributes are explicitly excluded from the attributes
that determine the class of a Metadata Element.

2) Added namespace rules to section 6.4.1 and 6.4.2.

3) Added atom:source as a valid location for Metadata Elements.

4) Added paragraph about the intent of Metadata Elements.

5) Renamed 6.4 terms to "Metadata Extensions", "Simple Metadata
Extensions", and "Structured Metadata Extensions" for uniformity.

6) Added explicit definition of the term "Atom Vocabulary".

7) Moved sub-sections around so that the section can be read more
linearly.

I won't be available for the next week to discuss this btw.

== Dave's version of Section 6 ==

6.  Extending Atom

6.1  Extensions To the Atom Vocabulary

   Future versions of Atom could add new elements to the Atom
   namespace, and new attributes, in the default namespace, to
   existing Atom-namespaced elements.  Software written to conform to
   this version of the specification will not be able to process such
   markup correctly and, in fact, will not be able to distinguish it
   from markup error.  For the purposes of this discussion,
   unrecognized markup from the Atom vocabulary will be considered
   "foreign markup".

6.2  Extensions From Non-Atom Vocabularies

   This specification describes Atom's XML markup vocabulary.  Markup
   from other vocabularies ("foreign markup") can be used in an Atom
   document.  Note that the atom:content element is designed to support
   the inclusion of arbitrary foreign markup.

6.2.1  Metadata Extensions

   Child elements of atom:entry, atom:feed, atom:source, and Person
   constructs are considered Metadata Extensions, and are described
   below.  Child elements of Person constructs are considered to apply
   to the construct.

   Atom defines two classes of Metadata Extensions.  Simple Metadata
   Extensions are designed to be easier for simpler implementations to
   support.  To prevent sporadic support of an extension by
   implementations that only support Simple Metadata Extensions,
   extension authors SHOULD ensure that an extension is either a
   Simple Metadata Extension, or a Structured Metadata Extension for
   all of the extension's possible values.

6.2.1.1  Simple Metadata Extensions

   A Simple Metadata Extension element MUST NOT have any child
   elements or attributes, other than namespace declarations.  It MUST
   be namespaced-qualified, and MUST be defined outside of the Atom
   namespace.  The element MAY contain character data, or be empty.
   Simple Metadata Extensions are not Language-Sensitive.

   simpleExtensionElement =
      element * - atom:* {
         text
      }

   The element can be interpreted as a simple property (or name/value
   pair) of the parent element that encloses it.  The pair consisting of
   the namespace-URI of the element and the local name of the element
   can be interpreted as the name of the property.  The character data
   content of the element can be interpreted as the value of the
   property.  If the element is empty, then the property value can be
   interpreted as an empty string.

6.2.1.1  Structured Metadata Extensions

   The root element of a Structured Metadata Extension MUST have at
   least child element or attribute, other than namespace
   declarations.  It MUST be namespace-qualified, and MUST be defined
   outside of the Atom namespace.  It MAY have attributes, it MAY
   contain well-formed XML content (including character data), or it
   MAY be empty.  Structured Metadata Extensions are
   Language-Sensitive.

   structuredExtensionElement =
      element * - atom:* {
         (attribute * { text }+,
            (text|anyElement)*)
       | (attribute * { text }*,
          (text?, anyElement+, (text|anyElement)*))
      }

   The structure of a Structured Metadata Extension, including the order
   of its child elements, could be significant.

   This specification does not provide an interpretation of a Structured
   Metadata Extension.  The syntax of the XML contained in the element,
   and an interpretation of how the element relates to its containing
   element is defined by the specification of the Atom extension.

6.2.2  Unknown Foreign Markup

   Atom allows foreign markup anywhere in an Atom document, except
   where it is explicitly forbidden.  Markup in other locations, such
   as namespaced attributes, and child elements of atom-namespaced
   elements (for those elements that this specification does not
   already define a meaning for), are termed Unknown Foreign Markup.
   The role of Unknown Foreign Markup is undefined by this
   specification.

6.3  Processing Foreign Markup

   Atom Processors which encounter foreign markup in a location that is
   legal according to this specification MUST NOT stop processing or
   signal an error.  It might be the case that the Atom Processor is
   able to process the foreign markup correctly and does so.  Otherwise,
   such markup is termed "unknown foreign markup".

   When unknown foreign markup is encountered as a child of atom:entry,
   atom:feed, atom:source or a Person construct, Atom Processors MAY bypass
   the markup and any textual content and MUST NOT change their behavior
   as a result of the markup's presence.

   When unknown foreign markup is encountered in a Text Contruct or
   atom:content element, software SHOULD ignore the markup and process
   any text content of foreign elements as though the surrounding markup
   were not present.

-- 
Dave

---

From: Paul Hoffman <[email-masked]>
Date: Thu, 9 Jun 2005 17:03:41 -0700

At 12:31 AM +0100 6/10/05, David Powell wrote:
>Last week I thought about how to rework Section 6.

Wearing my co-chair hat: we have no opportunity to rework any section 
of the document unless the IESG asks us to. If we find technical 
errors, we will of course fix them.

If you think that Tim and I have made administrative errors in 
preventing this reorganization, you can appeal that decision.

>Although some of
>this reworking might be not acceptable now,

*All* reworking is not acceptable now.

>  I'll post it anyway. It

There is a large difference between suggesting a bunch of reworking 
and pointing out specific ambiguities. Please do the latter if you 
find them.

--Paul Hoffman, Director
--Internet Mail Consortium

---

From: David Powell <[email-masked]>
Date: Fri, 10 Jun 2005 06:30:27 +0100

> [...]

> and pointing out specific ambiguities. Please do the latter if you 

Yes, I understand. In my previous mail I suggested some areas which
might be ambiguous, such as the distinctions between the various types
of extension markup; and whether we need to say that namespace
attributes don't count as attributes for the purposes of 6.4.1/2.
Whether or not this is serious is up for debate...

I posted this purely as a talking point, so that anyone unsure about
section 6, can take a look, see if it matches their understanding of
section 6; and if not, to see whether this is the draft's fault, their
fault, or my fault.

The reason I posted it at all, is because I will be on holiday for the
next week, so I won't have any more input until after then, which will
probably be a bit late.

-- 
Dave

---

From: Norman Walsh <[email-masked]>
Date: Fri, 17 Jun 2005 14:53:38 -0400

/ David Powell <[email-masked]> was heard to say:
| a) Section 6.4 omits atom:source as a valid location for Metadata Extensions,
| but it is allowed by the RelaxNG in 4.2.11.  I believe that the RelaxNG
| reflects our intent to allow extensions to be preserved in atom:source.

That seems reasonable to me. I'd be content if we decided this was a
spec bug and agreed to add 'atom:source' to the lext of Metadata
Elements in Section 6.4.

| b) Section 6.4.1 and Section 6.4.2 don't place any restrictions on what elements
| may be used as Metadata Extensions, but the RelaxNG grammar explicitly excludes
| elements in the Atom namespace.  The Atom namespace should be reserved for
| future forwards-compatable revisions of Atom.

Given that our spec defines what the atom: elments mean and where they
can appear, it would seem bizarre to me to say that in Metadata
Extensions, any atom: element can be used for any purpose.

I conclude that the RELAX NG grammar reflects the groups intent in
these areas, but I'll change it if consensus proves me wrong. :-)

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <[email-masked]> | The worst enemy of life, freedom and
http://nwalsh.com/            | the common decencies is total anarchy;
                              | their second worst enemy is total
                              | efficiency.--Aldous Huxley