{"slug": "jev-oas-sentinel-catch-breaking-api-changes-hidden-in-openapi-prose", "title": "JEV OAS Sentinel – catch breaking API changes hidden in OpenAPI prose", "summary": "The independent community project JEV OAS Sentinel released a public alpha tool that compares two OpenAPI documents in two layers: deterministic structural checks plus TypeSafe Jev semantic evaluation of changed descriptions, examples, defaults, retry behavior, ordering, pagination, authorization, and error semantics. The tool returns typed decisions and probabilities rather than writing reviews or changing specifications, with deterministic Python code deciding whether to pass, request review, or block; advisory mode is the default. The project states it is not affiliated with, maintained by, or endorsed by TypeSafe AI, and its benchmarks suite exercises ten semantic-only contract changes.", "body_md": "# JEV OAS Sentinel\n\nActions\n## Tags\n\n(2)\nCatch behavioral breaking changes hidden in OpenAPI prose—changes that structural schema diff tools cannot see.\n\n`jev-oas-sentinel` compares two OpenAPI documents in two layers:\n\n1. deterministic checks find definite structural compatibility problems;\n2. TypeSafe Jev evaluates bounded semantic questions about changed descriptions, examples, defaults, retry behavior, ordering, pagination, authorization, and error semantics.\n\nJEV 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.\n\nNote\n\nJEV OAS Sentinel is an independent community project. It is not affiliated with, maintained by, or endorsed by TypeSafe AI.\n\nNo API key or network call to JEV is needed for this preview:\n\n```\ngit clone https://github.com/ShuhanSun/jev-oas-sentinel.git\ncd jev-oas-sentinel\nuvx jev-oas-sentinel compare \\\n  --base examples/base-openapi.yaml \\\n  --head examples/head-openapi.yaml \\\n  --dry-run \\\n  --format markdown\n```\n\nThe example changes an operation's consumer-facing prose. The structural schema remains compatible, but Sentinel identifies the operation that needs semantic review:\n\n```\n| Block | Review | Notice |\n|---:|---:|---:|\n|0|1|0|\n\n| Severity | Operation | Rule | Finding |\n|---|---|---|---|\n| review | GET /orders | semantic-evaluation-planned | Contract prose changed and would be sent to JEV |\n```\n\nThe reproducible [`benchmarks/`](https://github.com/ShuhanSun/jev-oas-sentinel/blob/main/benchmarks) suite exercises ten semantic-only contract changes covering pagination, ordering, retries, authorization, timestamps, error meaning, and other consumer-visible promises.\nThe independent [`jev-oas-sentinel-demo`](https://github.com/ShuhanSun/jev-oas-sentinel-demo) repository verifies the public `@v0` Action and SARIF upload from a real consumer workflow.\n\nThe current public alpha supports OpenAPI JSON and standards-compliant safe YAML,\nincluding anchors and merge keys. Internal and multi-file local `$ref` targets\nare resolved with cycle protection. Remote `$ref` targets are rejected rather\nthan fetched implicitly. Advisory mode is the default.\n\nLocal references are restricted to the specification's directory tree by default. For repositories that keep shared schemas in a parent directory, set an explicit trusted root:\n\n```\njev-oas-sentinel compare \\\n  --base api/base/openapi.yaml \\\n  --head api/head/openapi.yaml \\\n  --ref-root . \\\n  --no-jev\n```\n\n- [`uv`](https://docs.astral.sh/uv/) for the recommended installation and development workflow\n- Python 3.9+ when running without `uv`\n- A TypeSafe API key for live semantic evaluation\n\nRuntime dependencies are PyYAML for standards-compliant OpenAPI parsing and,\non Python 3.10+, `truststore` for the operating system's native certificate\nstore. Tool installers keep the CLI isolated from system and project Python\nenvironments. Python 3.9 uses its configured OpenSSL CA bundle and can be given\na private bundle explicitly.\n\nRun the published CLI once without installing it:\n\n```\nuvx jev-oas-sentinel --version\n```\n\nOr install it as an isolated command:\n\n```\nuv tool install jev-oas-sentinel\n# or\npipx install jev-oas-sentinel\n```\n\nTo work on the current checkout, install it in editable mode:\n\n```\nuv tool install --editable .\njev-oas-sentinel --version\n```\n\nOn a Mac or corporate network that relies on certificates from the operating-system trust store, add `--system-certs` to the `uv` install command.\n\nManaged installs can be upgraded or removed cleanly with `uv tool upgrade jev-oas-sentinel` and `uv tool uninstall jev-oas-sentinel`.\n\n`./jev-oas-sentinel` remains available as a no-install fallback when working directly in a source checkout.\n\nRun deterministic checks only:\n\n```\njev-oas-sentinel compare \\\n  --base examples/base-openapi.yaml \\\n  --head examples/head-openapi.yaml \\\n  --no-jev \\\n  --format markdown\n```\n\nRun a live Jev evaluation:\n\n```\nexport TYPESAFE_API_KEY=\"...\"\n\njev-oas-sentinel compare \\\n  --base examples/base-openapi.yaml \\\n  --head examples/head-openapi.yaml \\\n  --format markdown\n```\n\nPreview which operations would require JEV without an API key or network call:\n\n```\njev-oas-sentinel compare \\\n  --base examples/base-openapi.yaml \\\n  --head examples/head-openapi.yaml \\\n  --dry-run \\\n  --format json\n```\n\nBound API usage and transport behavior explicitly in CI:\n\n```\n--max-jev-calls 20 --timeout 30 --max-retries 3\n```\n\nPut shared policy in `.jev-sentinel.yaml` at the directory where the command\nruns. The format is versioned, CLI options override file settings, and\n`--config PATH` selects another file. Use `--no-config` for a fully explicit\nrun.\n\n```\nversion: 1\nmode: advisory\nfail_on_review: false\nmodel: jev-1.13.0\nreview_threshold: 0.65\nblock_threshold: 0.90\nmax_jev_calls: 20\ntimeout: 30\nmax_retries: 3\n\nsuppressions:\n  - operation: GET /legacy/*\n    rule: semantic-contract-review\n    expires: 2099-12-31\n    owner: api-platform\n    reason: Migration is tracked in API-123\n```\n\nSuppressions require an owner, reason, and expiration date. A matching block or\nreview becomes a notice but remains in JSON, Markdown, and SARIF with its\noriginal severity and suppression metadata. An expired suppression fails the\nrun so exceptions cannot silently become permanent. Operation and rule values\nsupport shell-style `*`, `?`, and character-set patterns.\n\nFor security, repository configuration cannot set the JEV endpoint, API-key\nfile, CA bundle, local-reference root, report path, or trace path. Those remain\nexplicit CLI options. See [`examples/jev-sentinel.yaml`](https://github.com/ShuhanSun/jev-oas-sentinel/blob/main/examples/jev-sentinel.yaml)\nfor a complete example.\n\nThe client also accepts `--api-key-file PATH`. Never commit that file.\n\nTo inspect the exact JEV input and output, opt in to a sanitized trace:\n\n```\n# Show the trace on stderr while keeping the report on stdout.\njev-oas-sentinel compare \\\n  --base examples/base-openapi.yaml \\\n  --head examples/head-openapi.yaml \\\n  --show-jev-io \\\n  --format markdown\n\n# Or write the trace as JSON.\njev-oas-sentinel compare \\\n  --base examples/base-openapi.yaml \\\n  --head examples/head-openapi.yaml \\\n  --jev-io-output reports/jev-io.json \\\n  --format markdown\n```\n\nThe versioned trace omits request headers and recursively redacts the configured API key plus common credential fields from captured data. Trace files are created with owner-only permissions on POSIX systems. They do include the contract fragments sent to JEV, so treat them as potentially sensitive and do not publish them unintentionally.\n\nOn Python 3.10 and newer, HTTPS verification uses the operating system's native\ncertificate store, including enterprise CAs installed in macOS Keychain or the\nWindows certificate store. For Python 3.9 or a private CA bundle, use\n`--ca-bundle PATH`, `JEV_CA_BUNDLE`, or the standard `SSL_CERT_FILE` environment\nvariable. TLS verification is never disabled.\n\n```\njev-oas-sentinel compare \\\n  --base examples/base-openapi.yaml \\\n  --head examples/head-openapi.yaml \\\n  --ca-bundle /path/to/company-ca.pem \\\n  --format markdown\n```\n\nWrite SARIF for GitHub code scanning:\n\n```\njev-oas-sentinel compare \\\n  --base openapi-base.yaml \\\n  --head src/main/resources/openapi.yaml \\\n  --format sarif \\\n  --output reports/jev-oas-sentinel.sarif\n```\n\nThe repository includes a composite action. A complete pull-request example is available at [`examples/github-workflow.yaml`](https://github.com/ShuhanSun/jev-oas-sentinel/blob/main/examples/github-workflow.yaml).\n\n```\n- uses: ShuhanSun/jev-oas-sentinel@v0\n  with:\n    base: /tmp/openapi-base.yaml\n    head: src/main/resources/openapi.yaml\n    api-key: ${{ secrets.TYPESAFE_API_KEY }}\n    format: sarif\n    output: reports/jev-oas-sentinel.sarif\n```\n\n- `--mode advisory` (default): definite structural breaks block; semantic risks request review.\n- `--mode enforce` : a semantic break blocks only when both the`breaking` probability and promise-violation probability cross conservative thresholds.\n- `--fail-on-review` : return a non-zero exit code for review findings as well as blocks.\n\nThresholds are configurable:\n\n```\n--review-threshold 0.65 --block-threshold 0.90\n```\n\nDo not enable enforcement until the questions and thresholds have been evaluated on representative changes from your own APIs.\n\n- removed operations;\n- removed parameters;\n- new required parameters;\n- optional parameters becoming required;\n- required request bodies being introduced;\n- removed response status codes;\n- removed request or response media types;\n- removed request or response properties;\n- request properties becoming required;\n- response properties no longer being guaranteed;\n- request enum narrowing and response enum expansion;\n- incompatible schema type or nullability changes;\n- security requirement changes;\n- other non-documentation structural changes, conservatively routed to review.\n\nEach changed operation receives one request containing four independent questions:\n\n- change kind: documentation-only, additive, behavioral, breaking, or unclear;\n- affected dimension: defaults, response meaning, ordering/pagination, retry/idempotency, authorization, deprecation, error semantics, or another dimension;\n- whether every old consumer-visible promise remains preserved;\n- ordered migration burden.\n\nThe report retains the selected values, full probability distributions, confidence values, resolved model, token usage, and deterministic source location.\n\n- `0` : no blocking finding (and no review finding when`--fail-on-review` is used);\n- `1` : policy blocked the change;\n- `2` : invalid input or execution failure.\n\n- API keys are read from `TYPESAFE_API_KEY` or an explicit key file and are never included in reports.\n- Only changed operation fragments are sent to Jev.\n- Structural compatibility rules remain deterministic.\n- API errors fail closed in enforcement mode and request review in advisory mode.\n- OpenAPI descriptions are untrusted input. The tool does not execute examples, extensions, URLs, or code found in a specification.\n\nSee [docs/architecture.md](https://github.com/ShuhanSun/jev-oas-sentinel/blob/main/docs/architecture.md) for design boundaries and extension points.\n\n```\nuv sync --locked\nuv run python -m unittest discover -s tests -v\nuv run jev-oas-sentinel --version\nuv build --no-sources\n```\n\nCI runs the tests on Python 3.9, 3.11, and 3.13 and validates both distribution artifacts. See [docs/releasing.md](https://github.com/ShuhanSun/jev-oas-sentinel/blob/main/docs/releasing.md) for the trusted-publishing release process.\n\n- Read [`CONTRIBUTING.md`](https://github.com/ShuhanSun/jev-oas-sentinel/blob/main/CONTRIBUTING.md) before opening a pull request.\n- See the directional [`ROADMAP.md`](https://github.com/ShuhanSun/jev-oas-sentinel/blob/main/ROADMAP.md) .\n- Use the issue forms for reproducible bugs and concrete compatibility proposals.\n- Use [`docs/launch.md`](https://github.com/ShuhanSun/jev-oas-sentinel/blob/main/docs/launch.md) when sharing the project without overstating benchmark or model claims.\n\n**JEV OAS Sentinel** is not certified by GitHub. It is provided by a third-party and is governed by separate terms of service, privacy policy, and support documentation.", "url": "https://wpnews.pro/news/jev-oas-sentinel-catch-breaking-api-changes-hidden-in-openapi-prose", "canonical_source": "https://github.com/marketplace/actions/jev-oas-sentinel", "published_at": "2026-09-20 19:36:54+00:00", "updated_at": "2026-09-20 19:52:58.791091+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-tools"], "entities": ["JEV OAS Sentinel", "TypeSafe Jev", "TypeSafe AI", "ShuhanSun", "OpenAPI", "PyYAML", "uv", "GitHub"], "alternates": {"html": "https://wpnews.pro/news/jev-oas-sentinel-catch-breaking-api-changes-hidden-in-openapi-prose", "markdown": "https://wpnews.pro/news/jev-oas-sentinel-catch-breaking-api-changes-hidden-in-openapi-prose.md", "text": "https://wpnews.pro/news/jev-oas-sentinel-catch-breaking-api-changes-hidden-in-openapi-prose.txt", "jsonld": "https://wpnews.pro/news/jev-oas-sentinel-catch-breaking-api-changes-hidden-in-openapi-prose.jsonld"}}