Node references

Reference structure

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.

Version numbers

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 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.