YOS integration specification
YSDK is how any application becomes a room in YOS — discoverable by every other app, callable as a set of functions, installable on a device, and servable to other people. It invents almost nothing: identity is W3C DID, authority is UCAN, functional exposure is MCP, installability is the Web App Manifest. YSDK adds exactly one artifact to bind them.
Conformance is a ladder, not a threshold. Level 0 is a DID and a manifest. You do not have to boil the ocean to join it.
Your app's identifier comes from ydid.org and is controlled by you —
verifiable by anyone, revocable by you. YOS itself holds one of these. The store is
a customer of the identity system, not its issuer. That inversion is the point.
When one app uses another it never receives a key. It holds a capability: signed, scoped, expiring, revocable, passable on only in narrowed form. Lending a note that says may enter the kitchen, Tuesday only — not your house keys.
Your app publishes what it can do. Another app, or an agent acting for a person, discovers and calls it over MCP. A file manager becomes the file layer inside a video editor without the two teams ever meeting.
A visitor can use your app in a browser, install it and own the copy, or — if their machine qualifies and they opt in — run it for other people as a seed. One codebase, three relationships.
Three steps. The third one makes you a member.
Request a DID from the identity root. The private key is generated on your machine and never leaves it.
npx @ysdk/cli identity create --domain your-app.example
# → did:key:z6Mk… written to ./ysdk/identity.json (never commit this)One file. It binds your DID to your web manifest, your MCP endpoint, your capability grammar and your upgrade policy.
{
"ysdkVersion": "1.0.0-draft.2",
"did": "did:key:z6Mk…",
"identity": {
"signature": { "algorithm": "ML-DSA-87", "multicodec": "0x1212", "hybridWith": null, "sunsetAfter": null },
"keyAgreement": { "algorithm": "ML-KEM-1024", "multicodec": "0x120d", "hybridWith": "X448", "sunsetAfter": "2030-01-01" }
},
"app": {
"name": "Your App",
"domain": "your-app.example",
"webManifest": "/manifest.webmanifest",
"repository": "https://github.com/you/your-app",
"license": "MIT"
},
"modes": { "use": true },
"upgrade": { "policy": "explicit-always", "acceptedRanges": {},
"signatureRequired": true, "integrityHashRequired": true,
"rollbackSupported": true, "acceptanceLog": "/.well-known/ysdk.acceptance.log" },
"conformance": { "level": 0, "verifiedAt": "2026-08-30",
"evidence": { "didResolves": true, "runsStandaloneWithNoYos": true } },
"attestations": { "independentSecurityAudit": null,
"notReviewed": ["No independent security audit has been performed."] }
}Publish at /.well-known/ysdk.app.json, signed by your DID key.
You are now Level 0 — listed, resolvable, discoverable.
npx @ysdk/cli manifest sign ./ysdk.app.json
npx @ysdk/cli manifest check https://your-app.example
# → L0 PASS · signature verified · discoverable
Levels are earned by a run, never declared. The suite is tagged
@L0…@L6; its output populates the evidence block in your manifest.
Resolvable DID and a signed manifest at a well-known path.
Proven by: a third party resolves your DID and verifies the signature holding nothing but your public document.
Web App Manifest, service worker with a real update strategy, honest offline, three viewports, keyboard operable, focus visible through clip-path.
Proven by: the browser's own installability judgment, and offline confirmed by cutting the network — not by a manifest lint.
An MCP surface. Every tool documented, versioned, rate-limited, with sideEffects declared.
Proven by: an external consumer lists and calls a tool, and a gated tool refuses an uncredentialed call.
UCAN capabilities you issue and verify — scoped, expiring, revocable.
Proven by: issue, use, revoke, then observe the refusal across a fresh connection. A passing unit test is not sufficient evidence for this level.
Your app runs on someone else's machine, for other people, with declared and enforced capacity.
Proven by: the broker refuses to over-admit, and construction fails without operator opt-in and an abuse policy.
Your app has its own agent over its own knowledge partition.
Proven by: the app working fully with the agent dark — and turning it off not reflowing the layout by a single pixel.
Tamper-evident contribution records. Measurement only — YSDK does not define distribution of anything of value.
Proven by: a tamper attempt being detected.
Runs the real conformance checks in your browser. Nothing is uploaded, nothing is stored, no account required. Paste a domain we can fetch, or paste a manifest directly.
Fetches https://<domain>/.well-known/ysdk.app.json. Requires CORS on your side.
Results appear here. Every check names the specification clause it enforces.
The normative contract. Wire formats, verification order, the UI/UX contract with Baseline citations, and the non-negotiables.
Read the spec →JSON Schema 2020-12. Machine-readable, and what the validator on this page actually runs.
Get the schema →ysdk.org is itself a conforming app. This is its manifest — the reference implementation is the site you are reading.
Inspect it →ucan/dlg@1.0.0 and ucan/inv@1.0.0, with the Varsig header carrying the signature algorithm inside the envelope.@modelcontextprotocol/sdk 1.30.0.mldsa-87-pub 0x1212, mlkem-1024-pub 0x120d. Draft codepoints, so record the one you used rather than assuming it is stable.An ecosystem that invents its own identity, capability and RPC formats must persuade every application to learn three proprietary things, and must maintain them — including their security review — forever. A profile inherits their tooling, their test suites, and every application that already speaks them.
State as verified on 2026-08-30. Rooms that do not yet serve are marked, so you never build against an endpoint that isn't there.
Stated so nobody mistakes silence for permission.
You can reach Level 3 today without any of the above being resolved. That is the point of the ladder.