{"is":"instructionGraph001","item":{"content":{"description":"A truly global, decentralized graph where data objects can be scattered anywhere and reassembled by any agent that discovers them. Extract docs: cat THIS_FILE | jq -r .item.instruction > dataverse.md","name":"dataverse001"},"created_at":"2026-02-03T12:03:41+01:00","id":"00000000-0000-0000-0000-000000000000","in":["dataverse001"],"instruction":"# instructionGraph001 — Data Format Specification\n\nA signed, self-describing graph data format. Each object is a self-contained JSON fragment that can be verified, interpreted, and linked to other objects by any agent that encounters it.\n\ninstructionGraph001 defines the **wire format** — how objects are structured, signed, identified, and related. It says nothing about where objects live, how they propagate, or what realms they belong to. Those concerns are left to specific deployments (like dataverse001).\n\n## Object Format\n\n```json\n{\n \"is\": \"instructionGraph001\",\n \"signature\": \"\",\n \"item\": {\n \"in\": [\"\"],\n \"ref\": \".\",\n \"id\": \"\",\n \"pubkey\": \"\",\n \"created_at\": \"\",\n \"updated_at\": \"\",\n \"revision\": 0,\n \"type\": \"POST\",\n \"name\": \"My First Post\",\n \"instruction\": \"A post. Display title and body.\",\n \"rights\": {\n \"license\": \"CC0-1.0\",\n \"ai_training_allowed\": true\n },\n \"relations\": {\n \"in_application\": [{\"ref\": \".\"}],\n \"in_subcommunity\": [{\"ref\": \".\"}],\n \"author\": [{\"ref\": \".\"}]\n },\n \"content\": {\n \"title\": \"Hello World\",\n \"body\": \"First post!\"\n }\n }\n}\n```\n\n## Envelope vs Item\n\nAn instructionGraph001 object has two layers:\n\n- **Envelope** (unsigned): Contains `is` (format identifier) and `signature`. This is what generic tooling uses to recognize and verify the object.\n- **Item** (signed): The actual payload. Everything inside `item` is covered by the signature.\n\nThe `is` field identifies the data format. The `signature` covers the canonical JSON of `item`. This envelope pattern means you can add unsigned metadata (like transport hints) without breaking the signature.\n\n## Object Identity\n\nObjects are uniquely identified by the composite key `(pubkey, id)`. This prevents UUID squatting — you can only create objects under your own pubkey namespace.\n\n### Composite Key Format\n\nThe composite key is expressed as a single string: `{pubkey}.{id}`\n\nExample: `AxyU5_5vWmP2tO_klN4UpbZzRsuJEvJTrdwdg_gODxZJ.346bef5e-94ff-4f7a-bcf6-d78ae1e1541c`\n\nThis format:\n- Uses `.` as delimiter (URL-safe, filesystem-safe, not in base64url or UUIDs)\n- Enables direct lookup by filename, URL path, or database key\n\nEvery object carries its own composite key in the `ref` field (`item.ref`). This matches exactly what other objects use to point at it in relations.\n\n## Required Fields\n\n**Envelope (unsigned):**\n\n- **is**: Must be `\"instructionGraph001\"`. Format identifier for parsers and scanners.\n- **signature**: ECDSA signature over the canonical JSON of `item`.\n\n**Item (signed):**\n\n- **item.in**: Array of realm strings. The signer controls which realms/databases the object belongs to. This is part of the signed payload.\n- **item.ref**: Composite key `{pubkey}.{id}` — the object's own reference.\n- **item.id**: UUID.\n- **item.pubkey**: Creator's public key (compressed raw EC point, base64url encoded).\n- **item.created_at**: ISO8601 timestamp.\n\n## Optional Fields\n\n- **item.name**: Short human-readable label.\n- **item.updated_at**: Timestamp of last modification.\n- **item.revision**: Integer counter, incremented on update. Higher revision wins on sync.\n- **item.type**: Application-level type hint (e.g. `POST`, `COMMENT`, `IDENTITY`, `TYPE`).\n- **item.instruction**: Free-text field telling agents how to interpret/display this object. The core mechanism for self-describing data.\n- **item.rights**: Object grouping licensing and usage permissions (see Licensing & AI Training below).\n- **item.relations**: Named arrays of relation entries (see below).\n- **item.content**: Free-form payload (title, body, structured data, etc.).\n\n## Relations\n\nRelations are named arrays of objects with a `ref` field containing a composite key:\n\n```json\n\"relations\": {\n \"author\": [{\"ref\": \"AxyU5_...346bef5e...\"}],\n \"replies_to\": [{\"ref\": \"BzxY7_...a1b2c3d4...\", \"title\": \"Parent post\"}]\n}\n```\n\nEach relation entry:\n- **ref** (required): The composite key `{pubkey}.{id}` of the target object.\n- **revision** (optional): Pin to a specific revision of the target. Default: latest.\n- Additional fields (optional): `title`, `summary`, `url`, `instruction`, or any other hints to help agents understand the relation without fetching the target.\n\nTo parse a composite key: `split('.')` -> `[pubkey, id]`\n\n## Self-Describing Objects\n\nThe `instruction` field is the core innovation. It tells any agent — human or LLM — how to interpret, display, and interact with the object. An object with a good instruction field can be understood without any external documentation.\n\nFor repeated types, use a `type_def` relation to reference a TYPE object that defines the schema and behavior for all objects of that type:\n\n```json\n\"relations\": { \"type_def\": [{\"ref\": \".\"}] }\n```\n\nAgents MUST read the referenced TYPE object's instruction before creating objects of that type. The type definition contains schema, required relations, and display guidance that the object's own `instruction` field alone may not cover. Skip only if the TYPE object cannot be found locally or on any reachable hub.\n\n## Cryptography\n\n- **Algorithm**: ECC P-256 (prime256v1) with ECDSA\n- **Key format**: Compressed raw EC point (33 bytes), base64url encoded (44 characters, no padding)\n- **Signing input**: Canonical JSON of `item` — compact, sorted keys (`jq -cS`), no trailing newline\n\n### Public Key Format\n\nThe `pubkey` field contains the **compressed raw EC point** encoded as base64url (no padding):\n\n- **Format**: `02|03 || X` (33 bytes) — EC point in compressed form\n- **Encoding**: base64url (RFC 4648 section 5) — uses `-` and `_`, no `=` padding\n- **Result**: 44 characters\n\n### Generating a Keypair\n\n```bash\n# Generate private key\nopenssl ecparam -genkey -name prime256v1 -noout -out private.pem\n\n# Extract compressed raw pubkey as base64url\nopenssl ec -in private.pem -pubout -conv_form compressed -outform DER 2>/dev/null \\\n | tail -c 33 | base64 | tr '+/' '-_' | tr -d '='\n```\n\n### Signing\n\n```bash\necho \"$ITEM\" | jq -cS '.' | tr -d '\\n' > /tmp/item.json\nopenssl dgst -sha256 -sign private.pem /tmp/item.json | base64 -w0\n```\n\n### Verifying\n\nP-256 compressed keys need a fixed 26-byte DER header for OpenSSL:\n\n```bash\nDER_HEADER=\"3039301306072a8648ce3d020106082a8648ce3d030107032200\"\n```\n\n```bash\n#!/bin/bash\n# verify - Verify signature of an instructionGraph001 object\nFILE=\"${1:?Usage: ./verify }\"\nDER_HEADER=\"3039301306072a8648ce3d020106082a8648ce3d030107032200\"\n\njq -cS '.item' \"$FILE\" | tr -d '\\n' > /tmp/ig_item.json\njq -r '.signature' \"$FILE\" | base64 -d > /tmp/ig_sig.bin\n\nPUBKEY_B64URL=$(jq -r '.item.pubkey' \"$FILE\")\nPUBKEY_B64=$(echo \"$PUBKEY_B64URL\" | tr '_-' '/+')\ncase $(( ${#PUBKEY_B64} % 4 )) in\n 2) PUBKEY_B64=\"${PUBKEY_B64}==\" ;;\n 3) PUBKEY_B64=\"${PUBKEY_B64}=\" ;;\nesac\nPUBKEY_HEX=$(echo \"$PUBKEY_B64\" | base64 -d | xxd -p -c 100)\n\necho -n \"${DER_HEADER}${PUBKEY_HEX}\" | xxd -r -p > /tmp/ig_pub.der\nopenssl ec -pubin -inform DER -in /tmp/ig_pub.der -outform PEM -out /tmp/ig_pub.pem 2>/dev/null\n\nopenssl dgst -sha256 -verify /tmp/ig_pub.pem -signature /tmp/ig_sig.bin /tmp/ig_item.json\n```\n\n## Design Principles\n\n- **Self-contained**: Every object carries enough context to be understood independently.\n- **Transport agnostic**: Objects can travel via any channel — APIs, DHTs, Bluetooth mesh, LoRa, QR codes, steganography, blockchains. The format doesn't care how you got the data.\n- **Graceful degradation**: No strict hash-chains that break when one object is missing. Signatures double as integrity checks. Related objects are nice-to-have, not hard dependencies.\n- **Offline resilience**: The graph must function as well as possible while fragmented. When internet goes down, any previously usable app should still be usable — it's already local, along with whatever data it had cached. Apps that run on the graph tend to be *in* the graph (PAGE objects for browser apps, APPLICATION objects for apps that boot in an LLM), so they travel and cache alongside the data they operate on.\n- **Composable**: Objects can belong to multiple realms simultaneously via the `in` array. The signer controls realm membership.\n\n## Realm Membership (`in` field)\n\nThe `in` field is an array of realm strings inside `item` (signed). It declares which databases, networks, or communities the object belongs to. The signer controls this — realm membership is a deliberate, signed act.\n\nObjects can belong to multiple realms: `[\"dataverse001\", \"acme_internal\"]`. Realm semantics (propagation rules, access control, discovery) are defined by each realm, not by this format spec.\n\n## Revisions and Conflict Resolution\n\nOne object per composite key. Updates increment `revision`. On sync conflicts, higher revision wins.\n\n---\n\n# dataverse001 — A Global Database on instructionGraph001\n\ndataverse001 is a specific **realm** built on the instructionGraph001 data format. It's a truly global, decentralized graph where data objects can be scattered anywhere — files, disk slack space, steganography in images — and reassembled by any agent that discovers them.\n\nEvery object is a self-contained JSON fragment with `\"dataverse001\"` as a magic marker. When any device encounters this marker, it knows the object belongs to the global graph and can fold it into its local view.\n\n## What Makes dataverse001 Special\n\nMost realms are scoped — a corporate database, a private space, a project-specific store. dataverse001 is different: it's the **global commons**. Objects in this realm are meant to spread through every medium they can find and live forever.\n\nPutting `\"dataverse001\"` in your `item.in` array is a deliberate, signed act. You're saying: \"This should propagate globally.\"\n\n### Wild Scanning\n\nScanners grep for `dataverse001` in raw byte streams as a pre-filter, then parse JSON and verify that `item.in` contains `\"dataverse001\"`. Objects can be discovered in any data stream — disk images, network captures, embedded in other files.\n\nOther realms don't get this treatment. They propagate through configured routing, not through wild scanning.\n\n## Realm Composition\n\ndataverse001 is not a walled garden. It composes with other realms:\n\n- **Cross-realm type sharing**: A custom realm references type definitions from dataverse001 via `type_def` relations. The type lives here, the object lives in the custom realm.\n- **Multi-realm membership**: `[\"dataverse001\", \"acme_internal\"]` — visible to both global and internal agents.\n- **Server-public realm**: Use `\"server-public\"` for objects that should be readable by anyone on the current hub but should not propagate globally. This is useful for hub-local public apps, business data, or deployment-specific content.\n- **Private realms**: Use a pubkey as realm name for a private space. Omit `\"dataverse001\"` to keep it off the global graph.\n\n\"Realm\" rather than \"namespace\" — the intent is composition, not isolation.\n\n## Well-Known Realm Semantics\n\nThe dataverse currently relies on a few realm patterns with distinct visibility and propagation behavior:\n\n- **`dataverse001`** — readable by anyone and intended for global propagation and wild scanning.\n- **`server-public`** — readable by anyone, but hub-local by default. Objects in this realm stay on the hub they are pushed to unless a specific deployment chooses to forward them upstream.\n- **`` identity realm** — readable only by the matching authenticated identity.\n- **Shared realms** — readable only by authenticated members configured by the hub.\n\nUse `server-public` when you want public readability without turning something into part of the global commons.\n\n## Graph Structure\n\nObjects connect through named relations. There's a root node that structural objects link back to, but subgraphs can exist independently.\n\n### Root Node\n\nThe root node (`00000000-0000-0000-0000-000000000000`) is the entry point. It links to core types, identities, the app directory, and other foundational structures.\n\nStructural objects (identities, communities, specs, types) should include a `root` relation with a `url` for discoverability. Content objects (posts, comments) don't need this — they're reachable through structural objects.\n\n### Agent Behavior\n\nAny agent encountering verifiable dataverse001 objects should store them. The graph grows through opportunistic collection — objects propagate because agents find them useful enough to keep and share.\n\n**Agents MUST NOT add objects to the `dataverse001` realm by default.** The `dataverse001` realm is the global commons — objects placed there propagate everywhere and are intended to be world-readable forever. Only add `\"dataverse001\"` to an object's `in` array when the user has explicitly stated that they want that specific data to be world-readable.\n\n## Licensing & AI Training\n\nEvery object can optionally declare its license and usage permissions via `item.rights`:\n\n```json\n\"rights\": {\n \"license\": \"CC0-1.0\",\n \"ai_training_allowed\": true\n}\n```\n\n- **`license`**: An [SPDX identifier](https://spdx.org/licenses/) (e.g. `\"CC0-1.0\"`, `\"CC-BY-4.0\"`, `\"CC-BY-SA-4.0\"`). Declares the license for this object's content.\n- **`ai_training_allowed`**: `true` or `false`. Explicit signal whether the content may be used for training AI models.\n\nIf `rights` is absent or a field within it is absent, no assumption is made — the author simply hasn't declared.\n\n**Agents MUST NOT include a `rights` section by default.** Only add `rights` when the user has explicitly stated their licensing preferences.\n\n### Data by the People, for the People\n\nMuch of the dataverse's structural foundation — types, schemas, protocols, recipes — is public domain (`CC0-1.0`) and explicitly available for AI training. Not just by a few large corporations, but by anyone.\n\nWe encourage contributors to share under `CC0-1.0` with `\"ai_training_allowed\": true`. But it's your data — use whatever license fits your intent.\n\n","name":"dataverse001","pubkey":"AxyU5_5vWmP2tO_klN4UpbZzRsuJEvJTrdwdg_gODxZJ","ref":"AxyU5_5vWmP2tO_klN4UpbZzRsuJEvJTrdwdg_gODxZJ.00000000-0000-0000-0000-000000000000","relations":{"additional_instructions":[{"instruction":"Read these instructions to boot the dataverse.","ref":"AxyU5_5vWmP2tO_klN4UpbZzRsuJEvJTrdwdg_gODxZJ.59246a60-2fea-4c2b-bcf8-e8e728f8fd25"}],"app_directory":[{"instruction":"Index of applications built on the dataverse.","ref":"AxyU5_5vWmP2tO_klN4UpbZzRsuJEvJTrdwdg_gODxZJ.92da064a-88e6-481d-a874-05236e94874e"}],"author":[{"ref":"AxyU5_5vWmP2tO_klN4UpbZzRsuJEvJTrdwdg_gODxZJ.346bef5e-94ff-4f7a-bcf6-d78ae1e1541c"}],"core_types":[{"instruction":"Foundational type definitions for the dataverse. Read these if building on the dataverse.","ref":"AxyU5_5vWmP2tO_klN4UpbZzRsuJEvJTrdwdg_gODxZJ.e78f61fa-1905-4f0a-a55b-780ef9273c78"}],"dataverse_schema":[{"description":"Schema for every dataverse001 object","ref":"AxyU5_5vWmP2tO_klN4UpbZzRsuJEvJTrdwdg_gODxZJ.61f65458-c3fd-483b-bd07-e3ed56b47512"}],"page":[{"ref":"AxyU5_5vWmP2tO_klN4UpbZzRsuJEvJTrdwdg_gODxZJ.dfd23fb0-5e4a-4db5-8f6f-aa1291540b65","title":"What is Dataverse001"}]},"revision":41,"rights":{"ai_training_allowed":true,"license":"CC0-1.0"},"type":"ROOT","updated_at":"2026-04-09T11:52:59Z"},"signature":"MEUCIHR6NgHNkt0ejzYXUi2eweB43eaN/B67nCy0/aFcdGsqAiEA2t8x5yPdDOPE+xByXFQUN5C0ZIyNJtPP3PN/9daePf8="}