jsonschema tags

Author: jba

jsonschema/infer.go

@@ -9,6 +9,7 @@ package jsonschema
 import (
 	"fmt"
 	"reflect"
+	"regexp"
 
 	"github.com/modelcontextprotocol/go-sdk/internal/util"
 )
@@ -36,8 +37,12 @@ import (
 //   - complex numbers
 //   - unsafe pointers
 //
-// The types must not have cycles.
 // It will return an error if there is a cycle in the types.
+//
+// For recognizes struct field tags named "jsonschema".
+// A jsonschema tag on a field is used as the description for the corresponding property.
+// For future compatibility, descriptions must not start with "WORD=", where WORD is a
+// sequence of non-whitespace characters.
 func For[T any]() (*Schema, error) {
 	// TODO: consider skipping incompatible fields, instead of failing.
 	seen := make(map[reflect.Type]bool)
@@ -126,10 +131,20 @@ func forType(t reflect.Type, seen map[reflect.Type]bool) (*Schema, error) {
 			if s.Properties == nil {
 				s.Properties = make(map[string]*Schema)
 			}
-			s.Properties[info.Name], err = forType(field.Type, seen)
+			fs, err := forType(field.Type, seen)
 			if err != nil {
 				return nil, err
 			}
+			if tag, ok := field.Tag.Lookup("jsonschema"); ok {
+				if tag == "" {
+					return nil, fmt.Errorf("empty jsonschema tag on struct field %s.%s", t, field.Name)
+				}
+				if disallowedPrefixRegexp.MatchString(tag) {
+					return nil, fmt.Errorf("tag must not begin with 'WORD=': %q", tag)
+				}
+				fs.Description = tag
+			}
+			s.Properties[info.Name] = fs
 			if !info.Settings["omitempty"] && !info.Settings["omitzero"] {
 				s.Required = append(s.Required, info.Name)
 			}
@@ -144,3 +159,6 @@ func forType(t reflect.Type, seen map[reflect.Type]bool) (*Schema, error) {
 	}
 	return s, nil
 }
+
+// Disallow jsonschema tag values beginning "WORD=", for future expansion.
+var disallowedPrefixRegexp = regexp.MustCompile("^[^ \t\n]*=")

jsonschema/infer_test.go

@@ -23,6 +23,11 @@ func forType[T any]() *jsonschema.Schema {
 
 func TestFor(t *testing.T) {
 	type schema = jsonschema.Schema
+
+	type S struct {
+		B int `jsonschema:"bdesc"`
+	}
+
 	tests := []struct {
 		name string
 		got  *jsonschema.Schema
@@ -45,9 +50,9 @@ func TestFor(t *testing.T) {
 		{
 			"struct",
 			forType[struct {
-				F           int `json:"f"`
+				F           int `json:"f" jsonschema:"fdesc"`
 				G           []float64
-				P           *bool
+				P           *bool  `jsonschema:"pdesc"`
 				Skip        string `json:"-"`
 				NoSkip      string `json:",omitempty"`
 				unexported  float64
@@ -56,13 +61,13 @@ func TestFor(t *testing.T) {
 			&schema{
 				Type: "object",
 				Properties: map[string]*schema{
-					"f":      {Type: "integer"},
+					"f":      {Type: "integer", Description: "fdesc"},
 					"G":      {Type: "array", Items: &schema{Type: "number"}},
-					"P":      {Types: []string{"null", "boolean"}},
+					"P":      {Types: []string{"null", "boolean"}, Description: "pdesc"},
 					"NoSkip": {Type: "string"},
 				},
 				Required:             []string{"f", "G", "P"},
-				AdditionalProperties: &jsonschema.Schema{Not: &jsonschema.Schema{}},
+				AdditionalProperties: falseSchema(),
 			},
 		},
 		{
@@ -75,7 +80,37 @@ func TestFor(t *testing.T) {
 					"Y": {Type: "integer"},
 				},
 				Required:             []string{"X", "Y"},
-				AdditionalProperties: &jsonschema.Schema{Not: &jsonschema.Schema{}},
+				AdditionalProperties: falseSchema(),
+			},
+		},
+		{
+			"nested and embedded",
+			forType[struct {
+				A S
+				S
+			}](),
+			&schema{
+				Type: "object",
+				Properties: map[string]*schema{
+					"A": {
+						Type: "object",
+						Properties: map[string]*schema{
+							"B": {Type: "integer", Description: "bdesc"},
+						},
+						Required:             []string{"B"},
+						AdditionalProperties: falseSchema(),
+					},
+					"S": {
+						Type: "object",
+						Properties: map[string]*schema{
+							"B": {Type: "integer", Description: "bdesc"},
+						},
+						Required:             []string{"B"},
+						AdditionalProperties: falseSchema(),
+					},
+				},
+				Required:             []string{"A", "S"},
+				AdditionalProperties: falseSchema(),
 			},
 		},
 	}
@@ -205,7 +240,6 @@ func TestForWithCycle(t *testing.T) {
 	}
 
 	for _, test := range tests {
-		test := test // prevent loop shadowing
 		t.Run(test.name, func(t *testing.T) {
 			err := test.fn()
 			if test.shouldErr && err == nil {