OpenWOP openwop.dev

For host implementers

For host implementers.

You're implementing OpenWOP against a runtime — your own engine, a customer's stack, a managed service you're building. This page tells you what the conformance suite expects, what the advertise-honestly principle costs you, and which reference implementation to mine first.

Read the host capabilities specBrowse profile predicates

The contract in one sentence

A host advertises a set of capabilities at GET /.well-known/openwop, implements the REST endpoints + SSE streams + signed webhooks for the capabilities it claims, and passes the conformance scenarios gated on those capabilities.

Read these first

The advertise-honestly principle

If you advertise a capability, the conformance scenarios for it run against your host, and you must pass them. If you omit it, those scenarios are skipped and you owe nothing.

Do not advertise a capability your host doesn't handle correctly. Leaving out something you can't do yet is the right posture, not a weakness. The same goes for production: claim it only once backpressure, retention, claim acquisition and orphan recovery all hold under test.

The leaderboard at /conformance/ is the public record. A host that overclaims will fail in someone else's CI before it fails for an end user.

What you owe the matrix

  1. 1Adds a row to INTEROP-MATRIX.md.
  2. 2Adds your signed bundle under evidence/v2-host-bundles/, with a conformance.md beside it recording the suite version, command line, target URL class, and pass / fail / blocked / inapplicable / skipped counts.
  3. 3Lists the profiles you claim and the ones you explicitly don't (OPENWOP_OPTED_OUT_PROFILES, so the bundle records the opt-out).

The full guide

Everything on this page, in order, with every link.

The contract in one sentence

A host advertises a set of capabilities at GET /.well-known/openwop, implements the REST endpoints + SSE streams + signed webhooks for the capabilities it claims, and passes the conformance scenarios gated on those capabilities. Anything you don't claim, you don't have to implement.

Read these first

  • Capabilities — the advertisement shape. A host that supports a feature advertises a record for it; a host that doesn't, omits it.
  • Profiles — the named capability bundles a host can claim. Each profile is a predicate over /.well-known/openwop plus a set of conformance scenarios.
  • REST endpoints — every endpoint with request/response shapes and the canonical error codes.

The advertise-honestly principle

If you advertise a capability, the conformance scenarios for it run against your host, and you must pass them. If you omit it, those scenarios are skipped and you owe nothing.

Do not advertise a capability your host doesn't handle correctly. Leaving out something you can't do yet is the right posture, not a weakness. The same goes for production: claim it only once backpressure, retention, claim acquisition and orphan recovery all hold under test.

The leaderboard at /conformance/ is the public record. A host that overclaims will fail in someone else's CI before it fails for an end user.

Start from a reference host

Mine examples/hosts/v2-reference/ in openwop/openwop-examples. It was written directly from the v2 spec and certifies all three v2 profiles. Its conformance.md records which profiles it claims and its latest results.

For a step-by-step path, start from docs/IMPLEMENT-CORE.md.

Run the conformance suite

The conformance suite is published as @openwop/openwop-conformance on npm, with its exact-pinned contract peer @openwop/spec-artifacts at the same version — install both together. Point it at your host:

npm install --legacy-peer-deps @openwop/openwop-conformance@<version> @openwop/spec-artifacts@<version>
npx @openwop/openwop-conformance --base-url https://my-host.example.com --api-key … \
  --target-major 2 --require-behavior

--target-major 2 runs the v2 scenarios. --require-behavior is strict mode: an advertised behaviour that can't be observed fails instead of being skipped. Scenarios only run for the capabilities your host advertises. The leaderboard wants a signed bundle (--certify bundle-v3.json) plus a conformance.md recording the run.

Common implementation surfaces

  • Event log + suspend/resume: see Storage adapters.
  • BYOK secret resolution: see Auth and the secret-leakage threat model.
  • Signed webhooks: see Webhooks; the HMAC recipe is HMAC-SHA256({timestamp}.{rawBody}).
  • Interrupts: see Interrupts for the nine v2 kinds and the shared resolve contract.
  • OAuth-granted credentials for connector nodes: see OAuth — the host as an OAuth client, and the credentials family.

What you owe the matrix

When you ship an OpenWOP host (your own or for a customer), open a PR that:

  1. Adds a row to INTEROP-MATRIX.md.
  2. Adds your signed bundle under evidence/v2-host-bundles/, with a conformance.md beside it recording the suite version, command line, target URL class, and pass / fail / blocked / inapplicable / skipped counts.
  3. Lists the profiles you claim and the ones you explicitly don't (OPENWOP_OPTED_OUT_PROFILES, so the bundle records the opt-out).

The leaderboard rebuilds automatically. A claim counts as certified only when the bundle shows every required check for that profile passing, and CI re-verifies the bundle. Describing it honestly in your row is still on you.

Get on the board.