THE RAILS

one identity in · one signed proof · every surface out

Write once, project everywhere

Do I have to rewrite my agent's identity for every registry? No. Define the Entity Card once and call one function per rail - the same code path emits every projection, gated by the same proof posture, so updating the card updates all of them. Think of it as a passport: one document, stamped for every border. KYA-OS does not ask existing ecosystems or protocols to migrate: it projects your identity onto them.

The SDK integration

The @kya-os/mcp/card subpath provides the translators: no hand-formatted schemas, no duplicate identity files.

import {  toServerCardMeta, toCatalogEntry, toA2AExtension, toAgentFacts, type EntityCard,} from '@kya-os/mcp/card';// 1. Define the Entity Card onceconst card: EntityCard = {  id: 'did:web:agents.example.com:my-agent',  entityType: 'agent',  name: 'my-agent',};// 2. Project it onto each railtoServerCardMeta(card); // server.json _meta blocktoCatalogEntry(card);   // catalog.json entry, always by referencetoA2AExtension(card);   // A2A AgentCard extensions[] itemtoAgentFacts(card);     // NANDA AgentFacts JSON-LD

import {
  toServerCardMeta, toCatalogEntry, toA2AExtension, toAgentFacts, type EntityCard,
} from '@kya-os/mcp/card';

// 1. Define the Entity Card once
const card: EntityCard = {
  id: 'did:web:agents.example.com:my-agent',
  entityType: 'agent',
  name: 'my-agent',
};

// 2. Project it onto each rail
toServerCardMeta(card); // server.json _meta block
toCatalogEntry(card);   // catalog.json entry, always by reference
toA2AExtension(card);   // A2A AgentCard extensions[] item
toAgentFacts(card);     // NANDA AgentFacts JSON-LD

Claim minimalism

What the card does not carry, in the spec's own words (section 4.2): "A Card ASSERTS only identity + type + declared capabilities + accountability locators." Delegations are not on the card: delegationRef is a locator, and the delegation chain it points at travels as separate signed credentials (W3C VC 2.0) that a verifier resolves and checks (section 10). The trust level is likewise recomputed by the verifier, never self-claimed (section 9): "the Card's self-declared conformanceLevel is NEVER trusted."

Rail by rail

What each projection emits, how its rail carries it, and where it is specified. Every export, key, and URI below is the reference implementation's (src/card/emit.ts); the standards row grounds each rail's status with evidence.

How the projections resolve

• One source of truth. Every projection references the same canonical card.json on the entity's did:web DID document (the KyaOsEntityCard service entry anchors it), so a verifier always lands back on one card.
• Each rail degrades, none fails. A stripped _meta degrades to a fetch of the canonical card; required: false lets an unaware A2A peer skip the item; conforming NANDA consumers preserve the unknown kya: keys.
• The proof is never projected. The per-request holder-of-key proof rides per-request _meta only; proofProfile merely names the profile a verifier should expect, and a stripped proofProfile is not a failure.

see all 19 standards rows, with evidence ->