jev-oas-sentinel

# JEV OAS Sentinel — System One Semantic Compatibility for OpenAPI

[](https://github.com/ShuhanSun/jev-oas-sentinel/actions/workflows/ci.yml)
[](https://pypi.org/project/jev-oas-sentinel/)
[](https://pypi.org/project/jev-oas-sentinel/)
[](LICENSE)
[](https://github.com/marketplace/actions/jev-oas-sentinel)



Catch behavioral breaking changes hidden in OpenAPI prose—changes that structural schema diff tools cannot see.

`jev-oas-sentinel` compares two OpenAPI documents in two layers:

1. deterministic checks find definite structural compatibility problems;
2. TypeSafe Jev evaluates bounded semantic questions about changed descriptions, examples, defaults, retry behavior, ordering, pagination, authorization, and error semantics.

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.

> [!NOTE]
> JEV OAS Sentinel is an independent community project. It is not affiliated with, maintained by, or endorsed by TypeSafe AI.

## Try it in 30 seconds

No API key or network call to JEV is needed for this preview:



```bash
git clone https://github.com/ShuhanSun/jev-oas-sentinel.git
cd jev-oas-sentinel
uvx jev-oas-sentinel compare \
  --base examples/base-openapi.yaml \
  --head examples/head-openapi.yaml \
  --dry-run \
  --format markdown
```

The example changes an operation's consumer-facing prose. The structural schema remains compatible, but Sentinel identifies the operation that needs semantic review:

```text
| Block | Review | Notice |
|---:|---:|---:|
|0|1|0|

| Severity | Operation | Rule | Finding |
|---|---|---|---|
| review | GET /orders | semantic-evaluation-planned | Contract prose changed and would be sent to JEV |
```

The reproducible [`ben