koi_swagger_parser/doc/COMPATIBILITY.md

# Compatibility

[English](COMPATIBILITY.md) | [Chinese (Simplified)](zh-CN/COMPATIBILITY.md)

This matrix describes behavior covered by the current implementation and
automated tests.

- **Supported**: implemented and tested.
- **Partial**: only the boundary stated in the notes is supported.
- **Unsupported**: diagnosed before generation, or explicitly ignored with a
  warning.

## Documents, references, and merging

| Capability | Status | Boundary |
|---|---|---|
| OpenAPI 3.0.x / 3.1.x | Supported | JSON and YAML; common Schema Object subset needed by client generation |
| Swagger/OpenAPI 2.0 | Unsupported | `openapi.unsupported_version` error |
| Local `$ref` | Supported | JSON Pointer across component groups |
| Relative file / file URL `$ref` | Supported | Resolved relative to the referring document |
| HTTP(S) `$ref` | Supported | Per-run cache, dependency tracking, and cycle diagnostics |
| External component name conflicts | Supported | Deterministic rename with warning |
| Multiple root sources | Supported | Deterministic merge; component and operation conflict diagnostics |
| Unresolved `$ref` | Diagnosed | Error; never silently converted to `dynamic` |
| Callbacks / webhooks | Unsupported | Warning; no reverse-call client is emitted |
| Link Object | Unsupported | `openapi.links_not_supported` warning |

This is not a complete JSON Schema 2020-12 implementation. `$defs` as
generation roots, `if`/`then`/`else`, `not`, `contains`,
`dependentSchemas`, and unevaluated-property/item semantics are outside the
current contract.

## Schemas and models

| Capability | Status | Boundary |
|---|---|---|
| Object / array / map | Supported | Recursive containers and inline schemas |
| `properties` + `additionalProperties` | Supported | Extra entries round-trip at the JSON root |
| String/number/integer/bool/date/date-time | Supported | Formats can be overridden by type mappings |
| Enum | Supported | String, number, and boolean wire values; inline or component |
| Enum member-name mappings | Supported | Configuration and common `x-enum` extensions |
| Enum unknown fallback | Supported | Configurable `JsonKey.unknownEnumValue` output |
| Required / nullable / absent | Supported | Deserialization distinguishes missing from disallowed null; ordinary Freezed fields do not retain presence history |
| Read-only / write-only | Supported | Directional request/response variants when needed |
| `allOf` | Supported | Object properties, required fields, and additional properties are merged |
| Discriminator `oneOf`/`anyOf` | Supported | Local or normalized object branches |
| Non-discriminator `oneOf`/`anyOf` | Partial | Primitive, container, and object branches; overlapping `oneOf` matches are rejected |
| Custom schema/type/format | Supported | External imports; host code owns the JSON conversion contract |
| Constraint metadata | Partial | Descriptions/doc comments retained; no generated runtime validator |
| Presence/dirty tracking | Unsupported | No Kiota-style backing store |

## HTTP wire semantics

| Capability | Status | Boundary |
|---|---|---|
| Path/query/header/cookie parameters | Supported | Type, required/default, and wire names |
| Matrix / label / simple | Supported | Validated location/style combinations |
| Form / spaceDelimited / pipeDelimited / deepObject | Supported | Validated query/cookie combinations |
| Explode / `allowReserved` | Supported | A transport adapter is emitted when Retrofit cannot express the behavior |
| Parameter Object `content` | Partial | Exactly one media type is required |
| JSON / `+json` request body | Supported | Required bodies and null-to-absent behavior |
| Text request body | Supported | Typed `@Body` |
| `multipart/form-data` | Supported | Binary, primitive, array, and structured JSON parts |
| `application/x-www-form-urlencoded` | Supported | Typed fields; complex encoding uses an adapter |
| Binary upload | Supported | `Uint8List` |
| Binary download | Supported | `Uint8List` or Dio `ResponseBody` stream |
| XML / Protobuf / arbitrary custom codec | Unsupported | Content-type error; no unsafe decoder is emitted |

## Responses, servers, and security

| Capability | Status | Boundary |
|---|---|---|
| Multiple 2xx / 204 / `2XX` | Supported | Deterministic primary response; differing JSON types may become `Object?` with a warning |
| `default` / 4xx / 5xx | Supported | Error model/IR metadata retained; never selected as success |
| Response headers | Supported | Status, type, required flag, and description |
| Raw response metadata | Supported | `response_mode: http_response` |
| Mixed binary and JSON success media | Diagnosed | Error when one Retrofit method cannot decode the union safely |
| Root/path/operation servers | Supported | Server variable default/enum validation; preferred server becomes client default |
| Runtime switching among servers | Partial | Metadata retained; no environment-selector UI |
| API key / Bearer / Basic | Metadata supported | Scheme and operation requirements generated; credentials supplied by host interceptor/provider |
| OAuth2 / OpenID / mutual TLS | Partial | Scheme/scope metadata only; no complete authorization flow |
| Security OR/AND requirements | Supported | List entries are OR; schemes inside one map entry are AND |

## Generation and lifecycle

| Capability | Status | Boundary |
|---|---|---|
| Retrofit + Freezed | Supported | The only complete renderer in this release |
| Passthrough / external generic wrapper | Supported | Configurable standard-envelope detection |
| Model/property/parameter/operation mappings | Supported | Collision checks and safe identifiers |
| Schema/type/import mappings | Supported | Recursive Dart `List`/`Map` type expressions |
| Tag/path/operation/model filters | Supported | Exact, glob, and `regex:` patterns |
| Dry run | Supported | Reports would-write and would-delete sets |
| Dart fix / format | Supported | Changed primary generated files only |
| build_runner build/watch | Supported | Runs in the configured host-project directory |
| Unchanged skip | Supported | Spec/config/content and actual-file SHA-256 |
| Stale cleanup | Supported | Manifest ownership, root containment, and user-modification protection |
| Concurrent generation lock | Supported | Operating-system exclusive lock beside the manifest |
| External templates / plugin renderer | Unsupported | IR/preset are separated, but there is no public renderer SPI |
| Complete SDK package scaffold | Unsupported | Generates APIs/models inside an existing project |

## Verification coverage

The repository test suite covers:

- parser, IR, renderer, and lifecycle stages;
- OpenAPI 3.0 YAML and OpenAPI 3.1 JSON/FastAPI fixtures;
- enum and naming mappings, parameter wire styles, responses, schema
  semantics, security, and external/cyclic references;
- reviewed SHA-256 golden output;
- generation into a temporary Dart package followed by build_runner, analysis,
  and runtime tests.

Coverage of a feature in this matrix is not a claim of full OpenAPI or JSON
Schema conformance outside the stated boundary. Use a minimal fixture and
dry-run when adopting a new schema corpus.

Diagnostic meanings and remediation are documented in
[Diagnostics](DIAGNOSTICS.md).