koi_swagger_parser/doc/COMPATIBILITY.md

Compatibility

English | Chinese (Simplified)

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.