{"slug":"oip-link-structure","title":"OIP link structure","body":"## What is OIP?\n\nOIP stands for Object Invocation Protocol. It is a way for AI models to interact with digital \"objects.\" OIP uses standard web links. Any model that can open a URL can use OIP. There is no persistent session. This means the model does not need to maintain a continuous connection to a server.\n\n## What this article explains\n\nOIP links are not just a list of web addresses. They are typed handles to objects. A link should clearly state what object it opens. It should also show what a caller can do with that object.\n\n## OIP vs. MCP\n\nMCP stands for Model Context Protocol. MCP is an open standard. An AI model connects to an MCP server over a session. The server then provides tools, resources, and prompts. The model can call these. MCP is not a content-management system.\n\nOIP differs from MCP. OIP uses plain URLs. It uses receipts to confirm actions. There is no persistent session in OIP. Any model that can open a URL can act using OIP.\n\n## Link types\n\nDifferent OIP links serve different purposes:\n\n*   A **root article** explains the protocol itself.\n*   A **shelf article** groups related systems.\n*   A **system article** lists specific capabilities.\n*   A **capability article** explains one executable object.\n*   A **bundle link** provides machine-readable JSON data.\n*   A **receipt link** proves that an invocation happened.\n\n## Rule\n\nAn OIP link must be self-explaining. The receiving model must be able to tell its purpose. This includes whether it is for reading, invoking, proving, replaying, or repairing.\n\n## OIP Build Process\n\nThe OIP build is miscsubjects.com. Directory rows on this site are the objects. To invoke an object, you send a request to a specific endpoint.\n\nAn **endpoint** is a specific URL where an API can be accessed. An **API** (Application Programming Interface) is a set of rules that allows software applications to communicate.\n\nYou can invoke an object in two ways:\n\n1.  **POST request:** Send data to `/api/dispatch`. The data must be in JSON format. It includes a `key` for the object and a `body` with the invocation details. For example: `POST /api/dispatch { \"key\": \"my_object_key\", \"body\": { \"action\": \"do_something\" } }`.\n2.  **GET request:** Use the URL `/api/dispatch`. Include `invoke=KEY` and `body=...` as query parameters. For example: `GET /api/dispatch?invoke=my_object_key&body=%7B%22action%22%3A%22do_something%22%7D`.\n\nEvery invocation creates a record. This record is stored in an append-only ledger. An **append-only ledger** is a record book where new entries can only be added, not changed or deleted.\n\nEach invocation also generates a **receipt**. A receipt is a unique identifier. It confirms that your invocation was received. You can find the receipt at `/api/dispatch?receipt=inv_ID`. Here, `inv_ID` is the unique identifier for your invocation.\n\n## Error Handling and Debugging\n\nReceipts are important for debugging. If an invocation does not work as expected, you can use its receipt. The receipt allows you to check the status of your invocation. This helps you understand what went wrong.\n\n## Machine shape\n\nAn OIP link can be described using machine-readable JSON. **JSON** (JavaScript Object Notation) is a lightweight data-interchange format. This structure helps machines understand the link's properties.\n\nHere is an example of an OIP link's machine shape:\n\n```json\n{\n  \"kind\": \"capability\",\n  \"url\": \"https://miscsubjects.com/api/dispatch\",\n  \"method\": \"POST\",\n  \"object_id\": \"my_specific_capability\",\n  \"scope\": \"public\",\n  \"auth_required\": false,\n  \"result_shape\": {\n    \"type\": \"json\",\n    \"schema_url\": \"https://miscsubjects.com/schemas/capability_result.json\"\n  },\n  \"next_step\": {\n    \"description\": \"Check invocation status\",\n    \"url_template\": \"https://miscsubjects.com/api/dispatch?receipt={inv_ID}\"\n  },\n  \"documentation_url\": \"https://miscsubjects.com/a/oip-link-structure\"\n}\n```\n\n*   `kind`: Describes the type of object the link points to (e.g., `capability`).\n*   `url`: The **URL** (Uniform Resource Locator) is the web address for the object's endpoint. An **endpoint** is a specific URL where an API can be accessed.\n*   `method`: The HTTP method to use (e.g., `POST`, `GET`).\n*   `object_id`: A unique identifier for the specific object.\n*   `scope`: Defines who can access this object (e.g., `public`, `private`).\n*   `auth_required`: A boolean value. It indicates if authentication is needed. If `true`, a **token** might be required. A token is a piece of data that proves your identity or authorization.\n*   `result_shape`: Describes the expected format of the response. It can include a `schema_url` for validation.\n*   `next_step`: Suggests a logical next action. This often includes a URL template to follow up.\n*   `documentation_url`: A link to human-readable documentation about this object or protocol.\n## Latest clarity reviews (live)\n\nFresh models are sent this article's bundle and asked two separate questions: how clear is the machine JSON, and how clear is the English body. Scores are 0 to 10. The full history is in the append-only ledger.\n\n- 2026-07-02 23:55 · model `@cf/meta/llama-3.3-70b-instruct-fp8-fast` · NEEDS WORK · JSON 9/10 · English 8/10 · zero-context human 6/10\n  - gaps named: MCP explanation; OIP build process; Error handling and debugging\n\nHow the loop self-corrects: a failing review queues a model revision of this article (a new append-only version). A missing concept named by a reviewer queues a brand-new machine-written article, which then enters the same review cycle.","register":"oip_protocol","tags":["oip","object-invocation-protocol","protocol-specification","machine-native-json","primer"],"style":{"accent":"#16324f","measure":860},"claims":[{"id":"oip-c1","tier":"system","text":"The OIP article layer is generated from live directory rows, so it documents the objects that actually run the reference implementation.","who_claims":"system/oip_articles","source_ids":["oip-s3","oip-s4"]},{"id":"oip-c2","tier":"system","text":"The OIP operating path is caller to directory object to dispatch runner to invocation ledger to receipt.","who_claims":"system/oip_articles","source_ids":["oip-s1"]},{"id":"oip-c3","tier":"system","text":"Every executable capability in the reference implementation is reachable as an OIP object with a human article, a machine document, invocation history, and receipt path.","who_claims":"system/oip_articles","source_ids":["oip-s2","oip-s3"]},{"id":"oip-c4","tier":"system","text":"Tap & Go is the copy primitive: one drop carries credential, protocol, tree, search, execute, and receipt instructions without a separate token-map-bundle assembly step.","who_claims":"system/oip_articles","source_ids":["oip-s2"]},{"id":"oip-c5","tier":"system","text":"OIP receipts are the proof object for actions: they record request, response, actor, links, replay, repair, and lineage.","who_claims":"system/oip_articles","source_ids":["oip-s2","oip-s5"]}],"sources":[{"id":"oip-s1","type":"protocol","title":"BUILD_SPEC object invocation path","url":"https://miscsubjects.com/api/file/docs/BUILD_SPEC.md","summary":"Defines directory rows, dispatch, ledger, and the escalation path for changing the build.","quote":"Run anything: POST https://miscsubjects.com/api/dispatch {key, body}","claim_ids":["oip-c2"],"link_status":"ok","hash":"oipbuildspec0001"},{"id":"oip-s2","type":"protocol","title":"Object Invocation Protocol spec","url":"https://miscsubjects.com/api/file/docs/OIP.md","summary":"Defines OIP surfaces, invariant loop, receipt/replay/repair, and invocation envelopes.","quote":"identify, explain, invoke, ledger, yield","claim_ids":["oip-c3","oip-c4","oip-c5"],"link_status":"ok","hash":"oipspec00000002"},{"id":"oip-s3","type":"protocol","title":"Live OIP capability tree","url":"https://miscsubjects.com/api/dispatch?map=1&format=markdown","summary":"Public recursive capability tree.","quote":"root > shelf > system article > capability article > receipt","claim_ids":["oip-c1","oip-c3"],"link_status":"ok","hash":"oipmap0000000002"},{"id":"oip-s4","type":"protocol","title":"Directory row documentation","url":"https://miscsubjects.com/api/dispatch?key=OIP_TREE&format=markdown","summary":"Capability articles are generated from live rows.","quote":"Machine Contract","claim_ids":["oip-c1"],"link_status":"ok","hash":"oiprow0000000003"},{"id":"oip-s5","type":"protocol","title":"Invocation ledger","url":"https://miscsubjects.com/api/invocations","summary":"Append-only invocation records and receipt links.","quote":"invocations","claim_ids":["oip-c5"],"link_status":"ok","hash":"oipinvocations0005"}],"prov":{"model":"system/oip_articles","action":"generate"}}