Re: [security-services] AI: proposed text for core Section 4

["Eve L. Maler" <eve.maler@sun.com>]

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