[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: 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 <Anne.Anderson@sun.com> <mailto:Anne.Anderson@Sun.COM> > > Last modified: Thu Sep 28 12:49:04 EDT 2006 -- 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-1692Title: 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:
Reviewer: Anne Anderson <Anne.Anderson@sun.com> Version: 1.3 Updated: 06/09/28 (yy/mm/dd)
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 later 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.
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 is no guidance on specification titles other than
[Specification Title vX.X]
I propose:
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
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
OASIS administration will put documents under:
http://docs.oasis-open.org/xacml/2.0/.. http://docs.oasis-open.org/xacml/3.0/..
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/...
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]