bd2af6e0b1
Document the package. Change-Id: I770c14d6339b75ea6827280c23171c3584dc1071 Reviewed-on: https://go-review.googlesource.com/c/tools/+/674977 Reviewed-by: Robert Findley <rfindley@google.com> Reviewed-by: Alan Donovan <adonovan@google.com> Auto-Submit: Jonathan Amsterdam <jba@google.com> LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
74 lines
2.5 KiB
Go
74 lines
2.5 KiB
Go
// Copyright 2025 The Go MCP SDK Authors. All rights reserved.
|
|
// Use of this source code is governed by an MIT-style
|
|
// license that can be found in the LICENSE file.
|
|
|
|
/*
|
|
Package jsonschema is an implementation of the [JSON Schema specification],
|
|
a JSON-based format for describing the structure of JSON data.
|
|
The package can be used to read schemas for code generation, and to validate data using the
|
|
draft 2020-12 specification. Validation with other drafts or custom meta-schemas
|
|
is not supported.
|
|
|
|
Construct a [Schema] as you would any Go struct (for example, by writing a struct
|
|
literal), or unmarshal a JSON schema into a [Schema] in the usual way (with [encoding/json],
|
|
for instance). It can then be used for code generation or other purposes without
|
|
further processing.
|
|
|
|
# Validation
|
|
|
|
Before using a Schema to validate a JSON value, you must first resolve it by calling
|
|
[Schema.Resolve].
|
|
The call [Resolved.Validate] on the result to validate a JSON value.
|
|
The value must be a Go value that looks like the result of unmarshaling a JSON
|
|
value into an [any] or a struct. For example, the JSON value
|
|
|
|
{"name": "Al", "scores": [90, 80, 100]}
|
|
|
|
could be represented as the Go value
|
|
|
|
map[string]any{
|
|
"name": "Al",
|
|
"scores": []any{90, 80, 100},
|
|
}
|
|
|
|
or as a value of this type:
|
|
|
|
type Player struct {
|
|
Name string `json:"name"`
|
|
Scores []int `json:"scores"`
|
|
}
|
|
|
|
# Inference
|
|
|
|
The [For] and [ForType] functions return a [Schema] describing the given Go type.
|
|
The type cannot contain any function or channel types, and any map types must have a string key.
|
|
For example, calling For on the above Player type results in this schema:
|
|
|
|
{
|
|
"properties": {
|
|
"name": {
|
|
"type": "string"
|
|
},
|
|
"scores": {
|
|
"type": "array",
|
|
"items": {"type": "integer"}
|
|
}
|
|
"required": ["name", "scores"],
|
|
"additionalProperties": {"not": {}}
|
|
}
|
|
}
|
|
|
|
# Deviations from the specification
|
|
|
|
Regular expressions are processed with Go's regexp package, which differs from ECMA 262,
|
|
most significantly in not supporting back-references.
|
|
See [this table of differences] for more.
|
|
|
|
The value of the "format" keyword is recorded in the Schema, but is ignored during validation.
|
|
It does not even produce [annotations].
|
|
|
|
[JSON Schema specification]: https://json-schema.org
|
|
[this table of differences] https://github.com/dlclark/regexp2?tab=readme-ov-file#compare-regexp-and-regexp2
|
|
[annotations]: https://json-schema.org/draft/2020-12/json-schema-core#name-annotations
|
|
*/
|
|
package jsonschema
|