Appendix A. HTTP Problems 的 JSON Schema (JSON Schema for HTTP Problems)

本节给出 HTTP problem details 的 non-normative JSON Schema [JSON-SCHEMA]. 如果它与规范正文存在任何不一致, 以后者为准.

该 schema 用于说明 problem object 常见成员的结构, 包括 type、title、status、detail 和 instance. JSON Schema 中的字段名、类型名、格式名和描述文本保持原样, 因为它们是示例 schema 的一部分. 实现者应以正文规范为准, 不应把本附录视为替代性的规范定义.

在实际工程中, 该 schema 可用于测试和文档生成, 但协议兼容性仍取决于正文对成员语义、扩展成员和媒体类型的规定. 也就是说, 通过 schema 校验并不自动意味着 Problem Details 响应满足所有 RFC 9457 要求.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "An RFC 7807 problem object",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "format": "uri-reference",
      "description": "A URI reference that identifies the problem type."
    },
    "title": {
      "type": "string",
      "description": "A short, human-readable summary of the problem type."
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status code generated by the origin server for this occurrence of the problem.",
      "minimum": 100,
      "maximum": 599
    },
    "detail": {
      "type": "string",
      "description": "A human-readable explanation specific to this occurrence of the problem."
    },
    "instance": {
      "type": "string",
      "format": "uri-reference",
      "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced."
    }
  }
}