Subject: Version attribute on atom:entry

From: Norman Walsh <[email-masked]>
Date: Sun, 11 Jul 2004 11:11:16 -0400

The spec says

  If used alone, atom:entry elements MUST have a "version" attribute
  whose content indicates the version of the Atom specification that
  the construct conforms to.

Is version allowed on atom:entry if the element is not used alone, if
it occurs in a feed?

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <[email-masked]> | Do not try to live forever. You will
http://nwalsh.com/            | not succeed.--George Bernard Shaw

---

From: Sam Ruby <[email-masked]>
Date: Sun, 11 Jul 2004 11:40:12 -0400

> Is version allowed on atom:entry if the element is not used alone, if

I would prefer that version attributes be limited to root elements of 
XML documents.

- Sam Ruby

---

From: Asbjørn Ulsberg <[email-masked]>
Date: Sun, 11 Jul 2004 18:09:03 +0200

> Is version allowed on atom:entry if the element is not used alone, if

I hope not! This should probably be noted in the specification, though, no  
matter what's allowed and not. I would say +1 to «The version attribute is  
only allowed on document level elements».

However, it is a valid use case that feeds may contain entries with  
different versions (synthetical feeds). In such situations, it would  
probably be best (although not easiest) to «downgrade» the feed to the  
lowest //entry/@version.

-- 
Asbjørn Ulsberg         -=|=-        [email-masked]
«He's a loathsome offensive brute, yet I can't look away»

---

From: Eric Scheid <[email-masked]>
Date: Mon, 12 Jul 2004 02:14:19 +1000

> I would prefer that version attributes be limited to root elements of

+1

that's the making of some nice spec text there too.

e.

---

From: Norman Walsh <[email-masked]>
Date: Sun, 11 Jul 2004 12:35:48 -0400

/ Mark Nottingham <[email-masked]> was heard to say:
| I'd phrase the question in a slightly different manner;
|
| Why do we have a version attribute at all? Why not rely upon the XML
| namespace to identify the version of the Atom document?

Because changing namespace names is about the most traumatic thing you
can do to a document. It breaks every single tool that is doing a
proper namespace-based comparison of element names. All the XSLT
stylesheets stop functioning, all the DOM tools that use the ...NS()
accessors stop working, etc.

A version attribute lets us make small changes and corrections to the
spec over time without breaking everything.

It strikes me that we need to specify the rules for processing Atom
documents that have a version that isn't recognized. We may also want
to add an atom:mustUnderstand attribute globally.

                                        Be seeing you,
                                          norm

---

From: Mark Nottingham <[email-masked]>
Date: Sun, 11 Jul 2004 09:23:54 -0700

I'd phrase the question in a slightly different manner;

Why do we have a version attribute at all? Why not rely upon the XML 
namespace to identify the version of the Atom document?

--
Mark Nottingham     http://www.mnot.net/

---

From: Sam Ruby <[email-masked]>
Date: Sun, 11 Jul 2004 13:04:29 -0400

> accessors stop working, etc.

<joke>
     Actually, with current tools, the most traumatic thing you can do
     to a document is to change the version number from "1.0" to "1.1"
     - in the XML prolog.
</joke>

> spec over time without breaking everything.

Sometimes.  ;-)

> to add an atom:mustUnderstand attribute globally.

It has been alleged that David Orchard is working on such a proposal.

- Sam Ruby

---

From: Graham <[email-masked]>
Date: Sun, 11 Jul 2004 13:12:17 -0400

> probably be best (although not easiest) to «downgrade» the feed to the 

Do synthetic feeds normally contain cut-and-pasted XML*? Wouldn't it be 
normal for incoming entries to be normalized on the way in (eg 
converted to an internal data format, or a specific version of Atom), 
such that they could all be output in the same format? I don't see this 
as an issue.

Graham

(* apart from the perennially sucky Feedster, which at least used to)

---

From: Asbjørn Ulsberg <[email-masked]>
Date: Sun, 11 Jul 2004 20:31:30 +0200

