Schemes and separators

@evanion/urn allows you to override the default scheme and separator in your namespace class. This means you can mint identifiers that look like dotted paths (e.g., baize.game.azul) rather than standard URNs.

The Problem: Non-Standard Internal Identifiers

While RFC 8141 is the global standard for resource naming, many internal systems use different conventions for their keys. You might have a legacy system that expects dotted paths (system.resource.id) or a custom internal scheme (app:resource:id) that isn’t strictly a URN.

Forcing these identifiers into a urn:nid:nss format can make logs harder to read or break compatibility with existing internal tooling.

Solution: Custom Schemes and Separators

By overriding the scheme and separator properties in your namespace class, you can tell @evanion/urn to use your own conventions while still benefiting from the library’s parsing and validation logic.

For example, a GameKey class that sets the scheme to baize and the separator to . will produce identifiers like baize.game.azul.

class GameKey extends URN {
  static override readonly urn = 'baize';
  static override readonly nid = 'game';
  static override readonly separator = '.';
}
 
GameKey.stringify('azul'); // -> 'baize.game.azul'
GameKey.parse('baize.game.azul'); // -> { urn: 'baize', nid: 'game', nss: 'azul' }
GameKey.parse('baize.game.azul.2017').nss; // -> 'azul.2017'
URN.schemeGrammar.test('baize.shop'); // -> true
GameKey.schemeGrammar.test('baize.shop'); // -> false

Impact on Validation

When you use a custom separator, the library adjusts its grammar checks:

• The scheme and NID are checked against a character class that excludes the separator.
• This allows you to use one-character NIDs that the standard URN class would refuse.
• However, the NSS (the actual ID) always keeps the RFC 8141 grammar, regardless of the separator.

Verifying Namespaces Across Different Schemes

The belongsToNamespace method defaults its scheme check to the calling class’s own scheme. If you are checking a URN that uses a different scheme than your current class, you must provide the scheme as the third argument.

Otherwise, a GameURN (which uses urn) will return false for baize:game:azul:

GameURN.belongsToNamespace('urn:game:azul', 'game'); // -> true
GameURN.belongsToNamespace('baize:game:azul', 'game'); // -> false
GameURN.belongsToNamespace('baize:game:azul', 'game', 'baize'); // -> true

Component Restrictions for Special Separators

Because components are identified by ? and #, you cannot use these characters as separators.

If you set a separator like static override readonly separator = '#', the library cannot distinguish between the separator and the start of a component. In this case:

• parse will throw an InvalidError for any URN carrying a ? or # after the NID.
• stringify will throw an InvalidError if you attempt to add a component.

Every other separator allows components to work as described in the r-, q- and f-components guide.

Every @evanion/urn export

The API reference lists every class, function, error and type @evanion/urn exports, including the static properties a namespace class can override.