Contracts and operations

Contract boundary

Model many related operations inside one integration version.

Use one contract version for the related endpoint, response, event, and message schemas implemented by one integration. A request and response on the same route are separate operations because they have different payload locations and can have different schemas. Unrelated providers or workflows remain separate integrations.

• One integration can have many immutable contract versions.
• One contract version can have many operation schemas.
• One operation identifies one request, response, webhook message, scheduled-feed message, or queue message schema.
• Expected-outcome rules remain separate from structural contracts. They describe the business result that should follow an accepted source event.

Choose an import format

Use OpenAPI for many operations or JSON Schema for one operation.

Choose OpenAPI document when one document describes several supported operations. Seamward extracts JSON request bodies, JSON responses, and OpenAPI webhooks. Choose JSON Schema for one operation when you want to bind one schema to a route or event explicitly.

• OpenAPI accepts JSON or YAML and imports supported application/json or application/*+json schemas for GET, POST, PUT, PATCH, and DELETE operations.
• Each OpenAPI request and each response status selector becomes a separate operation. A 201 response and a 2XX response can therefore carry different schemas.
• OpenAPI webhooks use their webhook name as the event type unless x-seamward-event-type is present. x-seamward-route-template can supply the stable route template.
• JSON Schema registers exactly one operation and requires its route template, payload location, and any applicable method, event type, or response status selector.

Operation identity

See the fields Seamward uses to select a schema.

An operationKey is the stable identity Seamward stores for one operation. Matching considers the integration direction and protocol, then the method, route template, event type, payload location, and response status selector supplied by the contract and observation.

Use route templates such as /customers/{customerId} instead of concrete URLs such as /customers/123. Stable identities keep observations for the same operation together and prevent high-cardinality paths from creating artificial operations.

• Payload location is request, response, or message.
• Status selectors can be exact, such as 201, a class such as 2XX, or default.
• Event type distinguishes webhook, scheduled-feed, and queue messages when several events share transport details.

Register a version

Import a contract from the integration Contracts tab.

1. Open Integrations, select the integration, then open the Contracts tab.
2. Click Register contract or Register new version.
3. Enter a unique contract version. The version label cannot be reused for the same integration.
4. Choose OpenAPI document and paste the JSON or YAML document, or choose JSON Schema for one operation and complete the operation identity fields.
5. Click Register contract. Seamward stores an immutable Draft version and its extracted operations, then records an audit event. Existing analysis does not change.
6. Review the version card and use View schema to inspect each registered operation.
7. Click Activate version when the draft is correct. Activation records a revision and queues integration analysis atomically.

Version lifecycle

Understand immutable versions, Current status, and planned controls.

Registration creates a Draft and never changes the active analysis context. An owner or admin explicitly activates a reviewed draft. The former active version becomes Previous and remains immutable.

Activation uses the active version that the reviewer saw as an optimistic concurrency precondition. If that state changed, Seamward rejects the request instead of replacing another deployment's version. Rolling back reactivates the exact prior immutable version and records a new revision.

Comparison behaviour

Know when Seamward uses a declared schema or observed evidence.

When an observation matches a registered operation, Seamward compares its collector-derived shape with that operation's schema. Required fields, unexpected fields, and primitive type differences can produce structural findings.

When no registered operation matches, Seamward keeps that traffic in an explicitly attributed observed-baseline group instead of comparing it with an unrelated schema. Registered comparisons persist the exact contract version, activation revision, operation, match reason, and bounded observation references. Ambiguous selectors are not silently treated as a match.

• Drift detectionReview structural findings and observed-baseline behaviour.
• Expected outcomesDefine the business result expected after an accepted source event.