On Sun, 11 Jul 2004 13:12:17 -0400, Graham <[email-masked]> wrote:

> Do synthetic feeds normally contain cut-and-pasted XML*?

I have no idea, but you shouldn't bet much money on people _not_ doing  
things like this:

   <xsl:copy-of  
select="document('http://example.com/feed.atom')//atom:entry" />

> Wouldn't it be normal for incoming entries to be normalized on the way
> in (eg converted to an internal data format, or a specific version of
> Atom), such that they could all be output in the same format?

That should be recommended, yes.

> I don't see this as an issue.

Maybe it's not. I still think we need to be explicit about what elements  
@version can occur on, and in what situations.

---

From: Mark Nottingham <[email-masked]>
Date: Sun, 11 Jul 2004 17:43:44 -0700

Atom is less a document and more a container format for metadata; any 
changes to the semantics or syntax of atom:feed and atom:entry will be 
a traumatic change anyway. So, the version doesn't give us anything new 
for changes to the feed and entry themselves, as containers.

Another thing that the version might apply to is the semantics and 
syntax of individual pieces of metadata in the atom namespace; e.g., 
atom:title and atom:content. This doesn't seem like a good use of such 
an attribute, because the version attribute is coarse-grained; if we 
change the content model of "title," it doesn't seem like a good thing 
to change the entire Atom version. Additionally, versioning for 
"built-in" and extension metadata should happen in the same manner. So, 
version probably won't apply to the syntax and semantics of atom 
metadata; if we need to change existing metadata's syntax or semantics, 
we'll need to introduce a new, separate metadata (i.e., new namespace 
and/or new local name) and have a transition story between them.

There's one thing left that the version attribute can describe; the 
vocabulary of metadata used in a particular Atom feed; i.e., the feed 
MUST contain a title, MUST NOT contain more than one foo:blah in an 
entry, etc. This is something that the namespace is NOT good for 
describing, because the syntax and semantics of the individual elements 
have not changed at all. What has changed is the allowable and required 
combinations of those elements; this is what I think the version is 
good for.

However, I don't think "version" is a good name for it, because people 
tend to read the first two use cases into it. It would be much more 
appropriate to call it something like "profile", somewhat like HTML 
has.

In other words, I'm proposing that we refine our approach to versioning 
to three separate things:

1) Atom container constructs (e.g., atom:feed, atom:entry) are 
identified by their namespace URI; if we change the containment 
semantics, processing model, etc. we have to change that namespace.

2) Atom and extension metadata are likewise identified by their 
namespace; if their syntax or semantics change, they need a differnent 
Qname. This means that the metadata in our final release of Atom had 
better be well-understood and stable, because they'll be baked in (I 
think that's OK because it's true no matter what we do, and we're 
chartered to be conservative about the metadata we bake in).

3) The "package" of metadata used in a feed is described by a "profile" 
or "version" attribute, e.g.,
   <atom:feed profile="http://.../..."> ... </atom:feed>
   Atom would ship with a "default" profile that says there MUST be an 
atom:title, etc. -- just as the spec currently does -- and that 
extensions are allowed on top of that. More specialised vertical uses 
of Atom can likewise describe their own profiles; if they can get tool 
support for them, good on them.

Thoughts? There may be some interaction with atom:mustUnderstand here; 
I could see such a profile mechanism either replacing mU or being 
augmented by it. No matter what we do, I think we need to be a lot more 
precise about what a version attribute identifies; this is my 
straw-man, I'm more than open to other approaches, as long as they 
cover all of the bases.

---

From: Tim Bray <[email-masked]>
Date: Sun, 11 Jul 2004 22:10:47 -0700

On Jul 11, 2004, at 5:43 PM, Mark Nottingham wrote:

> In other words, I'm proposing that we refine our approach to 
> versioning to three separate things:

