Package Naming Strategy
How Zervice generates globally unique, collision-free package names using Reverse Domain Name Notation.
Reverse Domain Name Notation (RDNN)
We use a strict Reverse Domain Name Notation system to ensure globally unique package names. This is the same approach used by Java packages, Android apps, and many other software ecosystems.
Key principle: Package names are derived from the apex domain only. Subdomains are not included in the namespace.
Naming Rules
| Scenario | Input | Package Name |
|---|---|---|
| Business domain | acme.com | com.acme.{agent-slug} |
| Subdomain (same owner) | api.acme.com | com.acme.{agent-slug} |
| Personal (GitHub) | github.com/johndoe | github.johndoe.{agent-slug} |
| Manual/Upload | User ID abc123 | user.abc123.{agent-slug} |
| System utility | Zervice | custom.zervice.{agent-name} |
Note: Subdomains like api.openai.com or docs.acme.com map to the apex domain namespace (com.openai.*, com.acme.*). The domain owner is responsible for organizing their agents using the {agent-slug} portion.
Sanitization Rules
- Hyphens (
-) become underscores (_):my-app.io→io.my_app - Reserved prefixes:
zervice,sys,admin,root,user
Collision Safety: You might wonder if my-app.io and my_app.io could collide after sanitization. They cannot—underscores are not valid characters in DNS domain names. Only letters, numbers, and hyphens are allowed. Our hyphen-to-underscore conversion is guaranteed collision-free.
Examples
acme.com → com.acme.assistant api.acme.com → com.acme.api-bot (same namespace as acme.com) weather.com → com.weather.forecast my-startup.io → io.my_startup.chatbot github.com/alice → github.alice.my-agent
Namespace by User Type
Business Users (Organization)
Create agents under your verified domain namespace.
com.yourdomain.*Personal Users (GitHub)
Create agents under your GitHub username namespace.
github.username.*Manual/Upload
Agents without verification get a user-scoped namespace.
user.{userId}.*