Each node has a reference of the form:
Package Reference . Local Reference
Local Reference is an alphanumeric name that must start with a letter, and may contain underscores.
Package Reference is a dot-delimited set of references. It identifies a node that acts as a package.
If you like it formally:
node-reference = [ package-reference . ]? local-reference package-reference = node-reference local-reference = [a-zA-Z_][a-zA-Z0-9_]*
For example, this page's node reference is metrici.documentation.devguide.using_metrici.node_references. Its package is metrici.documentation.devguide.using_metrici and its local reference is node_references.
An organisation's data is arranged in a hierarchy of packages. For uniqueness, the top-level package generall reflect the owning organisation's name. For example, the packages for Some Company should be in package somecompany.
Every node has one or more versions, which have a version reference of the form.
Node Reference . Version Number
Version numbers start at 1 and increase without gaps in the sequence. A version can be frozen (or made final), which means that it and all lower version numbers can no longer be changed. There can be a maximum of one non-frozen version (known as the draft version).
When specifying a node, the node version number part of a node version reference can be omitted or replaced with a special word:
- $latest - the most recent version
- $current - the most recent frozen version, or null if no versions are frozen
- $draft - the draft version, or null if all versions are final
- $best - the most recent frozen version, or the draft version if no versions are frozen
- 0 or omitted - same as $latest
When $latest and $best are used, the service will only ever return a draft version if the user is authorised to use draft versions; if they are not authorised they are hidden from the user unless explicitly requested by version number. When the user does not have authorisation to use draft versions, then $latest and $best work the same as $current.
When setting a node reference, the local part of the reference can be given as $auto, in which case a reference will automatically be generated, based on the name if possible.,
Note: the relationship between a package and its contents is not versioned. The nodes that represent packages may go through multiple versions, but the nodes within the package do not "belong" to any particular version.