[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: Naming and Structure Issues
> 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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC