jev-oas-sentinel
OpenAPI diff tool that adds Jev semantic review of changed prose to deterministic checks, then code decides pass, review or block.
Overview
JEV OAS Sentinel catches behavioural breaking changes hidden in OpenAPI prose that structural schema diff tools cannot see. It compares two OpenAPI documents in two layers: deterministic checks find definite structural incompatibilities, and TypeSafe Jev evaluates bounded semantic questions about changed descriptions, examples, defaults, retry behaviour, ordering, pagination, authorisation and error semantics.
Jev never writes a review or changes the specification; it returns typed decisions with probabilities, and deterministic Python code decides whether to pass, request review or block. It is available as a PyPI CLI and a GitHub Action with SARIF upload, verified in a separate demo repository. A dry-run mode previews which operations would be sent to Jev without a key. The public alpha supports JSON and safe YAML with local multi-file $ref resolution and cycle protection, rejects remote refs, and defaults to advisory mode. A benchmark suite covers ten semantic-only contract changes.
What the decision model decides
| Type | Question | Answers |
|---|---|---|
| Yes / no | Does this prose change alter consumer-visible behaviour (pagination, ordering, retries, auth, errors)?(inferred) | yes · no |
| Choice | How should this change be classified?(inferred) | pass · review · block |
How it works
- Run deterministic structural compatibility checks
- Identify operations with changed consumer-facing prose
- Ask Jev bounded semantic questions about each change
- Code maps results to pass, review or block and emits Markdown or SARIF
Strengths
- Finds breaking changes invisible to schema diffs
- Dry-run preview without an API key
- GitHub Action with SARIF output
- Advisory by default; deterministic final decision
Caveats
- Public alpha
- Remote $ref targets are rejected
- Independent project not affiliated with TypeSafe
Getting started
uvx jev-oas-sentinel compare --base examples/base-openapi.yaml --head examples/head-openapi.yaml --dry-run --format markdownAt a glance
- Type
- Service
- Status
- beta
- Language
- Python
- Runtime
- CLI and GitHub Action
- Has code
- yes
- Has tests
- yes
- License
- Apache-2.0
Use cases and integrations
How curated lists describe it
JEV never writes a review or changes a specification. It returns typed decisions and probabilities; deterministic Python code decides whether to pass, request review, or block.
logicrw/awesome-jev-projectsCatch breaking API behavior hidden in OpenAPI prose with deterministic checks and TypeSafe JEV System One semantic review.
hellogumbo/awesome-jev
Frequently asked questions
What does Jev decide here?
Whether changed OpenAPI prose implies a consumer-visible behaviour change, as typed answers with probabilities.
Does Jev write review comments?
No. Code turns Jev's answers into pass, review or block findings.
Can I try it without a key?
Yes. --dry-run shows what would be sent for semantic review.
Related projects
Rust code-review gate asking Jev small typed questions about functions and tests, failing CI only on rules measured 80% right.
CLIproductionRustJev-first CLI coding agent that routes a request to a deterministic workflow which asks Jev fixed-choice questions about bounded evidence.
ProjectprototypeTypeScriptGives Claude Code, Codex, Pi and OpenCode five typed Jev tools (classify, check, score, rank, ask) plus a skill on when to use them.
MCP serverbetaTypeScriptPlaywright reporter that uses Jev to select end-to-end tests relevant to a code change before browser execution in CI.
ProjectbetaTypeScriptCLI that scores every test against a git diff with Jev and emits filter arguments for vitest, jest, node, Playwright, cargo, go and rspec.
ProjectbetaTypeScriptSix evidence-oriented Jev tools for pi, omp and any MCP client: ask about code, find files, locate ranges, check diffs and select tests.
ServicebetaTypeScript