Contracts & data
A diagram shows which parts of a system communicate. Contract Studio adds the useful detail: what a request means, what a message announces, and what information a data store holds.
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.
You do not need contracts for a first diagram. Add them when the team needs agreement about an important boundary.
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.
- 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.
- Implementation
- Optionally record where an approved component is implemented or deployed, so reviewers can follow up with the right owner.
- 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.
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.
| Operation | Main fields | Diagram target |
|---|---|---|
| HTTP | Contract key and version, API resource key, operation key, visibility, name, description, method, path, parameters, optional request body schema/content types/examples, success and error responses, auth, idempotency, and retry safety. | A component, request input, arrival handler, and the matching request/response/error edges. |
| Message | Channel key, operation key and version, producer or consumer direction, channel address, message and header schema IDs, correlation fields, delivery mode, ordering, acknowledgement, retry owner, dead-letter channel, auth, and visibility. | A component and message edge, with acknowledgement, error, and optional dead-letter edges. |
| Data | Resource and resource version, action (read, write, upsert, or delete), operation key and version, visibility, name, description, consistency, transaction requirement, and retention policy. | A component, data request port and handler, plus result and error edges. The selected resource supplies the data classification and schemas. |
A green Ready for approval message means the selected operation conforms to the current diagram connections. It does not mean the underlying implementation has been verified.
Define a data resource
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.
| Field | Use it for |
|---|---|
| Identity | Resource ID, version, logical name, optional physical name, and description. |
| Kind | table and collection use a key schema; cache uses a key template, value schema, TTL, and invalidation policy; entity uses identifier schemas, lifecycle states, and resource mappings. |
| Operations | Select one or more of read, write, upsert, and delete. Cache resources cannot use upsert. |
| Schemas | Link a record/key or value schema by ID and version, and optionally record its repository path. The resource form records the link; it is not a source-code or schema-file upload. |
| Classification and semantics | Choose unspecified, public, internal, confidential, or restricted. Mark database semantics portable or list unsupported features such as joins, transactions, triggers, or vendor queries with an explanation. |
| Implementation mapping | Optionally point to a repository, implementation path or symbol, schema file, or migration. This is review metadata, not an executable binding. |
Example: model orders as a table with version1.0.0, a key schema schema.order-id, a record schema schema.order, operationsread and write, andinternal 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.
The Implementation view is optional provenance. A binding can point at a component, port, handler, resource, or contract and can record repository/package/path, symbol, deployment, owner, source ref, and verification state. “Unverified” means Mockflow has recorded the link, not that it has checked the code.
Add useful detail
- Save the diagram, then open Contracts in the workbench.
- Choose the kind of communication you want to describe: a web request, a message, or a data operation.
- Link it to the relevant components and connection, then add only the information your reviewers need.
- Open Gap report and work through the items that matter for this review.
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 or download on your behalf.
- Save the graph and contract draft, then create the immutable checkpoint you want to export.
- Open Contracts, choose Export, select the source checkpoint, then choose Approve and publish contract.
- Download 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.
A checkpoint alone does not create an API contract. Approval is blocked when there are no authored operations, the draft is unsaved or conflicted, gaps remain, or the checkpoint cannot produce every output including Arazzo. Fix the first diagnostic shown in Gap report or the operation form, save, and select the intended checkpoint again.
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.
These docs intentionally do not describe Mockflow's internal document formats or private validation rules. The editor presents the supported fields and checks them for you.