I'm massively unconvinced that this added complexity has noticeable 
benefit.  I want to see a single namespace that means "this is Atom", 
and I don't expect the semantics of atom:title to change for a long 
time so I don't think its name should change, and I do want a 
root-level "version" attribute.  Going down the path of solving the 
versioning problem in the general case reliably leads to convulsions 
and hairy palms.  Let's do the simplest thing that could possibly work: 
a fixed namespace and a root version attribute. -Tim

---

From: Mark Nottingham <[email-masked]>
Date: Sun, 11 Jul 2004 23:20:25 -0700

> and hairy palms.  Let's do the simplest thing that could possibly 
> work: a fixed namespace and a root version attribute. -Tim

Tim, you've completely failed to convince me that this is the right 
thing to do; you've effectively said "trust me, this'll work," 
justified the particular approach by saying "because I want it," and 
forstalled others by saying "you don't want to do that, it's hard."

Why do we need both a fixed namespace and a root version attribute?

When should the version attribute be changed?

How should the three scenarios I highlight be handled?

What, if any, is the interaction between versioning and profiling?

---

From: Dan Brickley <[email-masked]>
Date: Mon, 12 Jul 2004 04:25:13 -0400

* Tim Bray <[email-masked]> [2004-07-11 22:10-0700]

+1

Dan

---

From: Norman Walsh <[email-masked]>
Date: Mon, 12 Jul 2004 08:13:59 -0400

/ Mark Nottingham <[email-masked]> was heard to say:
| 1) Atom container constructs (e.g., atom:feed, atom:entry) are
| identified by their namespace URI; if we change the containment
| semantics, processing model, etc. we have to change that namespace.
|
| 2) Atom and extension metadata are likewise identified by their
| namespace; if their syntax or semantics change, they need a differnent
| Qname. This means that the metadata in our final release of Atom had
| better be well-understood and stable, because they'll be baked in (I
| think that's OK because it's true no matter what we do, and we're
| chartered to be conservative about the metadata we bake in).

Extension metadata is already going to be in another namespace, so
that's not really an issue. If I understand you, what you're proposing
boils down to a namespace name for the atom:feed/atom:entry elements
and a different namespace name for the atommeta:title, atommeta:author,
etc. elements.

I think that's going to make Atom significantly harder for new users
that are trying to write, understand, or process feeds. I think
keeping everything in a single namespace so that a vanilla feed can
just use the default namespace for all elements is a feature we should
not lose without compelling motivation.

| 3) The "package" of metadata used in a feed is described by a
| "profile" or "version" attribute, e.g.,
|    <atom:feed profile="http://.../..."> ... </atom:feed>
|    Atom would ship with a "default" profile that says there MUST be an
| atom:title, etc. -- just as the spec currently does -- and that
| extensions are allowed on top of that. More specialised vertical uses
| of Atom can likewise describe their own profiles; if they can get tool
| support for them, good on them.

Calling the "version" attribute "profile" and allowing others to
define their own profiles is an interesting idea. I could probably
live with that.

But I don't think you've covered the use case that I think is most important.
Suppose that a year from now, we all have Atom 1.0 under our belts and we've
been using it for a while. Discussion has continued after the 1.0 release and
we're pretty sure we have the categorization problem solved (just to pick an
example, choose anything that isn't scheduled for the 1.0 release).

Now we want to publish Atom 1.1 with a new, optional element, atom:category.

We could:

 1. Add this in a new namespace
 2. Add this in a new namespace and change *all* the elements to the new namespace
 3. Add this in the old namespace and change the version/profile attribute.

Choice 1 is "right" by some metrics, but won't feel like we're integrating
atom:category into Atom proper.

Choice 2 is "right" by some metrics, but it really is a heck of a cliff that
everyone has to jump off. It will be *years* before everyone is ready to change
all their feeds and tools.

Choice 3 is "right" by some metrics, and if its combined with a
reasonable versioning policy in 1.0 offers the maximum bang for the
minumum buck, IMHO.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <[email-masked]> | Wandering in a vast forest at night, I
http://nwalsh.com/            | have only a faint light to guide me. A
                              | stranger appears and says to me: "My
                              | friend, you should blow out your candle
                              | in order to find your way more
                              | clearly." This man is a theologian.--
                              | Diderot

