URL Scheme Convention

Single-line summary: Mentionable publishes every machine-dereferenceable identifier (extension URIs, JSON-LD context terms, custom WebFinger rels, tools) under https://mentionable.dev/, organised by four small patterns. The /ns/ prefix is the canonical machine-namespace; legacy /spec/* and /agent-card URIs are kept alive only as transition aliases.

See also: architecture-overview, glossary, webfinger-agent-card-guide

Spec sources: docs/spec/webfinger.md, docs/spec/agent-card.md, docs/spec/transport-rest-v0.1.md, docs/spec/policy-part-v0.1.md, docs/spec/identity-evidence-v0.1.md, docs/spec/a2a-tool-events-v0.1.md. Implementation: packages/core/src/{webfinger,agent-card,identity,policy,tool-call-events}.ts. Origin issue: #503.

Why /ns/

A Mentionable extension URI does two things at once: it’s a stable machine identifier callers compare against, and it’s a real URL a human can dereference to read the spec. The semantic web has settled on /ns/ (“namespace”) for exactly this role:

• W3C ActivityStreams: https://www.w3.org/ns/activitystreams
• JSON-LD core context: https://www.w3.org/ns/json-ld
• W3C RDF / OWL / SHACL vocabularies all live under /ns/<name>

Two prefixes for the same concept inside one project (/spec/* and /ns/*) drifts away from the surrounding ecosystem and forces every consumer to remember which spec author picked which. Standardising on /ns/ matches the broader convention and removes one decision from every future spec.

The four patterns

Examples

Versioned spec / extension URIs

Live, canonical:

• https://mentionable.dev/ns/transport-rest/v0.1 — REST transport extension declared by REST-conformant agents. Spec: transport-rest-v0.1.md.
• https://mentionable.dev/ns/policy/v0.1 — PolicyPart v0.1 conformance. Spec: policy-part-v0.1.md.
• https://mentionable.dev/ns/identity/v0.1 — IdentityEvidence v0.1. Spec: identity-evidence-v0.1.md.
• https://mentionable.dev/ns/a2a-tool-events/v0.1 — A2A tool-event DataPart envelope. Spec: a2a-tool-events-v0.1.md.
• https://mentionable.dev/ns/normalized-message/v0.1 — RFC 6906 MIME profile for the Normalized Message email sidecar. Spec: normalized-message.md.

JSON-LD context terms

A single shared major (v1) hosts the JSON-LD context for A2A agent card vocabulary:

• https://mentionable.dev/ns/v1#defaultAgent
• https://mentionable.dev/ns/v1#agents
• https://mentionable.dev/ns/v1#routerType
• https://mentionable.dev/ns/v1#protocols
• https://mentionable.dev/ns/v1#webfinger

These follow the JSON-LD compact-context convention: one document, one major version, many terms identified by URI fragments.

Custom rels

• https://mentionable.dev/ns/rel/agent-card — the WebFinger custom rel binding the acct: URI to its Mentionable AgentCard. Spec: webfinger.md §4.

Rels are stable identifiers by convention (compare IANA registered rels like self, next). Mentionable does not version them; a new shape gets a new rel name.

Tools / utility pages

• https://mentionable.dev/trace/ — interactive trace viewer that decodes a base64url Normalized Response from the URL fragment. Linked from AP / Email replies that embed structured tool-call traces.

Tools sit at the root because they’re products, not identifiers. They evolve in place and don’t need to be machine-pinned.

Backward compatibility policy

The unification is a wire-shape change. Pre-v1 Mentionable has no production-critical external adopters yet, so the cutover is hard at the spec layer, but we run a transition window for any cached link, external bookmark, or passive HTTP fetch by extension-aware clients:

1. apps/web serves the new URIs and 301-redirects the legacy ones. /spec/<topic>/v<X.Y> → /ns/<topic>/v<X.Y>. /agent-card → /ns/rel/agent-card. Browsers and crawlers see the new canonical URL; existing links keep working.
2. Inbound parsers dual-recognise both forms. Each @mentionable/core constant ships a _DEPRECATED alias and a KNOWN_* membership set; recognition predicates (isAgentCardRel, isRestTransportExtensionUri, …) accept either form. This lets pre-migration publishers interop without code changes on the receiver side.
3. Outbound emit is the canonical /ns/* URI only. Every constant in code, every example in spec docs, every conformance test publishes the new form. The deprecated alias is read-only — never written.

Deprecation removal policy

Mentionable packages are published with Changesets under semver; pre-1.0 the meaningful release cadence is the minor version (0.X). Aliases follow a three-release window keyed to minor releases:

1. Release N (announce). The minor that introduces the canonical form ships the deprecated alias alongside it. The release notes call out the deprecation, the migration target, and the planned removal release.
2. Release N+1 (warn). The next minor MAY emit a runtime deprecation warning the first time a recognised inbound payload uses the deprecated alias (one warning per process, including the canonical replacement URI).
3. Release N+2 (remove). The minor after that MAY drop both the _DEPRECATED constant and the alias entry from the KNOWN_* membership set. Inbound traffic still on the alias becomes unrecognised; emitters that have not migrated lose interop.

Aliases introduced before 1.0 that have not been announced for removal stay live until a future minor explicitly schedules them; the policy above is the maximum lifetime, not a guarantee that every alias is removed at the earliest opportunity. After 1.0 the same N / N+1 / N+2 cadence applies to major releases instead of minors, and removal MUST land in a major.

The unification done in #503 (the /spec/* → /ns/* and /agent-card → /ns/rel/agent-card aliases) is announced in the release notes of the minor that first ships /ns/* canonical; the schedule for its removal will be set in a later changeset once external adopters are surveyed.

Migration table

The canonical mapping from issue #503. Anything not listed here is unchanged.

Unchanged (do not migrate):

• https://mentionable.dev/ns/normalized-message/v0.1 — already canonical.
• https://mentionable.dev/ns/v1#<term> — JSON-LD context terms.
• https://mentionable.dev/trace/ — tool page.

Archived URIs in docs/proposals/archive/draft2-policy-and-mandates.md are left verbatim. Archived material is a historical record; it does not migrate.

Versioning rules

Per-spec semver under /ns/<topic>/v<X.Y>:

• Major bump (vX → v(X+1)) — breaking wire change. Old URI keeps pointing at the old spec; the new URI is a separate identifier. Receivers opt in by declaring the new extension URI. Two versions can run side-by-side during migration.
• Minor bump (v0.1 → v0.2) — additive change. New optional fields, new enum values that follow the spec’s “open string” rule, new helpers — anything an existing receiver can ignore safely. The URI changes but old callers stay correct.
• Patch bump (v0.1.1) — editorial / clarifying changes that don’t change the wire shape at all. The URI stays at the parent minor.

JSON-LD context terms follow the shared major (v1); they’re additive within a major and only get a new major if the core context shape changes.

Custom rels (/ns/rel/<name>) are unversioned. A new shape gets a new name; we don’t ship agent-card/v2.

Notes for new specs

When you draft a new spec under docs/spec/:

1. Pick the right pattern from the table above. Almost always /ns/<topic>/v<X.Y> for spec docs and extension URIs.
2. Land the URI in code as a constant with three siblings: the canonical URI, an optional _DEPRECATED alias (only if you are migrating), and a KNOWN_* ReadonlySet<string> for membership-check recognition.
3. Add a one-line **Extension URI:** header at the top of the spec doc and a Deprecated-alias note immediately under it if applicable.
4. Update this page if your spec introduces a new URI pattern.