Naming and Structure Issues

["Hallam-Baker, Phillip" <pbaker@verisign.com>]

> All,
> 
> 	One of the issues that came up on the list is consistency in naming.
> This does not affect the semantics of the specification but can affect
> readability.
> 
> 	Given the groups preponsity for raising such issues I would much
> rather deal with them once and once only NOW rather than we get almost to
> completion and someone tries to open the issue and we spend a month
> arguing the point. There is also the issue of auxilliary docs such as the
> examples and discussion which need to be kept in sync.
> 
> 	I propose that we adopt a set of rules for naming of elements and
> structuring of the schema as follows, the first three are pretty much
> slam-dunk innocuous consistence issues, the others could have XML
> implications, note however that 6 and 7 represent current practice and 5
> represents a current design goal.
> 
> [Note I am putting these out for discussion before I edit the doc because
> I want to do that once.]
> 
> 1) Construction Of Names
> 	All names are implicitly scoped under the specification, no element
> contains the specification as part of its name. Rationale - the elements
> will be prefixed in most applications <samp:SAMLFooBar> is redundant
> 
> 	All names are composed of words spelled out in full without
> abreviations with the first letter of each word capitalized including the
> first.
> 
> 2) Hierarchy
> 	The interpretation of a name should not rely on implicit knowledge
> of the XML hierarchy. Rather a name should inform the reader of the
> hierarchy. So an <AttributeAssertion> is an extension of an <Assertion>.
> The head element name is written after the adjective describing the
> element that extends it.
> 
> 	Where an element contains sub elements the sub elements only take
> the name of the parent if ambiguity might otherwise arise
> 
> 3) Types, Abstract types etc.
> 	A type name ends with the word Type, the name of an abstract type
> ends with the words AbstractType
> Where an element is declared of a particular type the default name of the
> element is that of the type with the word Type omitted.
> 
> 4) Substitution Groups (controvertial)
> 	In each case that an abstract type is declared that is not an
> extension of another type, an element of that type is declared for use as
> the head of a substitution group. For each concrete type that is an
> extension of the abstract type a concrete element is declared that states
> it to be a member of the head substitution group.
> Rationale: Substitution groups to be defined to allow the use of the base
> SAML specification without the need to use the xsiType attribute.
> 	Note: Applications could still use the xsi:Type mechanism to ensure
> that their own extensions were backwards compatible and even if the main
> schema does not use substitution groups an extension schema may still
> choose to do so, I will add a note to the back of the document.
> 
> 5) Toplevel declarations
> 	Elements of types declared in the schema should be declared at the
> top level unless they are only used at one point in the schema AND are not
> likely to require extension because the elements they contain are intended
> to be extended.
> Rationale: Encourage future extension schemas to reuse and extend existing
> elements rather than forcing them to re-invent the wheel.
> 
> 6) Final elements
> 	No elements to be declared final
> Rationale: This is what we do now. The debate on which to declare final
> would be ugly and futile.
> 
7) Anonymous Types
		All types are declared explicitly. This means that all types
can be extended in other schemas.
	Rationale: This is what we do now

8) Add in any other rule we currently obey but have not stated.

> Consequences
> 	The following core-12 element names would be affected:
> 
> [3] 		Answer 							-->
> Decision
> [3] 		AssertionType 					-->
> AssertionAbstractType
> [1,3] 	SAMLAbstractRequestType		-->
> RequestAbstractType
> [3]		SubjectAssertionType			-->
> SubjectAssertionAbstractType
> [1]		SAMLRequest					-->
> Request
> [1]		SAMLRequestType				-->
> RequestType
> [1]		SAMLQueryType				-->
> QueryType
> [3]		SubjectQueryType				-->
> SubjectQueryAbstractType
> [1,3]	SAMLAbstractResponseType	-->		ResponseAbstractType
> [1]		SAMLResponse					-->
> Response
> [1]		SAMLResponseType			-->
> ResponseType
> 
> 
> [4] New concrete elements to be declared
> 
> [in assertions]
> AuthenticationAssertion
> AuthorizationDecisionAssertion
> AttributeAssertion
> 
> ]in protocol]
> AuthenticationQuery
> AttributeQuery
> AuthorizationQuery
> 
> 		Phill
> 
> 
> Phillip Hallam-Baker FBCS C.Eng.
> Principal Scientist
> VeriSign Inc.
> pbaker@verisign.com
> 781 245 6996 x227 <<Phillip Hallam-Baker (E-mail).vcf>>

Phillip Hallam-Baker (E-mail).vcf