XACML and OASIS document and naming guidelines

[Anne Anderson - Sun Microsystems <Anne.Anderson@sun.com>]

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
-- 
Anne H. Anderson             Email: Anne.Anderson@Sun.COM
Sun Microsystems Laboratories
1 Network Drive,UBUR02-311     Tel: 781/442-0928
Burlington, MA 01803-0902 USA  Fax: 781/442-1692

Title: XACML and OASIS Guidelines

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 <Anne.Anderson@sun.com>
Version:   1.2
Updated:   06/09/28 (yy/mm/dd)

Contents

• Introduction and General Notes
• Specification Format
• Specification Titles
• File Names, and "Document Identifier"
• "Persistent location"
• URI's

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 <Anne.Anderson@sun.com>

Last modified: Thu Sep 28 12:49:04 EDT 2006