Namespaces

Every schema is identified as <namespace>:<name> (e.g. com.example.myapp:article). The namespace groups the schemas that are shipped together, and prevents collisions between independent providers that happen to use the same schema name.

A namespace is a dot-separated identifier, and it is the application name: an application named com.example.myapp defines the com.example.myapp namespace, and the schemas it ships live there. The developer does not declare the namespace explicitly. Reverse-DNS (com.<org>.<app>) is a common convention but not required — acme.editorial or myschemas work just as well.

Each dot-separated segment may contain letters, digits, and underscores. Dashes are not allowed, since dots are converted to dashes when a namespace is used in a property name. The identifier is limited to 63 characters in total. Lowercase is the convention.

Namespaces are not limited to schemas — the same identifier names the application in every other context as well. Four namespaces are reserved by the platform for built-in functionality, and cannot be used as an application name:

Beyond the four reserved names, built-in platform APIs occupy namespaces of their own — server for the management APIs (e.g. server:app) and admin for the admin APIs (e.g. admin:status, admin:event). These are not rejected as application names, but an application using them would collide with the built-in APIs.

The literal <namespace>:<name> identifier is preserved in some contexts and re-encoded in others, depending on what characters are legal in the surrounding format.

Values preserved

Re-encoded