SODL

Boundaries

This is not a better DSL.

A tool whose pitch is don’t assume, prove it does not get to be vague about itself. So this page states what SODL is not, what it cannot do, which formats it will and will not claim, and exactly where it stands today.

If any of it rules you out, you have saved a week — and we would rather you found out here than three sprints into an adoption.

Compared honestly

What a test framework does, and where SODL differs

A better authoring language would still be a test engine. The difference is the step before authoring: a model derived from the contract, which gives SODL a denominator no test engine has.

Question A test framework SODL
Where does the model of the API come from? The test file. You describe the call; the tool executes your description. The wire contract, re-derived on every run.
What happens when the contract moves? The test still runs, and fails — or worse, passes against a stale belief. The scenario stops compiling, before anything executes.
What does it not know about? Nothing it can name. There is no denominator. It names the operations, entities and lifecycle states nothing exercises.
Can it fail a deploy for an uncovered change? No. Only covered paths can fail. Yes — contracts are diffed, not just tests.
What survives the run? A report, usually until the next build. An immutable, contract-anchored record.
Where a test framework is the right answer. If your service has no published contract, if the thing you are checking is a single function, or if the risk you are managing is a rendering or a latency question — use the tool built for that. SODL earns its place where a workflow spans services or takes time to settle, and nowhere else.

Scope

What SODL is not

Not a UI testing tool

It verifies systems through their APIs. There is no browser, no selector, no screenshot diffing.

Not a load testing tool

It answers “is this correct?”, not “how fast, at what concurrency?”

Not a unit test framework

It runs against real, running services. Your unit tests keep their job.

Contract formats

Two lists, because “we read it” and “we claim it” are different promises

Conflating them is how adoptions go wrong mid-flight. SODL only claims a format when every verification-relevant element is fully modelled — no surprises later.

Claimed

Verification-relevant elements fully modelled.

  • gRPC / protobuf
  • OpenAPI 3.0
  • Swagger 2.0

Also read

Accepted and normalised. Constructs beyond the modelled subset become explicit representation gaps rather than guessed semantics.

  • OpenAPI 3.1

Refused

Refused honestly, with teaching — never guessed over.

  • Swagger 1.x — a multi-file 2011-era format that cannot be translated from a single document; the error names converters
  • Any other major version

Status — stated 1 August 2026

Exactly what is claimable today

SODL is pre-V1, distributed as an internal release with an anonymous install script — no credentials needed to install it. All five capabilities work today and can be demonstrated end to end.

Three things stand between that and a V1 call

  1. Validation on a real cluster outside this project’s own repository. This is a deliberate bar: a tool whose pitch is “prove it” should not declare itself proven on its own fixtures.
  2. Scenario-corpus analysis — derived facts about the tests themselves (outlier failures, redundancy, flakiness by digest). Designed, not built.
  3. Non-JSON response bodies — download, render and raw endpoints currently fail at decode.

Deliberately not in V1

  • Async — AsyncAPI-declared correlation, server-streaming execution, inbound webhooks and callbacks. These are one missing concept, “the system emits to you”, and are being treated as a single arc rather than three patches.
  • parallel execution. The word is reserved and refused honestly today; making it work touches evidence ordering.
  • Walking list and search response bodies, which currently leaves some collection operations unobservable.
  • Hosted tier, scheduled runs, cross-org registries. Designed, not built.
Versions are never reused. Releases are named 0.1.0-internal.<n> while SODL is in internal trials. If you were handed internal.34, that build is internal.34 forever, and the release notes name the source commit it was built from. The releases page always names the current one.

Known issue, if you are holding 0.1.0-internal.34

sodl analyze could write an assumptions.yaml that the engine then refused, which broke every subsequent command on that project until the file was deleted by hand. It triggered on projects composing more than one contract provider. Fixed after that release — take a fresh build, or delete assumptions.yaml if you hit it.

Reporting something

A claim you could not verify is the most useful thing you can send back

More useful than a feature request, and considerably more useful than praise. If SODL asserted something and you could not reproduce it, that is a defect in the one thing this product sells.

Include three things

  • The output of sodl version
  • The command you ran, and what you expected instead
  • The run record from .sodl/runs/, if there is one — it is the evidence, and it is what makes a report actionable
Open an issue Get started