Overall I think the proposed versioning text is really good. Scott, if
you agree with the nature of the comments below but don't want to
attempt a rewrite along these lines, let me know and I'll try to make
time to do it myself...
Small comment: I think we want to refer to "the SAML specification set"
and not just "the SAML specification", since it's made up of several
discrete documents. This is the wording we use on the website.
Big comment: Given that the assertion and protocol are documented in the
same spec, and given that we've said we'll give all the specifications
in a set the same version, I think it's confusing to have both a SAML
Assertion Version section and a SAML Protocol Version section. I see
these version numbers in the instances as *references* to the
specification version (which you do ultimately make clear in the text of
both these sections). So I think it would be more accurate to say in
the intro that there are *two* (not several) independent versioning
schemes used in SAML: specification (referenced in assertion/message
instances and the schema modules) and namespace (referenced in
targetNamespace in the schema modules). I would prefer a reorganization
of the writeup to reflect this notion; there are a few different ways to
do it.
Finally, it seems a bit disingenuous to say that the appearance of a
version number in the namespace means nothing. The third paragraph in
that section pretty much backs off of the strong wording in the second
paragraph anyway. I would be willing to sign up for namespace versions
that are not orthogonal but, rather, that can be expected in normal
circumstances to contain an X.0 designation during a spec set's journey
from X.0 to X.n, and then change to Y.0 whenever a major revision
happens. Or, if they're really orthogonal, then let's commit to
removing version numbers from them in the future.
Regarding your other notes below, I'm happy to add entries to the
glossary once we formally agree on the new terminology (or did we
already?). I get backwards compatibility, but I always have trouble
making intuitive sense out of forward compatibility...
And it's a great idea to add something about profile versions, once we
know what we want to say. But maybe, since we've pushed off a
refactoring of Bindings and Profiles until V2.0, we can do "lazy
writing" of this part. (We will probably then have a total of three
versioning types: spec, namespace, and individual profile.)
Eve
Scott Cantor wrote:
> I took an AI on the last call to propose new text for section 4 of core to discuss versioning in more detail.
>
> I synthesized some of the text from my earlier draft submission, including some of the terminology and breakdown of the different
> version types, but tried to keep it brief. Some of it isn't all that normative, but I think it's useful for implementers, just like
> the stuff in section 1 is.
>
> Couple thoughts:
>
> It might need glossary support or some means of defining the terms I took from my draft like forward/backward compatibility. I
> didn't copy all that explication, but OTOH, I think it's clearer than the vague use of compatibility that's in 1.0.
>
> It could incorporate some of the parallel discussion on profile versioning that I think Jeff was looking at. I didn't really address
> that.
>
> -- Scott
--
Eve Maler +1 781 442 3190
Sun Microsystems cell +1 781 354 9441
Web Technologies and Standards eve.maler @ sun.com
