# OpenAPI Support Matrix

MoonContract 0.1.x 聚焦常见 REST JSON API，不声称实现完整 OpenAPI 或 JSON
Schema 规范。

## Supported

| Area | Support |
| --- | --- |
| Versions | OpenAPI 3.0.0–3.0.3 |
| Input | JSON；`moonbit-community/yaml` 支持的常用 YAML 子集 |
| Operations | GET、POST、PUT、PATCH、DELETE、HEAD、OPTIONS、TRACE |
| Parameters | path、query、header、cookie；标量和数组 |
| Bodies | `application/json` 和 `application/*+json` |
| Responses | 精确状态码、`1XX`–`5XX` 范围和 `default`；Mock 显式选择优先级为精确 > 范围 > default |
| References | components 下 schemas、parameters、requestBodies、responses 的本地 `$ref` |
| Schemas | string、integer、number、boolean、array、object |
| Constraints | required、nullable、enum、default、example、min/max、长度和数组数量 |
| Object policy | properties 和布尔 `additionalProperties` |

Query 数组支持重复键和逗号分隔形式。静态路由优先于参数路由，路径模板参数必须
占据完整路径段。

## Partial

- `format` 用于生成常见 date、date-time、email 和 uuid Mock，暂不执行严格格式校验。
- YAML 由上游简化解析器提供，不支持完整 YAML 1.2 特性。
- 非 JSON media type 会被忽略或诊断，不解析 multipart、form 或二进制正文。
- Schema 中未知关键字会被保留为未执行语义，不作为完整 JSON Schema 实现。

## Not Supported in 0.1.x

- OpenAPI 2.0 和 3.1。
- 外部文件或网络 `$ref`。
- `allOf`、`oneOf`、`anyOf`、`not`、discriminator 和 XML。
- callbacks、links、webhooks 和 OAuth 流程执行。
- 参数对象序列化、deepObject 和复杂 style/explode 组合。
- 状态化 Mock、代理、流量录制、TLS 和生产部署。

不支持的范围会在新增实现前更新此矩阵，并增加对应测试。


## 0.1.1 校验语义说明

- `nullable` 只放宽类型，不能跳过 enum；enum 排除 null 时仍拒绝 null。
- 无类型且未被解析器推断为 object/array 的 Schema 仍执行 enum，以及与实例类型匹配的数值/字符串等已支持约束。当前解析器仍会从 properties/items 推断类型，不能据此宣称完整无类型 JSON Schema 兼容性。
- JSON 正文整数按有限 Double 的数学整数判断，不再错误限制为 Int32；并未新增任意精度数字类型。超过 binary64 精确表示范围的 JSON 数字可能已被舍入，应使用字符串标识符或明确范围。
- path/query/header/cookie 的 integer 转换仍使用 Int32 解析；本轮没有扩展参数序列化和大整数文本输入。
- 通过库 API 构造的 NaN/Infinity 在数值校验中拒绝；它们不是合法 JSON 数字。
- 未执行的未知 Schema 关键字不会因此变成受支持约束。