Repository navigation
Stability
This page says which machine-readable outputs of sipnab a program can build
on, which changes to them break such a program, and how to compare two
releases with scripts/contract-diff.py.
sipnab is at 0.5. Until 1.0, a release may change any surface, and the changelog names each change. From 1.0 on, a release that breaks a surface on this page is a new major version, as Semantic Versioning defines it.
| Surface | File | Kind |
|---|---|---|
The REST API under /v1: each path, operation, parameter, response status and JSON body |
website/static/openapi.json | openapi |
A call report or full dialog: --call-report --json and GET /v1/dialogs/{id}
|
tests/schemas/call_report.schema.json | schema |
The capture analysis: --json-analyze, GET /v1/report and the MCP get_capture_report answer |
tests/schemas/capture_analysis.schema.json | schema |
One dialog of the GET /v1/dialogs list |
tests/schemas/dialog.schema.json | schema |
One SIP message: a --json or NDJSON line |
tests/schemas/message.schema.json | schema |
| One line of an operator notes file | tests/schemas/notes.schema.json | schema |
One RTP stream: GET /v1/streams/{id} and the streams items of a dialog |
tests/schemas/stream.schema.json | schema |
The script does not yet compare the command line and its exit codes, the configuration keys, the MCP tools or the Prometheus metric names. The vCon output follows the IETF vCon draft, and tests/schemas/vcon.schema.json is that draft's schema, so this page leaves it out.
A change breaks a program when a program written against the older release can fail against the newer one. Every other change is additive. The script reads each schema from the side of a reader: a program reads a report, and a client reads a response.
A change is breaking when:
- a property disappears;
- a required property becomes optional, so it may be absent;
- a value may take a type the older release never sent,
nullincluded; - a schema drops its
type, so the value may be of any type; - a closed list of values (
enum) gains a value; - a closed list of values loses its list;
- a fixed value (
const) changes.
A change is additive when:
- a new property appears, required or not;
- an optional property becomes required;
- a type narrows, as
numbertointeger; - a closed list of values loses a value;
- a list marked
"x-sipnab-open-enum": truein both releases gains a value.
A change is breaking when:
- an operation, a method on a path, disappears;
- a parameter disappears;
- a new required parameter appears;
- an optional parameter becomes required;
- a request body becomes required;
- a response status disappears;
- a response's JSON body disappears;
- a response's JSON body changes in a way the rules above call breaking.
A change is additive when:
- a new operation appears;
- a new optional parameter appears;
- a new response status appears;
- a response's JSON body changes in a way the rules above call additive.
The script follows only references inside a document, those that start with
#/, and it does not compare:
- descriptions, titles, examples and the
infoobject; - the schema of a request body, and the schema of a parameter;
- a change inside
oneOf,anyOf,allOfornot; - bounds, patterns and formats, such as
minimum,maxLength,patternandformat; -
additionalProperties; - a response body of another media type than
application/json; - a JSON body added to a response that had none.
sipnab also reads a notes file back (--notes), and the script reads the
notes schema as output only.
-
A clone of the repository with its tags. A clone made before the newer
release needs
git fetch --tags. The script is in the repository from the first release after 0.5.268; run it from a clone ofmainor of a later release, and name any two release tags. - Python 3. The script uses the standard library only.
- No change on any other system. The script reads files of the clone and connects to no server, so a running sipnab, its API and the SIP servers stay as they are.
# Run all of these, in order.
git clone https://github.com/NormB/sipnab
cd sipnabFrom the top of the clone, write each release's openapi.json to a file, then compare the files:
# Run all of these, in order.
git show v0.5.266:website/static/openapi.json > old.json
git show v0.5.267:website/static/openapi.json > new.json
python3 -I scripts/contract-diff.py --kind openapi old.json new.jsonBetween those two releases every change is additive:
additive GET /v1/aggregate query named: parameter added
additive GET /v1/dialogs query named: parameter added
additive GET /v1/dialogs/rates query named: parameter added
additive GET /v1/filters: operation added
additive GET /v1/filters/validate: operation added
additive GET /v1/talkers query named: parameter added
contract-diff: 6 change(s), 0 breaking
Name the file of the schema under tests/schemas/ in both git show lines:
# Run all of these, in order.
git show v0.5.263:tests/schemas/call_report.schema.json > old.json
git show v0.5.264:tests/schemas/call_report.schema.json > new.json
python3 -I scripts/contract-diff.py --kind schema old.json new.jsonadditive $.seen_by: property added
contract-diff: 1 change(s), 0 breaking
Each line is one change: breaking or additive, then where it is, then
what changed. For the REST API, the place is the method and the path, then a
parameter (query named) or a response status, then a $ path into the
JSON body. For a report schema, it is the $ path alone. A .name step
names a property, and [] names the items of an array. The last line counts
the changes. The script exits 0 when no change is breaking, 1 when one is,
and 2 when it could not decide.
Compare the work tree's openapi.json with itself. The script prints no change and exits 0:
# Run all of these, in order.
python3 -I scripts/contract-diff.py --kind openapi website/static/openapi.json website/static/openapi.json
echo "exit $?"contract-diff: 0 change(s), 0 breaking
exit 0
-
Exit 1. Each
breakingline names a change that can fail a program written against the older release. In a pull request, make the change additive: add an optional property or parameter in place of a required one, and keep the old property beside a new one. -
fatal: invalid object name.git showfound no such tag in the clone: rungit fetch --tags, and check the name withgit tag. -
Expecting value. A file is not JSON. When agit showline fails, its redirection leaves an empty file behind: fix the tag or the path, and run that line again. -
No such file or directory. The script found no file at a path on its command line: run it from the top of the clone, or give the full path. -
is not local to the document; nothing was decided. A$refnames another file. The script follows only references inside the document. -
does not resolve; nothing was decided. A$refnames a part of the document that the document does not hold. -
an OpenAPI document has no `paths` object; nothing was decided. One of the files is not an OpenAPI document, such as a report schema given with--kind openapi: use--kind schemafor it. -
usage: contract-diff.py --kind schema|openapi OLD.json NEW.json. The arguments are not the form the usage line shows.
Website · Repository · Issues · Generated from docs/ — edit there, not here.
Getting started
- Installation
- First CLI Triage
- Glossary
- Cookbook
- Runnable Examples
- Real World Captures
- Troubleshooting
- Measure Call Quality
- Run as a Service
- Tuning Capture
- Encapsulations
- Capture With Least Privilege
- Collect and Forward HEP
- Read Captures From Archives
- Rtpengine Relays
- Ask a Media Relay About Itself
- Ask Each Calls rtpengine Engine
- Backers
Using the TUI
CLI & automation
- CLI Reference
- Error Messages
- Capture Queries
- Expectations
- Filter DSL
- Follow A Call
- Output Formats
- Stability
- SIP Response Codes
- SIP Methods
- SIP Header Fields
- SIP Parameters
- SIP Lint Rules
- MOS and Codecs
Configuration
Integrations (API & MCP)
- REST API
- Prometheus Metrics
- Authentication
- Require Client Certificates
- MCP
- MCP Deployment
- MCP Across an Estate
- Manage Many Instances
- MCP Tools
- MCP Tools Core
- MCP Tools Signaling
- MCP Tools Captures
- MCP Tools Security
- MCP Tools Media
- MCP Tools Relay
- MCP Tools TFPS
- MCP Tools Server
- MCP Tools vCon
- MCP Tools TLS
- MCP Protocol
- Uprobe Walkthrough
- Capture SIP over TLS
- WASM Plugins
- Run Commands and Send Alerts
- vCon Export
- vCon Capture Stack
- G729 Decoding
Your SIP server
- Use OpenSIPS as the SIP Server
- Run sipnab beside OpenSIPS
- Use Kamailio as the SIP Server
- Run sipnab beside Kamailio
- Use Asterisk as the PBX
- Run sipnab beside Asterisk
- Use FreeSWITCH in the Voice Stack
- Run sipnab beside FreeSWITCH
Add to your voice stack
- Add a vCon Server
- Send vCons to a vCon Server
- Send vCons to vcon store
- Add TFPS
- Control TFPS from sipnab
- Ban SIP Scanners with fail2ban
- Feed fail2ban from sipnab
- Add rtpengine
- Name rtpengine Media with sipnab
- Add rtpproxy
- Name rtpproxy Media with sipnab
- Add Homer
- Connect sipnab to Homer
- Add Prometheus and Grafana
- Add sipnab Metrics to Prometheus
Development & internals
- Internals Index
- Internals Subsystem Guide
- Internals Invariants
- Internals Testing
- Internals Walkthroughs
- Internals Build CI Release
- Internals Profiling
- Internals Domain Primer
- Library API
- Benchmarks
- Fault Model
- Threat Model
- Assurance Case
- Architecture
- Internals Threading
- Internals TUI Testing
- Internals Zero Copy Payloads
- Internals Uprobe Capture
- Internals Rtpengine Control Plane
- Internals Relay Control Decoding
- Internals vCon Exporter
- Internals Operator Guide Notes
- Internals Postmortems
- Internals Code Map
- Internals Lint Rules
- Internals Encapsulation Decoding
- Internals MCP Design Notes
- Internals Metrics And Output Notes