kin-openapi v0.113.0版本对JSON Schema校验的严格化处理

在kin-openapi项目升级到v0.113.0版本后，许多开发者遇到了JSON Schema校验失败的问题。这个问题源于该版本对OpenAPI规范中JSON Schema校验规则的严格化处理，特别是针对非OpenAPI标准字段的校验。

问题背景

kin-openapi是一个用于处理OpenAPI/Swagger规范的Go语言库。在v0.113.0版本之前，该库对JSON Schema中的一些标准字段（如$id、$schema等）采取了较为宽松的处理方式。然而，从技术规范角度来看，这些字段在OpenAPI v3.0及以下版本中并不是官方支持的标准字段。

OpenAPI v3.1是第一个完整支持JSON Schema规范的版本。在v3.1之前，OpenAPI对JSON Schema的支持是子集形式的，这意味着许多JSON Schema标准字段在OpenAPI v3.0中并不被官方认可。

版本变更带来的影响

v0.113.0版本的kin-openapi开始严格执行OpenAPI v3.0规范，导致以下变化：

1. 不再默认允许JSON Schema标准字段（如$id、$schema）
2. 对这些"额外"字段会触发"extra sibling fields"校验错误
3. 需要显式声明允许这些字段才能通过校验

这一变更影响了许多现有项目，特别是那些在Schema中使用了完整JSON Schema特性的项目。

解决方案

对于需要继续使用这些JSON Schema标准字段的项目，kin-openapi提供了明确的解决方案：

err = doc.Validate(ctx, openapi3.AllowExtraSiblingFields("$id", "$schema", "examples"))

通过使用AllowExtraSiblingFields选项，开发者可以明确指定允许哪些额外的字段出现在Schema中。这种方法既保持了规范的严格性，又为需要这些字段的项目提供了灵活性。

技术建议

1. 评估升级影响：在升级到v0.113.0或更高版本前，应全面评估项目中JSON Schema的使用情况。

2. 逐步迁移：对于大型项目，可以考虑分阶段迁移，先处理关键Schema的兼容性问题。

3. 规范一致性：长期来看，建议将项目迁移到OpenAPI v3.1（当kin-openapi支持时），以获得完整的JSON Schema支持。

4. 文档注释：在使用AllowExtraSiblingFields时，建议添加注释说明为何需要这些额外字段，便于后续维护。

总结

kin-openapi v0.113.0版本的这一变更体现了开源项目向规范严格化方向的发展趋势。虽然短期内可能带来一些迁移成本，但从长远来看，这种严格化有助于提高代码的规范性和可维护性。开发者应当理解这一变更背后的技术考量，并采取适当的应对措施。