There is often a need to render namespace tuples and track names for purposes such as logging, representing track filenames, or use in certain authorization verification schemes. The namespace and track name are binary and need to be converted to a safe form.
The following format is RECOMMENDED:
-
Each of the namespace tuples are rendered in order with a hyphen (-) between them followed by the track name with a double hyphen (--) between the last namespace and track name.
-
Bytes in the range a-z, A-Z, 0-9 as well as _ (0x5f) are output verbatim, while all other bytes are encoded as a period (.) symbol followed by exactly two lowercase hexadecimal digits.
This format allows many common names to be rendered in an easily human readable form while still supporting binary values. Note that while the character set is chosen to be generally both filename and URL safe, filename safety is platform specific; for instance, on case-insensitive filesystems, track names can collide.
Because this format produces exactly one rendering of any given binary value, it
is bijective: every valid serialized name maps to exactly one binary value, so
serialized names can be compared without deserializing them. To maintain this
property, an implementation parsing this format MUST reject a name that does
not follow the encoding rules exactly, including a period not followed by
exactly two lowercase hexadecimal digits, or a byte that could have been
represented literally but was hex-encoded. For example, .61 is invalid
because a is represented as the literal character a. How an invalid name is
handled is application-defined.
Example:
example.2enet-team2-project_x--report Namespace tuples: (example.net, team2, project_x) Track name: report