Contracts & data

When to use Contract Studio

Use contracts when a line on the diagram needs a shared explanation. For example: which web request is being made, which event is being published, or which information a service reads from a database. Contracts make reviews clearer without changing how a simulation runs.

A schema describes one data shape. An API operation describes a method, path, inputs, and responses tied to a graph boundary. An OpenAPI specification packages those HTTP operations and schemas for review and downstream tooling. They are related, but not interchangeable.

The six Contract Studio views

Protocol contracts

Describe important web requests, messages, and data operations in words people can review together.

Data resources

Name the tables, collections, caches, or business records that appear in the system story.

Schemas

Inspect and edit the stored JSON Schema bodies shared by operations, resources, component outputs, and exports.

Component outputs

Optionally attach a shared schema to an executable output port, or infer one from a JSON example. This changes contract metadata, not the connection or simulation.

Gap report

Highlights important parts of the diagram that still need a description or an agreed link.

Export

Choose an immutable checkpoint, pin the reviewed contract to it, and download the standards artifacts.

Describe an HTTP API

An HTTP operation ties a method and path to the component and handler that serve it. Define the request/response connections and handler behavior in Design first; adding a contract does not deploy an endpoint or create those connections for you.

1. 1Open Contracts → Protocol contracts. In Operation, enter POST /orders. Choose the component under Served by.
2. 2If that component has several request inputs, select the correct Request port. It determines the arrival handler and response routes; Graphrun does not silently choose between them.
3. 3Optionally paste neutral JSON into Request body example (optional). Review the Derived schema, then choose Add operation. The schema is stored in the shared catalog and linked to the request body.
4. 4Select the saved operation to review and edit its detailed fields: parameters, body schema IDs, responses, authentication metadata, idempotency, and linked examples. To create a new operation with those details from the start, use Add with full details instead as an alternative to quick add.

Quick add accepts GET, POST, PUT, PATCH, DELETE, HEAD, and OPTIONS. A path without a method defaults to GET. Both /orders/:id and /orders/{id} become the OpenAPI path template /orders/{id}, with a required string path parameter. Add query parameters in the detailed form, not as a query string in the route. Review derived response codes, visibility, and retry-safety defaults; they are model metadata, not observations of a live API.

Request and response Body schema ID fields refer to stored schemas. Select a catalog schema for each response that has a body, or leave No body schema where appropriate. A schema ID is a link, not the JSON Schema body itself.

Create and reuse JSON Schemas

A schema describes the shape of data, not an API route or a database table. The shared schema catalog can describe request bodies, responses, message payloads, data-resource keys and records, and component outputs. You do not need to invent a data resource just to store a request schema.

1. 1Create a schema from a request-body example in quick add, or infer one from an example in Component outputs. The Schemas view lists stored schemas; it is not a whole-file uploader or an Add schema form.
2. 2Open Schemas, select an entry, and choose Edit schema. Edit its Schema JSON body, then choose Save schema. The editor validates it before updating the shared contract draft; wait for autosave.
3. 3Reuse its schema ID in other operations or outputs. The ID and version stay unchanged when you edit the body, so every reference to that entry uses the revised shape in the draft. Already approved snapshots retain their original schema bytes.

{
  "productId": "sku-42",
  "quantity": 2
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "productId": {
      "type": "string"
    },
    "quantity": {
      "type": "integer"
    }
  },
  "required": [
    "productId",
    "quantity"
  ],
  "additionalProperties": false
}

Inference is a starting point: every observed object property becomes required, extra properties are disallowed, and only the first array item determines the item schema. Empty arrays do not establish an item shape. Review optional fields, nullable values, arrays, formats, and constraints before approval. A single example cannot establish your whole API contract.

What each contract records

Contract Studio keeps the contract draft separate from the graph. A saved operation describes a boundary and points back to the component, port, handler, and edges that implement it. Saving this metadata does not change runtime behavior.

Define a data resource

For a Database configured with Atomic batch, use a data operation with operation: write and transactional: atomic_batch, targeting database.writeIn and its matching request and writtenOut result connection. The resource must be one table or collection that declares write. Single writes normally use not_required. General transactions remain unsupported; an atomic batch does not imply guarantees across calls or collections.