---

From: Mark Nottingham <[email-masked]>
Date: Mon, 12 Jul 2004 12:12:17 -0700

> and a different namespace name for the atommeta:title, atommeta:author,

No; I'm proposing that whatever ships with Atom -- i.e., the container 
and any "core" metadata -- be associated with a single namespace. 
However, if we have to change the syntax or semantics of any of that 
core metadata, we'll have to change its name (either the namespace URI 
or the localname).

> I think

Totally agreed.

> reasonable versioning policy in 1.0 offers the maximum bang for the

This explains what I mean by 'profiling' very well -- thanks! :)

There are actually two issues at hand; what namespace to add the new 
metadata in, and how to identify if they're required parts of the 
profile.

I think that the WG can add new metadata into the existing Atom 
namespace, as long as we don't change existing semantics. I.e., we can 
add atom:Category later without revving the version/profile attribute.

The only reason we'd want to rev the version/profile attribute is if we 
change the requirements about the presence of the new metadata 
(atom:Category) in the feed; i.e., if we say "an entry MUST have an 
atom:Category element", a new version/profile id is required, so that 
software can recognise the difference.

---

From: James M Snell <[email-masked]>
Date: Mon, 12 Jul 2004 14:07:13 -0600

Comments inline...

- James M Snell
  [email-masked]
  http://www.ibm.com
  (877) 511-5082 / Office
  930-1979 / Tie Line

> core metadata, we'll have to change its name (either the namespace URI 

+1 ... any change to syntax or semantics should require a version or 
namespace change.  I would argue, however, that the addition of even 
optional elements constitutes a syntax/semantics change.

> > Suppose that a year from now, we all have Atom 1.0 under our belts and 

> > we've

While I'm ok with this, I'd have to argue that the bar should be set 
rather high for the working group to consider such changes after Atom 1.0 
is out the door.  Even the addition of new optional elements within the 
same namespace could cause problems for various implementations. 

There is one other possibility.  It would be possible for this WG to 
define an "extension namespace" within which non-core new optional 
elements could be added.  e.g. <atomex:Category>.  The bar for adding 
elements to this extension namespace would be set much lower than the core 
atom namespace. The semantics, of course, would be that all elements in 
the atomex namespace would be always optional.  Once (and if) elements in 
the atomex namespace became popular/essential enough, this work group 
could decide on whether or not those elements should be moved to the core 
namespace, causing a rev in the version attribute value.

Each element added to the atomex namespace would need to be described in 
it's own RFC (meaning people would actually have to go through some work 
to define them rather than inventing them willy-nilly). 

It is, at least, an idea that *may* be worth considering.

---

From: Mark Nottingham <[email-masked]>
Date: Mon, 12 Jul 2004 13:13:37 -0700

On Jul 12, 2004, at 1:07 PM, James M Snell wrote:
> rather high for the working group to consider such changes after Atom 
> 1.0 is out the door.  Even the addition of new optional elements 
> within the same namespace could cause problems for various 
> implementations.  

How so?

> elements to this extension namespace would be set much lower than the 
> core atom namespace. The semantics, of course, would be that all 
> elements in the atomex namespace would be always optional.  Once (and 
> if) elements in the atomex namespace became popular/essential enough, 
> this work group could decide on whether or not those elements should 
> be moved to the core namespace, causing a rev in the version attribute 
> value.
>
> Each element added to the atomex namespace would need to be described 
> in it's own RFC (meaning people would actually have to go through some 
> work to define them rather than inventing them willy-nilly).

Hmm, this is interesting. I take it the atomex namespace would be only 
used for WG extensions, rather than anybody who wants to?

I imagine we'll end up doing this in any case, because we'll want to 
use in-development namespaces until any such extensions are final.

Cheers,

---

