v2.0.0 to v3.0.0
102 added, 41 removed. Audit A to A.
---
name: broker-api-changelog-diffing-tool
- description: Use when updating broker SDKs or API integrations to automatically diff
- release-over-release OpenAPI/JSON schemas, detecting breaking endpoint removals,
- renamed parameters, mutated enums, request body changes, and response model alterations
- before production deployment.
+ description: Use when updating broker SDKs or API integrations to diff release-over-release
+ OpenAPI schemas, resolving $ref models and detecting breaking endpoint removals, removed
+ response codes and content types, requirement changes, direction-aware enum mutations,
+ and type changes before production deployment.
domain: algorithmic-trading
subdomain: broker-integration
tags:
- broker-integration
- api-changelog
- schema-diffing
- openapi
- breaking-changes
- - ci-cd-security
- - quantitative-engineering
+ - ci-cd
brokers_frameworks:
- - Schema Diffing Engine
- - Python OpenAPI Parser
- - Quantitative Standards
- version: "2.0.0"
+ - OpenAPI 3.x
+ - Swagger 2.0 (reference resolution only)
+ version: "3.0.0"
author: algo-trading-skills-contributors
license: Apache-2.0
---
## When to Use
- Invoke this skill prior to upgrading broker SDK versions or pulling new API specifications (e.g., Binance OpenAPI specs, Coinbase REST schemas, IBKR Client Portal specs). Broker API version updates frequently introduce silent breaking changes — removing required fields in nested response objects, altering parameter types, or deleting enum values. This skill rigorously diffs API schemas release-over-release to flag these changes in CI/CD build pipelines, adhering to strict institutional quant standards.
+ Invoke this before upgrading a broker SDK version or pulling a new API specification
+ (Binance, Coinbase, IBKR Client Portal and similar publish OpenAPI documents). Broker
+ releases introduce silent breaking changes — a removed nested response field, a parameter
+ that quietly became mandatory, a new order status the state machine has never seen. This
+ skill diffs two schema snapshots and classifies what changed, so a CI job can fail the
+ build before the change reaches an order path.
+ The tool is a **gate**, and its failure modes are asymmetric: a false positive costs a
+ developer a few minutes, a false negative ships a broken integration. Everything about its
+ classification is biased accordingly.
+
+ ## When NOT to Use
+
+ - **As proof a release is safe.** It compares structure only. Rate limits, auth scope
+ changes, altered matching-engine behaviour, changed rounding, new error codes returned
+ in a 200 body — none are expressible in a schema, and none will appear in the report. A
+ clean diff means "nothing structural broke", not "safe to deploy".
+ - **On specifications it cannot fully resolve.** Only local (`#/...`) references are
+ followed. External and remote `$ref`s are reported as `UNRESOLVED_REF` — that region was
+ *not compared*, and treating the report as complete when one is present is a mistake.
+ - **As a Swagger 2.0 differ.** `#/definitions/...` references resolve, but Swagger 2.0's
+ body parameters and top-level `consumes`/`produces` are not modeled; the request-body
+ logic assumes OpenAPI 3.x `requestBody.content`. Convert 2.0 documents to 3.x first.
+ - **As a file loader.** It takes parsed Python dictionaries. Reading and parsing JSON or
+ YAML is the caller's job.
+ - **For composition keywords.** `oneOf`, `anyOf`, `allOf` and `discriminator` are not
+ evaluated; schemas using them will diff only at the level the tool can see.
+
## Prerequisites
- - Baseline (older) OpenAPI/JSON schema snapshot.
- - Target (newer) OpenAPI/JSON schema snapshot.
+ - Baseline (older) and target (newer) API schemas, parsed into dictionaries.
+ - Both documents complete, including the `components`/`definitions` sections the
+ `$ref`s point at — a spec split across files must be bundled first, or references will
+ come back unresolved.
## Workflow
- 1. **Ingest Old and New API Schemas**:
- - Load OpenAPI/Swagger v2 or v3 JSON/YAML specifications for $V_{\text{old}}$ and $V_{\text{new}}$.
+ 1. **Load both documents and let the differ reject unusable input.** `diff_schemas`
+ raises `SchemaDiffError` when a document is not a mapping or has no `paths`. This is
+ deliberate: a failed download or a wrong path yields an empty document, and a differ
+ that shrugs and reports zero changes turns the gate green at exactly the moment it
+ matters.
- 2. **Diff Endpoint & Path Hierarchies**:
- - Identify deleted paths, added endpoints, and modified HTTP methods.
+ 2. **Diff endpoints.** Removed paths and removed methods are `CRITICAL_BREAKING`. Only
+ real HTTP methods are treated as operations — a Path Item Object also legally carries
+ `parameters`, `servers`, `summary`, `description` and `$ref`, and path-level
+ `parameters` are diffed as shared across every operation.
- 3. **Diff Request Parameters & Bodies**:
- - recursively scan for removed fields, modified field data types, deleted enums, and new mandatory parameters.
- - Specifically handles `requestBody` objects across different `content-type` specifications.
+ 3. **Resolve `$ref` before comparing anything.** Real broker specs describe payloads
+ almost entirely through references, and a `$ref` schema carries no `type`, `properties`
+ or `enum` of its own. Resolution follows `#/components/schemas/...` and
+ `#/definitions/...` against the document each side came from, with cycle protection for
+ self-referential models.
- 4. **Diff Response Schemas**:
- - Ensure the broker does not remove payload fields that trading algorithms might depend on to parse market state, executions, or balances.
- - Check for response type mutations.
+ 4. **Treat absence as a change.** A removed response status code, a removed request or
+ response content type, and a removed `requestBody` are all breaking and all invisible
+ to a differ that walks only the keys present on both sides.
- 5. **Classify Breaking Change Severity**:
- - `REMOVED_ENDPOINT` / `CRITICAL_BREAKING`
- - `REMOVED_FIELD` / `HIGH_BREAKING`
- - `TYPE_MUTATION` / `HIGH_BREAKING`
- - `ENUM_MUTATION` / `HIGH_BREAKING`
- - `REMOVED_RESPONSE_FIELD` / `HIGH_BREAKING`
- - `RESPONSE_TYPE_MUTATION` / `HIGH_BREAKING`
- - `NEW_REQUIRED_PARAMETER` / `MEDIUM_BREAKING`
- - `ADDED_OPTIONAL_FIELD` / `NON_BREAKING_INFO`
+ 5. **Check requirement transitions in both directions.** A request field or parameter
+ moving *into* `required` breaks callers that omit it. A response field moving *out of*
+ `required` breaks parsers that assume it is present. Both matter; they are not the same
+ check.
- 6. **Generate CI/CD Compatibility Report**:
- - Fail CI build if critical, high, or medium breaking changes are detected without adapter updates.
+ 6. **Classify enums by direction.** A request enum constrains what the client may send, so
+ *removing* a value is breaking. A response enum constrains what the client must handle,
+ so *adding* a value is breaking — a new order status silently breaks an exhaustive state
+ machine. Newly imposing a request constraint, and dropping a response constraint, are
+ breaking too.
+ 7. **Gate the build.** `report.exit_code` is 0 when compatible and 1 otherwise;
+ `report.format_report()` renders the findings severity-first. `is_compatible` is False
+ if any change is `MEDIUM_BREAKING` or higher.
+
> Full procedure: see `references/workflows.md`.
- > Standards reference: see `references/standards.md`.
+ > Severity matrix and classification rationale: see `references/standards.md`.
> Printable pre-flight checklist: see `assets/checklist.md`.
## Common Pitfalls
- - **Silent Enum Value Modifications**: Broker removing order states or cancellation reason strings, breaking quantitative state machines.
- - **Ignoring Nested Payload Objects**: Diffing top-level JSON keys while missing breaking changes inside nested arrays or request bodies.
- - **Treating Optional Field Additions as Breaking**: Raising false alarm build failures for non-breaking backward-compatible additions.
+ - **Comparing `$ref` schemas without resolving them.** Both sides look like empty objects,
+ every check is skipped, and a release that deleted an entire response model reports
+ clean. This is the single most likely way to get a false green.
+ - **Ignoring an `UNRESOLVED_REF` finding.** It is informational in severity but it means a
+ region of the schema was never compared. Bundle the spec and re-run.
+ - **Only diffing keys present on both sides.** Removals are the breaking changes; a
+ loop written as `if key in new: compare(...)` cannot see any of them.
+ - **Treating enum changes as direction-agnostic.** Flagging every set difference raises
+ false alarms on request widenings while missing the response additions that actually
+ break consumers.
+ - **Assuming a scalar `type`.** OpenAPI 3.1 allows `type: ["object", "null"]` where 3.0
+ used `nullable: true`. An equality test against the literal `"object"` silently skips
+ property diffing, and comparing the two spellings reports a mutation that never happened.
+ - **Treating every key under a path as an HTTP method.** `parameters` is a list and
+ `summary` is a string; calling `.get()` on them raises on a perfectly valid document.
+ - **Letting an empty or malformed document produce a clean report.**
+ - **Unbounded recursion on self-referential models.** `Order.parent → Order` is ordinary,
+ and resolving references without a cycle guard hangs the build.
+ - **Reading a clean report as deployment approval.** Structure is not behaviour.
## Verification
- - Input two OpenAPI schemas where an endpoint is removed, a response field is removed, an enum is removed, and a field type is mutated.
- - Verify non-breaking optional field additions are correctly classified as `INFO`.
- - Run `python scripts/test_changelog_differ.py` and confirm 100% pass rate.
+ - Run the unit suite and confirm every test passes:
+ `python -m unittest discover -s skills/broker-api-changelog-diffing-tool/scripts`
+ - Build a fixture whose response model sits behind a `$ref`, delete a field from the
+ referenced component, and confirm `REMOVED_RESPONSE_FIELD` is reported. A differ that
+ passes every inline-schema test can still fail this one, which is the case that matters.
+ - Confirm two empty documents raise `SchemaDiffError` rather than reporting compatible.
+ - Confirm a self-referential model terminates.
+ - Confirm direction-aware enum behaviour: adding a response enum value is breaking; adding
+ a request enum value is not.
+ - Confirm a Path Item Object carrying `parameters` and `summary` does not raise.
+ - Mutate fixtures by deep-copying a baseline and changing exactly one thing, so a test for
+ one change cannot accidentally introduce another.
## Related Skills
- `broker-api-versioning-migration-playbook`
- `broker-api-deprecation-notice-monitoring`
- `sandbox-vs-production-endpoint-drift`
+ - `broker-agnostic-adapter-interface`