Examples
Reference OBI documents from the specification repository. Each demonstrates a different pattern.
Minimal — Echo Service
The simplest possible OBI: a single operation with one binding. A good starting point for understanding the format.
{
"openbindings": "0.1.0",
"name": "Echo Service",
"version": "1.0.0",
"description": "A minimal OpenBindings interface with a single operation and one binding.",
"operations": {
"echo": {
"description": "Echo a message back unchanged.",
"idempotent": true,
"input": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "The message to echo back"
}
},
"required": ["message"]
},
"output": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
},
"sources": {
"restApi": {
"format": "openapi@3.1",
"location": "./openapi.json"
}
},
"bindings": {
"echo.restApi": {
"operation": "echo",
"source": "restApi",
"ref": "#/paths/~1echo/post"
}
}
}
OpenBlendings
A realistic service with five operations exposed through five different binding specifications: REST (OpenAPI), events (AsyncAPI/SSE), AI tools (MCP), backend RPC (gRPC), and Connect (Buf). Demonstrates the core value proposition — one interface, multiple protocols.
{
"openbindings": "0.1.0",
"name": "OpenBlendings",
"version": "1.0.0",
"description": "A coffee shop with six bindings: REST (OpenAPI), events (AsyncAPI/SSE), AI tools (MCP), internal RPC (gRPC), Connect (Buf), and GraphQL. One interface, six binding specifications.",
"schemas": {
"MenuItem": {
"type": "object",
"properties": {
"id": { "type": "string" },
"name": { "type": "string" },
"description": { "type": "string" },
"sizes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": { "type": "string" },
"price": { "type": "number" }
},
"required": ["label", "price"]
}
}
},
"required": ["id", "name", "sizes"]
},
"Menu": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": { "$ref": "#/schemas/MenuItem" }
}
}
},
"PlaceOrderInput": {
"type": "object",
"properties": {
"drink": { "type": "string", "description": "Menu item ID" },
"size": { "type": "string", "description": "Size label (v1, v2, or v3)" },
"customer": { "type": "string", "description": "Customer name" }
},
"required": ["drink", "size", "customer"]
},
"Order": {
"type": "object",
"properties": {
"id": { "type": "string" },
"drink": { "type": "string" },
"size": { "type": "string" },
"customer": { "type": "string" },
"status": {
"type": "string",
"enum": ["received", "preparing", "ready", "picked_up", "cancelled"]
},
"createdAt": { "type": "string", "format": "date-time" }
},
"required": ["id", "drink", "size", "customer", "status", "createdAt"]
},
"OrderStatusInput": {
"type": "object",
"properties": {
"orderId": { "type": "string" }
},
"required": ["orderId"]
},
"CancelOrderInput": {
"type": "object",
"properties": {
"orderId": { "type": "string" }
},
"required": ["orderId"]
},
"CancelOrderOutput": {
"type": "object",
"properties": {
"success": { "type": "boolean" },
"message": { "type": "string" }
}
},
"OrderUpdate": {
"type": "object",
"properties": {
"orderId": { "type": "string" },
"status": {
"type": "string",
"enum": ["received", "preparing", "ready", "picked_up", "cancelled"]
},
"updatedAt": { "type": "string", "format": "date-time" }
},
"required": ["orderId", "status", "updatedAt"]
}
},
"operations": {
"getMenu": {
"description": "Returns the full menu with drinks, sizes, and prices.",
"idempotent": true,
"output": { "$ref": "#/schemas/Menu" }
},
"placeOrder": {
"description": "Place a new order. Returns the order with its ID and initial status.",
"input": { "$ref": "#/schemas/PlaceOrderInput" },
"output": { "$ref": "#/schemas/Order" }
},
"getOrderStatus": {
"description": "Check the current status of an order by ID.",
"idempotent": true,
"input": { "$ref": "#/schemas/OrderStatusInput" },
"output": { "$ref": "#/schemas/Order" }
},
"cancelOrder": {
"description": "Cancel a pending order. Only works if the order has not started preparation.",
"input": { "$ref": "#/schemas/CancelOrderInput" },
"output": { "$ref": "#/schemas/CancelOrderOutput" }
},
"orderUpdates": {
"description": "Stream of order state transitions. Emitted whenever an order changes status.",
"output": { "$ref": "#/schemas/OrderUpdate" }
}
},
"sources": {
"rest": {
"format": "openapi@3.1",
"location": "https://blend.openbindings.com/openapi.json",
"description": "REST API for the ordering app"
},
"events": {
"format": "asyncapi@3.0",
"location": "https://blend.openbindings.com/asyncapi.json",
"description": "SSE event stream for the barista dashboard"
},
"mcp": {
"format": "mcp@2025-11-25",
"location": "https://blend.openbindings.com/mcp",
"description": "MCP tools for AI assistants"
},
"grpc": {
"format": "grpc",
"location": "blend.openbindings.com:9090",
"description": "gRPC service for backend microservices"
},
"connect": {
"format": "connect",
"location": "https://blend.openbindings.com",
"description": "Connect (Buf) — same protobuf service over HTTP/1.1 + JSON"
},
"graphql": {
"format": "graphql",
"location": "https://blend.openbindings.com/graphql",
"description": "GraphQL API — flexible queries and subscriptions"
}
},
"bindings": {
"getMenu.rest": {
"operation": "getMenu",
"source": "rest",
"ref": "#/paths/~1api~1menu/get"
},
"getMenu.mcp": {
"operation": "getMenu",
"source": "mcp",
"ref": "tools/getMenu"
},
"getMenu.grpc": {
"operation": "getMenu",
"source": "grpc",
"ref": "blend.CoffeeShop/GetMenu"
},
"getMenu.connect": {
"operation": "getMenu",
"source": "connect",
"ref": "blend.CoffeeShop/GetMenu"
},
"placeOrder.rest": {
"operation": "placeOrder",
"source": "rest",
"ref": "#/paths/~1api~1orders/post"
},
"placeOrder.mcp": {
"operation": "placeOrder",
"source": "mcp",
"ref": "tools/placeOrder"
},
"placeOrder.grpc": {
"operation": "placeOrder",
"source": "grpc",
"ref": "blend.CoffeeShop/PlaceOrder"
},
"placeOrder.connect": {
"operation": "placeOrder",
"source": "connect",
"ref": "blend.CoffeeShop/PlaceOrder"
},
"getOrderStatus.rest": {
"operation": "getOrderStatus",
"source": "rest",
"ref": "#/paths/~1api~1orders~1{orderId}/get"
},
"getOrderStatus.mcp": {
"operation": "getOrderStatus",
"source": "mcp",
"ref": "tools/getOrderStatus"
},
"getOrderStatus.grpc": {
"operation": "getOrderStatus",
"source": "grpc",
"ref": "blend.CoffeeShop/GetOrderStatus"
},
"getOrderStatus.connect": {
"operation": "getOrderStatus",
"source": "connect",
"ref": "blend.CoffeeShop/GetOrderStatus"
},
"cancelOrder.rest": {
"operation": "cancelOrder",
"source": "rest",
"ref": "#/paths/~1api~1orders~1{orderId}~1cancel/post"
},
"cancelOrder.mcp": {
"operation": "cancelOrder",
"source": "mcp",
"ref": "tools/cancelOrder"
},
"cancelOrder.grpc": {
"operation": "cancelOrder",
"source": "grpc",
"ref": "blend.CoffeeShop/CancelOrder"
},
"cancelOrder.connect": {
"operation": "cancelOrder",
"source": "connect",
"ref": "blend.CoffeeShop/CancelOrder"
},
"orderUpdates.events": {
"operation": "orderUpdates",
"source": "events",
"ref": "#/operations/onOrderUpdate"
},
"orderUpdates.grpc": {
"operation": "orderUpdates",
"source": "grpc",
"ref": "blend.CoffeeShop/OrderUpdates"
},
"getMenu.graphql": {
"operation": "getMenu",
"source": "graphql",
"ref": "Query/getMenu"
},
"placeOrder.graphql": {
"operation": "placeOrder",
"source": "graphql",
"ref": "Mutation/placeOrder"
},
"getOrderStatus.graphql": {
"operation": "getOrderStatus",
"source": "graphql",
"ref": "Query/getOrderStatus"
},
"cancelOrder.graphql": {
"operation": "cancelOrder",
"source": "graphql",
"ref": "Mutation/cancelOrder"
},
"orderUpdates.graphql": {
"operation": "orderUpdates",
"source": "graphql",
"ref": "Subscription/orderUpdates"
}
}
}
CLI + REST — Bookmark Store
A bookmark manager with every operation bound to both a CLI (via usage spec) and a REST API (via OpenAPI). Same contract, different transports.
{
"openbindings": "0.1.0",
"name": "Bookmark Store",
"version": "1.0.0",
"description": "A bookmark manager accessible as both a CLI tool (via usage spec) and a REST API (via OpenAPI). Every operation has two bindings — same contract, different transports.",
"schemas": {
"Bookmark": {
"type": "object",
"properties": {
"id": { "type": "string" },
"url": { "type": "string", "format": "uri" },
"title": { "type": "string" },
"tags": {
"type": "array",
"items": { "type": "string" }
},
"createdAt": { "type": "string", "format": "date-time" }
},
"required": ["id", "url", "title", "createdAt"]
}
},
"operations": {
"addBookmark": {
"description": "Save a new bookmark.",
"input": {
"type": "object",
"properties": {
"url": { "type": "string", "format": "uri", "description": "URL to bookmark" },
"title": { "type": "string", "description": "Display title" },
"tags": {
"type": "array",
"items": { "type": "string" },
"description": "Tags for organization"
}
},
"required": ["url", "title"]
},
"output": { "$ref": "#/schemas/Bookmark" }
},
"getBookmark": {
"description": "Retrieve a bookmark by ID.",
"idempotent": true,
"input": {
"type": "object",
"properties": {
"id": { "type": "string", "description": "Bookmark ID" }
},
"required": ["id"]
},
"output": { "$ref": "#/schemas/Bookmark" }
},
"listBookmarks": {
"description": "List bookmarks, optionally filtered by tag.",
"idempotent": true,
"input": {
"type": "object",
"properties": {
"tag": { "type": "string", "description": "Filter by tag" }
}
},
"output": {
"type": "object",
"properties": {
"bookmarks": {
"type": "array",
"items": { "$ref": "#/schemas/Bookmark" }
}
}
}
},
"deleteBookmark": {
"description": "Delete a bookmark by ID.",
"input": {
"type": "object",
"properties": {
"id": { "type": "string", "description": "Bookmark ID" }
},
"required": ["id"]
},
"output": {
"type": "object",
"properties": {
"success": { "type": "boolean" }
}
}
}
},
"sources": {
"cli": {
"format": "usage@2.0.0",
"location": "./bookmarks.usage.kdl",
"description": "CLI for terminal users"
},
"rest": {
"format": "openapi@3.1",
"location": "./openapi.json",
"description": "REST API for web and service clients"
}
},
"bindings": {
"addBookmark.cli": {
"operation": "addBookmark",
"source": "cli",
"ref": "add"
},
"addBookmark.rest": {
"operation": "addBookmark",
"source": "rest",
"ref": "#/paths/~1bookmarks/post"
},
"getBookmark.cli": {
"operation": "getBookmark",
"source": "cli",
"ref": "get"
},
"getBookmark.rest": {
"operation": "getBookmark",
"source": "rest",
"ref": "#/paths/~1bookmarks~1{id}/get"
},
"listBookmarks.cli": {
"operation": "listBookmarks",
"source": "cli",
"ref": "list"
},
"listBookmarks.rest": {
"operation": "listBookmarks",
"source": "rest",
"ref": "#/paths/~1bookmarks/get"
},
"deleteBookmark.cli": {
"operation": "deleteBookmark",
"source": "cli",
"ref": "delete"
},
"deleteBookmark.rest": {
"operation": "deleteBookmark",
"source": "rest",
"ref": "#/paths/~1bookmarks~1{id}/delete"
}
}
}
Multi-Source — User Service
A user service available through two OpenAPI sources — a public API and an internal admin API — unified under one interface. Shows how different audiences can access different subsets of the same contract.
{
"openbindings": "0.1.0",
"name": "User Service",
"version": "2.0.0",
"description": "A user service available through two OpenAPI sources — a public API and an internal admin API — unified under one interface.",
"schemas": {
"User": {
"type": "object",
"properties": {
"id": { "type": "string" },
"email": { "type": "string", "format": "email" },
"name": { "type": "string" },
"role": { "type": "string", "enum": ["user", "admin"] },
"createdAt": { "type": "string", "format": "date-time" }
},
"required": ["id", "email", "name", "role"]
},
"GetUserInput": {
"type": "object",
"properties": {
"userId": { "type": "string" }
},
"required": ["userId"]
},
"CreateUserInput": {
"type": "object",
"properties": {
"email": { "type": "string", "format": "email" },
"name": { "type": "string" },
"role": { "type": "string", "enum": ["user", "admin"] }
},
"required": ["email", "name"]
},
"ListUsersOutput": {
"type": "object",
"properties": {
"users": {
"type": "array",
"items": { "$ref": "#/schemas/User" }
}
}
}
},
"operations": {
"getUser": {
"description": "Retrieve a user by ID.",
"idempotent": true,
"input": { "$ref": "#/schemas/GetUserInput" },
"output": { "$ref": "#/schemas/User" }
},
"createUser": {
"description": "Create a new user account.",
"input": { "$ref": "#/schemas/CreateUserInput" },
"output": { "$ref": "#/schemas/User" }
},
"listUsers": {
"description": "List all users. Only available through the admin API.",
"idempotent": true,
"output": { "$ref": "#/schemas/ListUsersOutput" }
}
},
"sources": {
"publicApi": {
"format": "openapi@3.1",
"location": "https://api.example.com/openapi.json",
"description": "Public-facing REST API"
},
"adminApi": {
"format": "openapi@3.1",
"location": "https://admin.example.com/openapi.json",
"description": "Internal admin REST API"
}
},
"bindings": {
"getUser.publicApi": {
"operation": "getUser",
"source": "publicApi",
"ref": "#/paths/~1users~1{userId}/get"
},
"getUser.adminApi": {
"operation": "getUser",
"source": "adminApi",
"ref": "#/paths/~1admin~1users~1{userId}/get"
},
"createUser.publicApi": {
"operation": "createUser",
"source": "publicApi",
"ref": "#/paths/~1users/post"
},
"createUser.adminApi": {
"operation": "createUser",
"source": "adminApi",
"ref": "#/paths/~1admin~1users/post"
},
"listUsers.adminApi": {
"operation": "listUsers",
"source": "adminApi",
"ref": "#/paths/~1admin~1users/get"
}
}
}