如何在JSON Schema中正确引用其他JSON Schema文件？

问题场景 #

我有两个简化后的JSON Schema文件：

header.scm #

{
    "$schema":"https://json-schema.org/draft/2020-12/schema",
    "$id":"header.scm",
    "type":"object",
    "additionalProperties":false,
    "properties":{
        "id":{
            "type":"string",
            "pattern":"^[A-Z]*([0-9]{17})$",
        },
        "verb":{
            "type":"string",
            "enum":["POST","GET","PUT","PATCH","DELETE"]
        }
    },
    "required":["id","endpoint"]
}

wms_mission.scm #

{
    "$schema":"https://json-schema.org/draft/2020-12/schema",
    "$id":"wms_mission.scm",
    "type":"object",
    "properties":{
        "header":{
            "$ref":"#C:/schemas/header.scm"
        },
        "body":{
            "additionalProperties":false,
            "type":"object",
            "properties":{
                "mission_id":{
                    "type":"string",
                    "pattern":"^(MISSION)([0-9]{17})$",
                },
                "command":{
                    "type":"string",
                    "enum":["CREATE","CANCEL"]
                }
            },
            "required":["mission_id","command"]
        }
    },
    "required":["header","body"],
    "additionalProperties":false
}

用这套Schema校验消息格式时，示例消息如下：

{
    "body":{
        "mission_id":"EJ_1",
        "command":"CREATE"
    },
    "header":{
        "id":"EXAMPLE_ID001",
        "verb":"POST"
    }
}

为复用header结构，我在wms_mission.scm中用绝对路径通过$ref引用header.scm，但验证时报错：

Check that the format follows the schema (wms_mission.scm). [header: is missing but it is required, body: is missing but it is required]

调整相对路径后要么抛异常，要么误判验证通过，求正确的跨文件引用方法。

问题修复与正确引用方式 #

1. 修正$ref的路径格式 #

你当前的"$ref":"#C:/schemas/header.scm"是错误的URI格式，JSON Schema引用本地文件必须使用标准file://协议：

"$ref": "file:///C:/schemas/header.scm"

注意：file:///是三个斜杠，后接完整本地绝对路径。

2. 相对路径引用的正确写法 #

如果两个文件在同一目录，直接用文件名：

"$ref": "header.scm"

如果header.scm在当前目录的schemas子文件夹中：

"$ref": "./schemas/header.scm"

3. 修复header.scm的自身错误 #

你的header.scm中required数组包含"endpoint"，但properties里根本没定义这个字段——这会导致所有header实例都验证失败，进而让父Schema误报“header缺失”。必须删除"endpoint"或者补充该字段的定义：

// 修正后的required数组
"required":["id"]

4. 验证工具的注意事项 #

不同工具对本地路径的支持有差异，如果问题仍存在：

• 确认工具支持file://协议
• 将所有Schema放在同一目录，用相对路径引用
• 部分工具需要手动加载所有依赖Schema，无法自动解析$ref路径

内容的提问来源于stack exchange，提问作者Danielps1818