Go jsonschema 怎样从内存注册被引用的 Schema

如果 JSON Schema 不落盘，而是由配置、数据库或代码在运行时拼出来，Go 的 jsonschema/v5 仍然可以解析其中的 $ref。关键不是把所有内容拼成一份大 JSON，而是让同一个 Compiler 先用稳定的资源名注册主 Schema 和被引用 Schema，再从主资源名调用 Compile。

最小配方：用同一个 Compiler 收纳多份 Schema

先准备两份 JSON 文本：main.json 只声明入口对象和 $ref，obj.json 提供被引用的对象结构。两次 AddResource 必须使用同一个编译器，第二个参数可以是 strings.NewReader，因此不需要创建临时文件。

package main

import (
    "log"
    "strings"

    "github.com/santhosh-tekuri/jsonschema/v5"
)

func buildSchema() (*jsonschema.Schema, error) {
    // 两份资源共享一个 Compiler，引用才会在同一资源表中解析。
    compiler := jsonschema.NewCompiler()

    mainSchema := `{"$schema":"https://json-schema.org/draft/2020-12/schema","$ref":"obj.json"}`
    objectSchema := `{"type":"object","properties":{"name":{"type":"string"}}}`

    // 资源名是内存中的定位键，不是必须存在的磁盘路径。
    if err := compiler.AddResource("main.json", strings.NewReader(mainSchema)); err != nil {
        return nil, err
    }
    if err := compiler.AddResource("obj.json", strings.NewReader(objectSchema)); err != nil {
        return nil, err
    }

    // 从根资源编译，$ref 会继续寻找已注册的 obj.json。
    return compiler.Compile("main.json")
}

func main() {
    // 入口只展示错误处理；实际校验时可继续调用 schema.Validate。
    if _, err := buildSchema(); err != nil {
        log.Fatal(err)
    }
}

这段配方里，main.json 的 $ref 是 obj.json，所以注册时必须出现同名资源。Compile("main.json") 选择的是根入口，不是被引用的子资源；这样得到的 Schema 才代表完整的引用关系。

$ref 为什么必须和资源名对得上

AddResource 的第一个参数承担的是资源 URL/名称的定位作用。它不一定是真实文件，但必须能参与引用解析，而且官方文档明确要求这个 URL 不能带 fragment。最常见的相对引用是 main.json 里的 "$ref":"obj.json"，对应的注册键就应是 obj.json，而不是一个随手起的 child-schema。

如果需要定位子 Schema 内部的定义，fragment 放在 $ref 中，而不是放进 AddResource 的资源名。例如：

{
  "$ref": "obj.json#/definitions/item"
}

这里的 obj.json 仍然是已注册资源，#/definitions/item 只是文档内部位置。注册阶段可先把完整的 obj.json 放入内存，再由引用表达式完成内部定位。

动态内容怎么接入，哪些错误要先看

当 Schema 来自数据库字段或配置中心时，可以先把字符串转成 strings.NewReader；如果内容已经是字节，也可以用 bytes.NewReader。两者都满足 io.Reader，但资源名仍然要稳定，否则相对 $ref 无法建立明确的基准。

import (
    "bytes"

    "github.com/santhosh-tekuri/jsonschema/v5"
)

func compileFromMemory(mainText, childText []byte) (*jsonschema.Schema, error) {
    // 使用字节 Reader 接入动态配置，资源名继续保持可预测。
    compiler := jsonschema.NewCompiler()
    if err := compiler.AddResource("schemas/main.json", bytes.NewReader(mainText)); err != nil {
        return nil, err
    }
    if err := compiler.AddResource("schemas/obj.json", bytes.NewReader(childText)); err != nil {
        return nil, err
    }

    // 相对引用应以 schemas/main.json 的位置为基准组织资源名。
    return compiler.Compile("schemas/main.json")
}

排查时按这三个问题看最快：第一，所有资源是否使用了同一个 Compiler；第二，$ref 的相对路径和注册名是否一致；第三，是否误把带 #... 的完整引用写进了 AddResource。若资源本身是非法 JSON 或引用目标不存在，AddResource 或 Compile 会返回错误，应在返回处保留上下文。

把内存注册封装成可复用入口

在服务中，建议把“资源命名规则、注册顺序和根入口”收在一个小函数里，不要让业务层到处拼接 $ref。只要每次编译使用的资源键稳定，Schema 可以按请求重新构建，也可以在配置不变时缓存编译后的结果；缓存的是编译结果，不是把资源名改成随机值。

• 主资源和子资源必须进入同一个 Compiler。
• 资源键不带 fragment，fragment 只用于引用文档内部位置。
• 编译根资源后再交给业务校验，不要直接把某个子资源当作完整入口。

常见问题

只注册 main.json，能让 $ref 自动读取内存里的 obj.json 吗？

不能。除非另行配置加载器，否则被引用资源也要加入同一个 Compiler；内存注册不会凭空知道另一份文本。

AddResource 的 URL 可以写成 obj.json#/definitions/item 吗？

不建议也不符合该方法的边界。注册 URL 不应带 fragment，应注册 obj.json，再在 $ref 中写 fragment。

Compile 应该传主 Schema 还是被引用 Schema？

传主 Schema 的资源名。它是读者请求对应的根文档，编译器会沿着其中的 $ref 找到已注册的依赖。