Update: [xacml] XACML and OASIS document and naming guidelines

New version already: it fixes "so long as your formats are weird" :-)

Anne

Anne Anderson - Sun Microsystems wrote On 09/28/06 12:52,:
> Colleagues,
> 
> Prompted by Erik's question about formatting, naming, etc. of the 
> delegation work, I went through the naming guidelines document and the 
> specification format guidelines and tried to pull out what is relevant 
> to our specifications with XACML examples.  Since the guidelines provide 
> little guidance on specification titles or file name syntax, I have 
> proposed a syntax for consistency.
> 
> Please let me know if there are other topics we need to agree on, if you 
> disagree with any of the proposals, or if you have other comments on this.
> 
> Regards,
> Anne
> 
> ------------------------------------------------------------------------
> 
> 
>   XACML and OASIS Guidelines
> 
> This is a review of OASIS Document and Naming Guidelines for 
> applicability to XACML specifications, schemas, and names. It is based 
> on the following references:
> 
>     * http://docs.oasis-open.org/specGuidelines/namingGuidelines/resourceNaming.html
> 
>     * http://docs.oasis-open.org/templates/ 
> 
> Reviewer:  Anne Anderson 
> Version:   1.2
> Updated:   06/09/28 (yy/mm/dd)
> 
> 
>   Contents
> 
>     * Introduction and General Notes <#Intro>
>     * Specification Format <#Docs>
>     * Specification Titles <#SpecTitles>
>     * File Names, and "Document Identifier" <#Files>
>     * "Persistent location" <#Location>
>     * URI's <#URIs> 
> 
> 
>   Introduction and General Notes
> 
> These guidelines apply only to documents to be stored under 
> http://docs.oasis-open.org, so do not apply to our Working Drafts, 
> although it will be easier to convert Working Drafts to the required 
> format if they conform.
> 
> No names of schema elements, etc. are affected.
> 
> No underscores are allowed in names unless absolutely necessary, but 
> camel case is allowed if you want.
> 
> 
>   Specification Format
> 
> OASIS provides specification templates at 
> http://docs.oasis-open.org/templates/. The detailed instructions are 
> only in Word and PDF formats under the "Microsoft Word Specification 
> Template" section of the page.
> 
> Changes from older versions:
> 
>     * There are more fields to be filled in on the title page, so be
>       sure to copy the new format for that
>     * The "Notices" page follows the title page, rather than being at
>       the end, and has revised wording, so be sure to copy that.
>     * Section 1 of a spec has a specified format, and should be copied
>       from a template. It has Introduction, Terminology, Normative
>       References, and Non-normative References.
>     * An Appendix contains Acknowledgments, such as TC members that
>       participated in development of the specification. Use their format.
>     * An optional Appendix contains Revision History. This Appendix is
>       not included in OASIS standard versions of a specification.
>     * An optional Appendix "should" contain Non-Normative text, but
>       small blocks of non-normative text, if clearly marked, may be
>       embedded in the main body of the document.
>     * You aren't going to be ruled out-of-compliance for minor style
>       differences. The User Guide includes recommended styles for Code
>       examples, Attribute Names, DataType names, Element names, etc.
>       that are useful. If you are creating a brand new document, use
>       these, but if you are updating an earlier draft, use your own
>       discretion so long as your formats are weird. 
> 
> 
>   Specification Titles
> 
> There is no guidance on specification titles other than
> 
>   [Specification Title vX.X]
> 
> I propose:
> 
>     * Core:
>       Example: *eXtensible Access Control Markup Language (XACML) v2.0*
>     * Profile:
>       <Target> profile of XACML <XACML version> v<profile version>
>       Example: *SAML 2.0 profile of XACML 2.0 v2* 
> 
> 
>   File Names, and "Document Identifier"
> 
> Similarly there is not much guidance about document titles or file 
> names. The following fit the guidelines, and will let our documents 
> follow a consistent naming pattern.
> 
> General rough syntax for file names:
> 
>   xacml-<xacml version>-<topic>-<doctype>-<stage>-<draft version>-<language>.<format>
> 
> The "Document Identifier" is everything up through <draft version>.
> 
> where
> 
>     * <topic> is something like "core" or "profile-ws-policy" or
>       "profile-saml-2.0" - enough to identify the topic of the various
>       versions and document types involved
>     * <doctype> is spec or schema. Schema may be further identified as
>       to its sub-topic: schema-policy, schema-context - and its version
>       (v2, v3 - assume otherwise it is v1)
>     * <stage> is wd, cd, os
>     * <draft version> is in sequential order (1,2,...10,11,9999999 :-)
>     * <language> is usually "en" (English)
>     * <format> is pdf, odt, html, etc. - documents must be available in
>       at least one editable format (.odt, .doc), and may also be
>       available in others like .pdf 
> 
> 
>       Examples:
> 
>   Core spec:      *xacml-3.0-core-spec-wd-1-en.odt*
>   Core schema:    *xacml-3.0-core-schema-policy-wd-1.xml*
> 
> Profiles should identify the version of what is being profiled if relevant:
> 
>   Profile:        *xacml-2.0-profile-ws-policy-1.0-spec-wd-1-en.odt*
>   Profile schema: *xacml-2.0-profile-ws-policy-1.0-schema-wd-1.xml*
>   Profile:        *xacml-2.0-profile-saml-2.0-spec-wd-1-en.odt*
> 
> If we update a profile, give it an new version (v2, v3, etc.)
> 
>   Profile:        *xacml-2.0-profile-saml-2.0-v2-spec-wd-1-en.odt*
>   Profile schema: *xacml-2.0-profile-saml-2.0-v2-schema-assertion-wd-1.xml*
> 
> 
>   "Persistent location"
> 
> OASIS administration will put documents under:
> 
>    *http://docs.oasis-open.org/xacml/2.0/..*
>    *http://docs.oasis-open.org/xacml/3.0/..*
> 
> 
>   URI's
> 
> We can continue to use:
> 
>   *urn:oasis:names:tc:xacml:2.0:...*
> 
> Example:
> 
>   *urn:oasis:names:tc:xacml:2.0:profile:saml2.0:v2:schema:assertion*
> 
> They recommend URIs of the following form:
> 
>   *http://docs.oasis-open.org/xacml/...*
> 
> ------------------------------------------------------------------------
> Anne Anderson <> <mailto:>
> 
> Last modified: Thu Sep 28 12:49:04 EDT 2006

-- 
Anne H. Anderson             Email: 
Sun Microsystems Laboratories
1 Network Drive,UBUR02-311     Tel: 781/442-0928
Burlington, MA 01803-0902 USA  Fax: 781/442-1692