Revised:OASIS Naming Guidelines for XACML, v1.4

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

Colleagues,

Erik and I queried Robin Cover and Mary McRae about which guidelines 
documents were normative, and about specific names, and I have revised 
the proposed XACML guidelines accordingly.  I think what readers care 
about most is specification titles and file names, so look particularly 
at those sections and make sure you are happy.

If everyone is happy with these, I would like the TC to approve them so 
that we can have some consistency in our specification titles and file 
names.

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: OASIS Naming Guidelines for XACML

OASIS Naming Guidelines for XACML

Editor:  Anne Anderson 
Version: 1.4
Updated: 06/10/03 (yy/mm/dd)

This is a profile of the current OASIS document and naming guidelines for applicability to XACML specifications, schemas, and names. It is based on the following references:

• [1] Guidelines for Filenames, URIs, Namespaces, and Metadata 2006-07-20
• [2] OASIS Naming Guidelines: Metadata and Versioning 2006-09/30
• [3] Specification Templates
• [4] Microsoft Word [Specification Template] User Guide (.doc)

According to e-mail from Robin Cover, 3 Oct 2006, Document [1] is the base document. Document [2] supplements and clarifies [1], and is in the process of being merged with [1]. [3] should be used for document format templates, and [4] explains fonts, styles, document sections, etc., but [1] and [2] are the only normative naming guidelines, and override [3] and [4].

Contents

• Introduction and General Notes
• Specification Format
• Specification Title
• File Name
• Persistent Location
• URI's

Introduction and General Notes

The OASIS guidelines apply only to documents to be stored under http://docs.oasis-open.org/xacml/3.0/..., etc., but we will use them for Working Drafts also in order to make conversion to the standard format easier as specifications are approved.

No names of schema elements or attributes are affected.

See [1] and [2] for more details.

Specification Format

OASIS provides specification templates at [3], with instructions for their use in [4], which are not necessarily up-to-date. [1] and [2] override [3] and [4].

Changes from older versions:

Be sure to copy new versions of the changed pages from [3]

• Title: There are more fields to be filled in on the title page.
• Notices: The "Notices" page follows the title page, rather than being at the end, and has revised wording.
• Section 1: has a specified format: Introduction, Terminology, Normative References, and Non-normative References.
• An Appendix contains Acknowledgments, such as TC members that participated in development of the specification.
• An optional Appendix contains Revision History. This Appendix is not included in OASIS standard versions of a specification.
• An optional Appendix "should" contain any 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. [4] 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 not weird.

Specification Title

Syntax:

  [Specification Title] Version[X.X]

Note that all major words in the title are capitalized, and there is no comma before "Version", which is also capitalized.

There is no normative syntax for [Specification Title]. For XACML, we will construct names as in the following examples, but you should get your title approved by the OASIS administration (Robin Cover <robin@oasis-open.org>, Mary McRae <mary.mcrae&oasis-open.org>) before casting it in concrete:

• Core:
  Example: eXtensible Access Control Markup Language (XACML) Version 3.0
• Supplement to Core:
  XACML <XACML version> <Supplement Name> Version <Supplement version>
  Example: XACML 3.0 Administrative Policy Version 1.0
  
• Profile:
  <Profile target and version> Profile of XACML <XACML version> Version <profile version>
  Example: SAML 2.0 Profile of XACML 2.0 Version 2.0

File Name

There is no normative syntax for file names, except that normative specification files must be available in PDF and XHTML formats, and an editable version (.odt, .doc) must be available in the TC repository. When a file becomes a Committee Draft or OASIS Standard, it will be stored under http://docs.oasis-open.org/xacml/<XACML version>/ by the OASIS Administration.

For XACML, we will construct file names as follows:

Rough syntax:

  xacml-<xacml version>[-profile]-<topic>-v<topic version>-<doctype>-<stage>-<draft version>-<language>.<format>

where

• <topic> is something like "core", "administration", "profile-webservices", or "profile-saml2.0" - enough to identify the general category (spec, profile), topic, and any relevant versions, of the various versions
• <doctype> is usually spec or schema (there are some other less common types in [1]. schema may be further identified as to its sub-topic: schema-policy, schema-context
• <topic version> is vX.Y: "v1.0", "v2.0".
  
• <stage> is wd (Working Draft), cd (Committee Draft), or os (OASIS Standard)
• <draft version> is in sequential order (1,2,...10,11,9999999 :-)
• <language> is usually "en" (English)
• <format> is pdf, odt, html, etc. - normative specification documents must be available in pdf (.pdf) and xhtml (.html). In addition, an editable source version must be submitted to the TC's document repository (.odt, .doc)

Hyphens will be used to separate name components, and camel case will be used to separate elements within a name component, since underscores are hard to see when a URL is underlined.

The Document Identifier that goes on the title page of a specification is everything up through <draft version>.

Examples:

  Core spec:       xacml-3.0-core-spec-v1.0-wd-1-en.pdf
  Core schema1:    xacml-3.0-core-schema-policy-v1.0-wd-1.xml
  Core schema2:    xacml-3.0-core-schema-context-v1.0-wd-1.xml
  Supplement spec: xacml-3.0-administration-v1.0-wd-13.pdf

Profiles should identify the version of what is being profiled if relevant:

  Profile:        xacml-3.0-profile-webservices-spec-v1.0-wd-1-en.pdf
  Profile schema: xacml-3.0-profile-webservices-schema-v1.0-wd-1.xml
  Profile:        xacml-2.0-profile-saml2.0-spec-v2.0-wd-1-en.pdf
  Profile schema: xacml-2.0-profile-saml2.0-schema-assertion-v2.0-wd-1.xml

If we update a profile, give it a new version (v1.1, v2.0, etc.)

  Profile:        xacml-2.0-profile-saml2.0-v2.1-spec-wd-1-en.odt
  Profile schema: xacml-2.0-profile-saml2.0-v2.1-schema-assertion-wd-1.xml

Persistent Location

OASIS administration will put Committee Draft and OASIS Standard 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:data-type:dnsName

OASIS administration recommends URIs of the following form, but this is not a requirement:

  http://docs.oasis-open.org/xacml/3.0/...

---

Anne Anderson <Anne.Anderson@sun.com>

Last modified: Tue Oct  3 15:00:13 EDT 2006