"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.
A namespace is identified by a URI. The namespace associated to a
specification is of the form
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
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
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
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
(, 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
) and the function type declaration.
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.
The URL where a specification is published can be of several forms:
codeis the short code, like
X.Yis the version number, like
YYYYMMDDis the publication date, like
In addition, when it is applicable, the URL can end with:
/difffor a version where differences with the previous version are highlighted
.xmlfor 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
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
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:
http://expath.org/spec/http-client: the latest version
http://expath.org/spec/http-client/1.0: the version 1.0
http://expath.org/spec/http-client/1.0.xml: the version 1.0 as XML
http://expath.org/spec/http-client/20130818: the draft from Aug. 18, 2013
http://expath.org/spec/http-client/20130818/diff: the draft from Aug. 18, 2013, with differences with the previous draft highlighted
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".