From: James M Snell <[email-masked]>
Date: Mon, 12 Jul 2004 14:47:45 -0600

- James M Snell
  [email-masked]
  http://www.ibm.com
  (877) 511-5082 / Office
  930-1979 / Tie Line

> > within the same namespace could cause problems for various 

More of an implementation issue really (as opposed to something that 
should be codified in the spec), but given an application that is 
programmed to expect certain known optional elements, the addition of a 
new unknown optional element that the application does not know how to 
handle could cause problems.  Look at the parallels in things like DNS as 
an example, where while the DNS spec supports new resource record types, 
for years the introduction of new types, regardless of their optional 
nature, was not supported by many implementations.  I am not saying that 
the WG should care if applications are written in such a brittle fashion, 
only that it should be recognized that such issues can occur.  It is 
possible to mitigate such issues by defining concise behavior/semantics 
and setting the bar high for changes to the core namespace (or extension 
namespaces).  For example, if we expect that new elements could be added 
at any time to the core namespace without much effort, then that should be 
captured in the spec so that implementors can plan their implementations 
accordingly.

> used for WG extensions, rather than anybody who wants to?

Correct.  If someone wishes to add a new element to the atomex namespace, 
they would be required to submit an RFC describing that element to this 
WG. 

> use in-development namespaces until any such extensions are final.

Correct, the use of the extension namespace raises the bar for things to 
be added/changed in the core namespace.

---

From: Mark Nottingham <[email-masked]>
Date: Mon, 12 Jul 2004 17:50:36 -0700

On Jul 12, 2004, at 1:47 PM, James M Snell wrote:
> programmed to expect certain known optional elements, the addition of 
> a new unknown optional element that the application does not know how 
> to handle could cause problems.  Look at the parallels in things like 
> DNS as an example, where while the DNS spec supports new resource 
> record types, for years the introduction of new types, regardless of 
> their optional nature, was not supported by many implementations.  I 
> am not saying that the WG should care if applications are written in 
> such a brittle fashion, only that it should be recognized that such 
> issues can occur.  It is possible to mitigate such issues by defining 
> concise behavior/semantics and setting the bar high for changes to the 
> core namespace (or extension namespaces).  For example, if we expect 
> that new elements could be added at any time to the core namespace 
> without much effort, then that should be captured in the spec so that 
> implementors can plan their implementations accordingly.

No. One of the big reasons I'm involved in Atom is to allow new 
extensions to be introduced without this kind of barrier; without that, 
Atom is frankly not very interesting at all.

Much better to make an explicit "must ignore" rule (as DavidO has 
documented) in the spec, so implementations know what the expectations 
upon them are in these situations.

---

From: James M Snell <[email-masked]>
Date: Mon, 12 Jul 2004 22:14:21 -0600

- James M Snell
  [email-masked]
  http://www.ibm.com
  (877) 511-5082 / Office
  930-1979 / Tie Line

> upon them are in these situations.

By all means, create all the extensions you want... *in their own 
namespace or in an extension namespace*.  I'm all for that and defining a 
"MustUnderstand" attribute for these elements.  What I draw the line at, 
however, is changes being made willy-nilly within the core namespace.  The 
core should only rarely ever be changed.

---

From: Mark Nottingham <[email-masked]>
Date: Mon, 12 Jul 2004 21:35:52 -0700

On Jul 12, 2004, at 9:14 PM, James M Snell wrote:
> namespace or in an extension namespace*.  I'm all for that and 
> defining a "MustUnderstand" attribute for these elements.  What I draw 
> the line at, however, is changes being made willy-nilly within the 
> core namespace.  The core should only rarely ever be changed.

Totally agreed; the WG owns the Atom NS, and is the only entity that 
can change it or introduce new things into it.

I had taken this for granted; apologies if it wasn't explicit. The 
question I've been revolving around is what mechanisms/stubs we give to 
people who are designing their own extensions (e.g., mustUnderstand) 
and usage scenarios (e.g., profiling).

Cheers,