Naming

From EXPath Community Group

"To call things by incorrect names is to add to the world's misery."

This page documents the naming rules for various things defined in EXPath specifications. The rules are organized by the nature of those things to be named.

Namespaces

A namespace is identified by a URI. The namespace associated to a specification is of the form http://expath.org/ns/{module}, where module must be replaced by the specification short code. The same short code is used in the address of the specification document itself. It must consist only of lower case latin letters (from a to z) and of dashes (dashes cannot appear at either end of the code, and there cannot be two consecutive dashes). A short code must be at least 3 letters-long.

For instance, the namespace URI for the HTTP Client module is http://expath.org/ns/http-client.

In addition to a short code, a specification will define a prefix bound to the namespace (this is of course a convention, as the namespace mechanism fortunately guarantee that the user can chose whatever prefix is best suited). That prefix is used consistently across the specification every time a lexical QName refers to that namespace (if a specification refers to a QName defined in another specification, it must use the same prefix as in the other specification). The namespace prefixes must be unique among all EXPath specifications. The prefix might be the same of the specification short code, but does not have to.

For instance, the namespace prefix for the HTTP Client module is hc.

Functions

Function names must be valid QNames (as defined by XPath). The namespace URI and prefix are defined at the specification level, as documented below. The function local name must follow the following rules (in addition to being a valid NCName, indeed):

  • contain only lower case latin letters (from a to z) and dashes
  • dashes cannot appear as the first nor last character
  • there cannot be two consecutive dashes
  • digits are tolerated if needed (e.g. in base64)

Each simple word is separated by a dash. The only exception where upper case latin letters can appear (from A to Z) is when the domain already contains such names (for instance the XML Schema type xs:hexBinary). This is discouraged though.

Within the specification (this is editorial) the function prototypes must look like the following: 

p:some-name($arg as xs:integer) as element(p:info)?

p:some-name($arg      as xs:integer,
            $new-name as xs:string) as element(p:info)?

The several arities of the same function are given all at once (the lower arity first). Parameters are given very short names (they must be defined in the text right after anyway, do not try to put all the semantics in the parameter name, just enough to distinguish it fro the other parameters). The same parameters in two different arities must be given the same name. The first parameter appears right after the opening (, the second parameter in a new line (its $ symbol must be right before the first one). The third parameter appears on the third line, with the same indentation, and so on. All the type clauses (all the as keywords) appear below each other. The line of the last parameter ends with the closing ) and the function type declaration.

Error codes

Error codes follow the same naming conventions as the function names (lower case latin letters, names separated with dashes, digits tolerated). As functions, the error codes are in the specification namespace (there are not in a specific error namespace).

Error codes should be kept short, though carying enough information about the error conditions to the reader. The entire definition does not have to be contained in the name, but it must be expressive enough to intuitively distinguish it from other error conditions.

Using number codes (like XPath, XQuery, XSLT and F&O specifications themselves do) is deprecated.

Specifications

The URL where a specification is published can be of several forms:

  • http://expath.org/spec/{code}
  • http://expath.org/spec/{code}/{X.Y}
  • http://expath.org/spec/{code}/{YYYYMMDD}
  • http://expath.org/spec/{code}/editor

where:

  • code is the short code, like http-client
  • X.Y is the version number, like 1.0
  • YYYYMMDD is the publication date, like 20130818

In addition, when it is applicable, the URL can end with:

  • /diff for a version where differences with the previous version are highlighted
  • .xml for the original XML source for the specification

The editor copy (the URL ending with /editor) is the latest version the editor is working on currently. This is useful in order for the editor(s) to share the current state of their own copy, without requiring them to actually publish a draft. The typical use case is to ask on the mailing list, after having integrated changes discussed in a long email chain, whether everyone is happy with the wording. This is not really a published document.

A draft is published at some point in time, and must be in a consitent state (some sections can be incomplete though). A draft is a public document, open to comments by anyone.

Once a specification is approved, it is assigned a version number. The first one is 1.0, then 2.0, and so on. A sub-version can be created if the editor and the Community Group feel it is the right thing (like 2.1).

The latest verison of a specification (the shortest URL, ending with the short code only) refers to the latest version of the specification if there is any. If it has not been approved yet, then it refers to the latest (pre-1.0) draft.

Examples of URLs for the http-client:

Notes

The quote in the introduction of this page is a translation from French: "Mal nommer les choses c'est ajouter au malheur du monde.", in Brice Parain, "Sur une philosophie de l'expression".

Retrieved from "https://www.w3.org/community/expath/wiki/index.php?title=Naming&oldid=62"