Open Data resources, select Add, and save the resource before adding a data operation that uses it. Resources are versioned descriptions; removing one is disabled while a data operation still uses it.

Example: model orders as a table with version 1.0.0, a key schema schema.order-id, a record schema schema.order, operations read and write, and internal classification. Then bind a service's read port to a data operation that selects this resource.

Link an operation to the graph

The target section is where a contract becomes useful for review. Pick the component first; the editor then offers only compatible ports, handlers, and edges. HTTP responses must use response edges and error responses must use error edges. Message acknowledgements and dead-letter routes are selected separately. Data operations select their result targets rather than inventing a new resource.

If a target is missing, return to Design and add the connection or handler. A contract draft cannot make an unconnected port executable, and it cannot delete or rewrite the graph when you save it.

Add useful detail

1. 1Save the diagram, then open Contracts in the workbench.
2. 2Choose the kind of communication you want to describe: a web request, a message, or a data operation.
3. 3Link it to the relevant components and connection, then add only the information your reviewers need.
4. 4Open Gap report and work through the items that matter for this review.

What the OpenAPI specification contains

Graphrun exports OpenAPI 3.2.0 from authored HTTP operations, not from every connection on the canvas. Methods and paths become operations; parameters, request content types, response status codes, and schema references come from your contract. The stored schema bodies and their dependencies appear under components.schemas. Graph targets and source provenance remain in x-mockflow-* extensions for traceability.

openapi: 3.2.0
info:
  title: Orders API
  version: 1.0.0
paths:
  /orders:
    post:
      operationId: createOrder
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrder'
      responses:
        '201':
          description: Order created
components:
  schemas:
    CreateOrder:
      type: object
      properties:
        productId:
          type: string
        quantity:
          type: integer
      required: [productId, quantity]
      additionalProperties: false

openapi: 3.2.0 identifies the specification version; info.version identifies the API document version. Graphrun defaults the latter to contract-draft.<revision>. See the OpenAPI 3.2 specification for the standard itself. Graphrun only exports fields supported by its contract model; supporting OpenAPI 3.2 does not mean every feature in the standard has an editor control.

Per contract owner is the default packaging: one YAML/JSON pair per serving component, with a manifest in a ZIP. Use it when different services expose the same method and path. Combined document creates one diagram-wide spec; duplicate method/path pairs across owners can make that option unavailable. Collisions within a single owner still need correction.

There is no whole-file OpenAPI import or automatic round-trip sync in the current UI. Author contracts in Graphrun or through an authorized MCP client, then export a reviewed snapshot. Generating a specification does not deploy the API, generate its implementation, or enforce request validation in the simulation.

Approve and export a contract

Contract approval is a web-only review action. An MCP client may author the draft and its schemas, but it cannot publish a contract snapshot. Authorized MCP readers can read existing approved artifacts; they cannot approve a new export.

OpenAPI describes HTTP APIs; AsyncAPI describes messaging contracts; the JSON Schema bundle carries reusable shapes; Arazzo describes a supported journey workflow and depends on OpenAPI. The formats are checked separately, so choose the artifacts you actually need.

1. 1Save the graph and contract draft, then create the immutable checkpoint you want to export.
2. 2Open Contracts, choose Export, and select the source checkpoint. Choose one or more available formats; unavailable formats show the reason they cannot be generated.
3. 3For OpenAPI, choose Per contract owner for a ZIP of owner-specific YAML and JSON files, or Combined document for a diagram-wide document when available. Select Approve and publish; the button also shows the number of selected formats.
4. 4Download the approved OpenAPI 3.2, AsyncAPI 3.1, Arazzo 1.1, or JSON Schema bundle artifact. OpenAPI, AsyncAPI, and Arazzo are available as YAML or JSON; the JSON Schema bundle is JSON. Authorized MCP readers receive those same approved bytes.

Approval combines the current saved contract draft with the selected immutable graph checkpoint. It does not load an old contract merely because you choose an older checkpoint. The resulting snapshot pins its sources and bytes, including the schema bundle used for export. Later draft edits do not rewrite previous downloads; approve a new snapshot when the contract changes.

Keep sensitive detail out

Describe shapes and meaning, not live secrets. Do not paste passwords, access keys, customer records, private source code, or production payloads into Contract Studio. Use neutral examples when an example is helpful.