JSON Schema
Machine-readable schemas for validating OpenBindings documents. Use these in your editor or CI pipeline.
OpenBindings Interface
JSON Schema 2020-12 definition for OBI documents. Validates the root structure, operations, schemas, sources, bindings, and transforms.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://openbindings.com/schema/openbindings-0.1.0.json",
"title": "OpenBindings Interface Document (v0.1.0)",
"description": "Canonical JSON Schema for the OpenBindings interface document.",
"type": "object",
"required": [
"openbindings",
"operations"
],
"properties": {
"openbindings": {
"type": "string",
"description": "OpenBindings document format version (e.g., 0.1.0)."
},
"name": {
"type": "string",
"description": "Human-friendly interface name."
},
"version": {
"type": "string",
"description": "Author-chosen label for the interface contract version. Not an identifier; does not participate in compatibility checking."
},
"description": {
"type": "string",
"description": "Human-readable description of the interface."
},
"schemas": {
"type": "object",
"description": "Named JSON Schemas referenced by operations.",
"additionalProperties": {
"$ref": "#/$defs/JSONSchema"
}
},
"operations": {
"type": "object",
"description": "Operation registry keyed by operation name.",
"additionalProperties": {
"$ref": "#/$defs/Operation"
}
},
"roles": {
"type": "object",
"description": "Interfaces this document intends to satisfy, mapping local aliases to URLs/paths of other OpenBindings interfaces.",
"additionalProperties": {
"type": "string"
}
},
"sources": {
"type": "object",
"description": "Registry of binding artifacts (e.g., OpenAPI/AsyncAPI/proto).",
"additionalProperties": {
"$ref": "#/$defs/Source"
}
},
"bindings": {
"type": "object",
"description": "Binding entries keyed by binding name, mapping operations to binding sources.",
"additionalProperties": {
"$ref": "#/$defs/BindingEntry"
}
},
"security": {
"type": "object",
"description": "Named security entries. Each entry is an array of security methods in preference order (first = preferred). Bindings reference these by key.",
"additionalProperties": {
"type": "array",
"items": {
"$ref": "#/$defs/SecurityMethod"
}
}
},
"transforms": {
"type": "object",
"description": "Named transforms that can be referenced by bindings.",
"additionalProperties": {
"$ref": "#/$defs/Transform"
}
}
},
"additionalProperties": true,
"$defs": {
"JSONSchema": {
"type": "object",
"description": "JSON Schema object (dialect defined by the OpenBindings spec).",
"additionalProperties": true
},
"Operation": {
"type": "object",
"properties": {
"description": {
"type": "string",
"description": "Human-readable description of the operation."
},
"deprecated": {
"type": "boolean",
"description": "Whether the operation is deprecated."
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Organizational labels for grouping and filtering."
},
"aliases": {
"type": "array",
"description": "Alternate names for matching compatibility.",
"items": {
"type": "string"
}
},
"satisfies": {
"type": "array",
"description": "Explicit mappings to operations in other interfaces.",
"items": {
"$ref": "#/$defs/Satisfies"
}
},
"idempotent": {
"type": "boolean",
"description": "Whether the operation is idempotent (safe to retry)."
},
"input": {
"oneOf": [
{ "$ref": "#/$defs/JSONSchema" },
{ "type": "null" }
],
"description": "Input schema. Null or absent means unspecified."
},
"output": {
"oneOf": [
{ "$ref": "#/$defs/JSONSchema" },
{ "type": "null" }
],
"description": "Output schema. Null or absent means unspecified."
},
"examples": {
"type": "object",
"description": "Named examples for this operation.",
"additionalProperties": {
"$ref": "#/$defs/OperationExample"
}
}
},
"additionalProperties": true
},
"OperationExample": {
"type": "object",
"description": "An example input/output pair for an operation.",
"properties": {
"description": {
"type": "string",
"description": "Human-readable description of this example."
},
"input": {
"description": "Example input value (must validate against input schema)."
},
"output": {
"description": "Example output value (must validate against output schema)."
}
},
"additionalProperties": true
},
"Satisfies": {
"type": "object",
"required": [
"role",
"operation"
],
"properties": {
"role": {
"type": "string",
"description": "Role key referencing an entry in the document's roles map."
},
"operation": {
"type": "string",
"description": "Operation key or alias within the role's interface."
}
},
"additionalProperties": true
},
"Source": {
"type": "object",
"required": [
"format"
],
"anyOf": [
{ "required": ["location"] },
{ "required": ["content"] }
],
"properties": {
"format": {
"type": "string",
"description": "Binding format token (e.g., openapi@3.1)."
},
"location": {
"type": "string",
"description": "URI or path to the binding specification."
},
"content": {
"oneOf": [
{ "type": "object" },
{ "type": "string" }
],
"description": "Binding specification content, embedded directly. Object for JSON-based formats, string for text formats (e.g. KDL, protobuf). If both location and content are present, implementations MUST prefer content."
},
"description": {
"type": "string",
"description": "Human-readable description of this binding source."
},
"priority": {
"type": "number",
"description": "Default priority for all bindings referencing this source. Lower values are more preferred. Binding-level priority overrides this value."
}
},
"additionalProperties": true
},
"BindingEntry": {
"type": "object",
"required": [
"operation",
"source"
],
"properties": {
"operation": {
"type": "string",
"description": "Operation key referenced by this binding."
},
"source": {
"type": "string",
"description": "Binding source key from sources."
},
"ref": {
"type": "string",
"description": "Pointer into the binding artifact."
},
"priority": {
"type": "number",
"description": "Relative binding preference (lower is more preferred)."
},
"description": {
"type": "string",
"description": "Human-readable description of this binding."
},
"deprecated": {
"type": "boolean",
"description": "If true, this binding is deprecated and an alternative should be preferred."
},
"security": {
"type": "string",
"description": "Key referencing an entry in the document's security map. Indicates the security requirements for this binding."
},
"inputTransform": {
"$ref": "#/$defs/TransformOrRef",
"description": "Transform from operation input schema to binding input structure."
},
"outputTransform": {
"$ref": "#/$defs/TransformOrRef",
"description": "Transform from binding output structure to operation output schema."
}
},
"additionalProperties": true
},
"SecurityMethod": {
"type": "object",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"description": "Security method type identifier (e.g., 'bearer', 'oauth2', 'basic', 'apiKey'). Unknown types SHOULD be skipped by clients."
},
"description": {
"type": "string",
"description": "Human-readable description or hint for the client UI."
},
"authorizeUrl": {
"type": "string",
"description": "OAuth2 authorization endpoint URL. Required for type 'oauth2'."
},
"tokenUrl": {
"type": "string",
"description": "OAuth2 token endpoint URL. Required for type 'oauth2'."
},
"scopes": {
"type": "array",
"items": { "type": "string" },
"description": "Available OAuth2 scopes."
},
"clientId": {
"type": "string",
"description": "For type 'oauth2': optional client identifier. Servers MAY use a default."
},
"name": {
"type": "string",
"description": "For type 'apiKey': the name of the header, query parameter, or cookie."
},
"in": {
"type": "string",
"enum": ["header", "query", "cookie"],
"description": "For type 'apiKey': where the key is sent."
}
},
"additionalProperties": true,
"description": "A security method declaration. Discriminated on the 'type' field. Well-known types: 'bearer', 'oauth2', 'basic', 'apiKey'. Clients that encounter an unknown type SHOULD skip it and try the next method in the array."
},
"Transform": {
"type": "object",
"required": [
"type",
"expression"
],
"properties": {
"type": {
"type": "string",
"description": "Transform language identifier (e.g., 'jsonata')."
},
"expression": {
"type": "string",
"description": "Transform expression in the specified language."
}
},
"additionalProperties": true
},
"TransformOrRef": {
"oneOf": [
{
"$ref": "#/$defs/Transform"
},
{
"type": "object",
"required": ["$ref"],
"properties": {
"$ref": {
"type": "string",
"description": "JSON Pointer reference to a named transform (e.g., '#/transforms/myTransform')."
}
},
"additionalProperties": false
}
],
"description": "Either an inline transform definition or a reference to a named transform."
}
}
}Operation Graph Format
JSON Schema for the native operation graph format, which defines graph-based operation orchestration.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://openbindings.com/schema/openbindings.operation-graph-0.1.0.json",
"title": "OpenBindings OperationGraph Source Document (v0.1.0)",
"description": "JSON Schema for openbindings.operation-graph binding source documents. Companion to the OpenBindings Specification.",
"type": "object",
"required": [
"openbindings.operation-graph",
"graphs"
],
"properties": {
"openbindings.operation-graph": {
"type": "string",
"pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
"description": "Operation graph format version (semver, e.g., 0.1.0)."
},
"graphs": {
"type": "object",
"description": "Named operation graphs, each defining a node graph.",
"additionalProperties": {
"$ref": "#/$defs/OperationGraph"
}
}
},
"patternProperties": { "^x-": {} },
"additionalProperties": false,
"$defs": {
"OperationGraph": {
"type": "object",
"description": "A named operation graph defining a directed graph of typed nodes connected by edges.",
"required": [
"nodes",
"edges"
],
"properties": {
"description": {
"type": "string",
"description": "A human-readable description of what the operation graph does."
},
"nodes": {
"type": "object",
"description": "Map of named nodes. Each key is a node identifier.",
"additionalProperties": {
"$ref": "#/$defs/Node"
}
},
"edges": {
"type": "array",
"description": "Array of edges connecting nodes.",
"items": {
"$ref": "#/$defs/Edge"
}
}
},
"patternProperties": { "^x-": {} },
"additionalProperties": false
},
"Node": {
"type": "object",
"description": "A typed node in an operation graph. The 'type' field determines the node's behavior and valid fields.",
"required": ["type"],
"properties": {
"type": {
"type": "string",
"description": "The node type. Determines behavior and which other fields are valid."
},
"onError": {
"type": "string",
"description": "Node key to route error events to if this node fails. If not set, errors are dropped."
}
},
"allOf": [
{
"if": {
"properties": { "type": { "const": "input" } }
},
"then": {
"properties": {
"type": true,
"onError": true
},
"patternProperties": { "^x-": {} },
"additionalProperties": false
}
},
{
"if": {
"properties": { "type": { "const": "output" } }
},
"then": {
"properties": {
"type": true,
"onError": true
},
"patternProperties": { "^x-": {} },
"additionalProperties": false
}
},
{
"if": {
"properties": { "type": { "const": "operation" } }
},
"then": {
"required": ["operation"],
"properties": {
"type": true,
"onError": true,
"operation": {
"type": "string",
"description": "Operation key in the containing OBI to invoke."
},
"maxIterations": {
"type": "integer",
"minimum": 1,
"description": "Maximum times this node may be invoked per event lineage. Required if the node is part of a cycle."
},
"timeout": {
"type": "integer",
"minimum": 1,
"description": "Maximum time in milliseconds to wait for the operation to complete."
}
},
"patternProperties": { "^x-": {} },
"additionalProperties": false
}
},
{
"if": {
"properties": { "type": { "const": "buffer" } }
},
"then": {
"properties": {
"type": true,
"onError": true,
"limit": {
"type": "integer",
"minimum": 1,
"description": "Flush after accumulating this many events. Resets and continues (windowing)."
},
"until": {
"type": "object",
"description": "JSON Schema. Flush when an event matches (exclusive — matching event not included and dropped)."
},
"through": {
"type": "object",
"description": "JSON Schema. Flush when an event matches (inclusive — matching event is included)."
}
},
"not": {
"required": ["until", "through"]
},
"patternProperties": { "^x-": {} },
"additionalProperties": false
}
},
{
"if": {
"properties": { "type": { "const": "filter" } }
},
"then": {
"oneOf": [
{
"required": ["schema"],
"properties": {
"type": true,
"onError": true,
"schema": {
"type": "object",
"description": "JSON Schema. Events that validate pass; others are dropped."
}
},
"patternProperties": { "^x-": {} },
"additionalProperties": false
},
{
"required": ["transform"],
"properties": {
"type": true,
"onError": true,
"transform": {
"$ref": "#/$defs/Transform",
"description": "Transform expression. Events where the expression evaluates truthy pass; others are dropped."
}
},
"patternProperties": { "^x-": {} },
"additionalProperties": false
}
]
}
},
{
"if": {
"properties": { "type": { "const": "transform" } }
},
"then": {
"required": ["transform"],
"properties": {
"type": true,
"onError": true,
"transform": {
"$ref": "#/$defs/Transform",
"description": "Transform expression. The result replaces the event."
}
},
"patternProperties": { "^x-": {} },
"additionalProperties": false
}
},
{
"if": {
"properties": { "type": { "const": "map" } }
},
"then": {
"required": ["transform"],
"properties": {
"type": true,
"onError": true,
"transform": {
"$ref": "#/$defs/Transform",
"description": "Transform expression. The result MUST be an array; each element is emitted as a separate event."
}
},
"patternProperties": { "^x-": {} },
"additionalProperties": false
}
},
{
"if": {
"properties": { "type": { "const": "combine" } }
},
"then": {
"properties": {
"type": true,
"onError": true
},
"patternProperties": { "^x-": {} },
"additionalProperties": false
}
},
{
"if": {
"properties": { "type": { "const": "exit" } }
},
"then": {
"properties": {
"type": true,
"onError": true,
"error": {
"type": "boolean",
"description": "If true, the operation graph terminates with an error. If false (default), the event is emitted to output before termination."
}
},
"patternProperties": { "^x-": {} },
"additionalProperties": false
}
}
]
},
"Edge": {
"type": "object",
"description": "A connection between two nodes. Edges carry no logic.",
"required": ["from", "to"],
"properties": {
"from": {
"type": "string",
"description": "The key of the source node."
},
"to": {
"type": "string",
"description": "The key of the target node."
}
},
"patternProperties": { "^x-": {} },
"additionalProperties": false
},
"Transform": {
"type": "object",
"description": "A transform expression using the core OpenBindings Transform model.",
"required": ["type", "expression"],
"properties": {
"type": {
"type": "string",
"description": "Transform language identifier (e.g., jsonata)."
},
"expression": {
"type": "string",
"description": "The transform expression string."
}
},
"patternProperties": { "^x-": {} },
"additionalProperties": false
}
}
}
Usage
VS Code
Add to your .vscode/settings.json to get validation in .obi.json files:
{
"json.schemas": [
{
"url": "https://openbindings.com/openbindings.schema.json",
"fileMatch": ["*.obi.json"]
}
]
}Direct download
The schemas are also available directly from the spec repository.