grammar : support array references in json schema

[aldehir]

fixes #16790

related: #16714 (comment).

The JSON schema to grammar conversion does not support referencing array items. It appears zod or the MCP library may do this to reuse schemas instead of creating a separate definition.

Example

curl http://localhost:8080/v1/chat/completions -d '{
  "model": "gpt-oss-20b",
  "messages": [
    {
      "role": "user",
      "content": "Build a binary tree that matches (A (B C D) E)"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "build_binary_tree",
        "description": "build a binary tree. The left/right fields may be either a string value or another tree.",
        "parameters": {
          "type": "object",
          "properties": {
            "tree": {
              "type": "object",
              "properties": {
                "left": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "$ref": "#/properties/tree"
                    }
                  ]
                },
                "right": {
                  "anyOf": [
                    {
                      "$ref": "#/properties/tree/properties/left/anyOf/0"
                    },
                    {
                      "$ref": "#/properties/tree"
                    }
                  ]
                }
              },
              "additionalProperties": false
            }
          },
          "required": [
            "tree"
          ],
          "additionalProperties": false,
          "$schema": "http://json-schema.org/draft-07/schema#"
        }
      }
    }
  ],
  "tool_choice": "auto"
}'

The example above will fail with:

{
  "error": {
    "code": 500,
    "message": "JSON schema conversion failed:\nError resolving ref #/properties/tree/properties/left/anyOf/0: 0 not in [{\"type\":\"string\"},{\"$ref\":\"#/properties/tree\"}]",
    "type": "server_error"
  }
}

This PR adds support for referencing array items.

Since indexes are less unique than object keys, it also renames the grammar rules derived from references.

Currently, the rules are named after the last component of the reference. E.g. #/properties/tree => tree. That doesn't work well with indexes, so instead this PR names them as follows:

1. Extract the content after #.
2. Replace non-alphanumeric characters with a dash -.
3. Prefix with ref

This results in #/properties/tree => ref-properties-tree as the grammar rule name.

@ochafik I would like your opinion on the rule naming. I don't know if there is any additional impact I am not seeing.

Here is the same example against this PR:

{
  "model": "unsloth/gpt-oss-20b",
  "choices": [
    {
      "finish_reason": "tool_calls",
      "index": 0,
      "message": {
        "role": "assistant",
        "reasoning_content": "We need to use the function build_binary_tree. The f...",
        "content": null,
        "tool_calls": [
          {
            "type": "function",
            "function": {
              "name": "build_binary_tree",
              "arguments": "{\"tree\":{\"left\":{\"left\":\"C\",\"right\":\"D\"},\"right\":\"E\"}}"
            },
            "id": "NHd0M0zGWTx1XG6DN2NalUqMT0b8GVb3"
          }
        ]
      }
    }
  ]
}

And the grammar rules generated:

build-binary-tree-args ::= "{" space build-binary-tree-args-tree-kv "}" space
build-binary-tree-args-tree ::= "{" space  (build-binary-tree-args-tree-left-kv build-binary-tree-args-tree-left-rest | build-binary-tree-args-tree-right-kv )? "}" space
build-binary-tree-args-tree-kv ::= "\"tree\"" space ":" space build-binary-tree-args-tree
build-binary-tree-args-tree-left ::= string | build-binary-tree-args-tree-left-1
build-binary-tree-args-tree-left-1 ::= ref-properties-tree
build-binary-tree-args-tree-left-kv ::= "\"left\"" space ":" space build-binary-tree-args-tree-left
build-binary-tree-args-tree-left-rest ::= ( "," space build-binary-tree-args-tree-right-kv )?
build-binary-tree-args-tree-right ::= build-binary-tree-args-tree-right-0 | build-binary-tree-args-tree-right-1
build-binary-tree-args-tree-right-0 ::= string
build-binary-tree-args-tree-right-1 ::= ref-properties-tree
build-binary-tree-args-tree-right-kv ::= "\"right\"" space ":" space build-binary-tree-args-tree-right
build-binary-tree-call ::= "build_binary_tree"channel " <|constrain|>json"? "<|message|>" build-binary-tree-args
build-binary-tree-call0 ::= "build_binary_tree" " <|constrain|>json"? "<|message|>" build-binary-tree-args
channel ::= "<|channel|>" ( "commentary" | "analysis" )
char ::= [^"\\\x7F\x00-\x1F] | [\\] (["\\bfnrt] | "u" [0-9a-fA-F]{4})
recipient-in-channel ::= channel " to=functions." ( build-binary-tree-call0 )
recipient-in-role ::= "<|start|>assistant"? " to=functions." ( build-binary-tree-call )
ref-properties-tree ::= "{" space  (ref-properties-tree-left-kv ref-properties-tree-left-rest | ref-properties-tree-right-kv )? "}" space
ref-properties-tree-left ::= string | ref-properties-tree-left-1
ref-properties-tree-left-1 ::= ref-properties-tree
ref-properties-tree-left-kv ::= "\"left\"" space ":" space ref-properties-tree-left
ref-properties-tree-left-rest ::= ( "," space ref-properties-tree-right-kv )?
ref-properties-tree-right ::= ref-properties-tree-right-0 | ref-properties-tree-right-1
ref-properties-tree-right-0 ::= string
ref-properties-tree-right-1 ::= ref-properties-tree
ref-properties-tree-right-kv ::= "\"right\"" space ":" space ref-properties-tree-right
root ::= recipient-in-role | recipient-in-channel
space ::= | " " | "\n"{1,2} [ \t]{0,20}
string ::= "\"" char* "\"" space

[CISC]

@aldehir Do you need someone to merge for you and/or are you waiting for @ochafik?

[ochafik]

Thanks @aldehir !

Looks good (small nits), no objections re/ naming (looks neater!)

Could you share an example of zod schema that produces def arrays? The spec seems to say defs must be an object (which in json spec doesn't mean array i believe).

[aldehir]

@ochafik thank you for pointing that out, and for the feedback. This stemmed from the following (contrived) example in #16714 (comment):

const SomeObject = z.object({ test: z.string() })

const testType = z.lazy(() =>
  z.object({
    and: z.union([SomeObject, testType]),
    or: z.union([SomeObject, testType]),
    not: z.union([SomeObject, testType])
  })
)

server.registerTool('test',
  {
    title: 'Get test record by ID',
    description: 'Get test record by ID',
    inputSchema: {
      test: testType
    }
  },
  ({ testId }) => {
    return {
      content: [{ type: 'text', text: 'You requested test record ID: ' + testId }]
    }
  }
)

Which produces:

{
  "type": "object",
  "properties": {
    "test": {
      "type": "object",
      "properties": {
        "and": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "test": {
                  "type": "string"
                }
              },
              "required": [
                "test"
              ],
              "additionalProperties": false
            },
            {
              "$ref": "#/properties/test"
            }
          ]
        },
        "or": {
          "anyOf": [
            {
              "$ref": "#/properties/test/properties/and/anyOf/0"
            },
            {
              "$ref": "#/properties/test"
            }
          ]
        },
        "not": {
          "anyOf": [
            {
              "$ref": "#/properties/test/properties/and/anyOf/0"
            },
            {
              "$ref": "#/properties/test"
            }
          ]
        }
      },
      "required": [
        "and",
        "or",
        "not"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "test"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

It does not appear specific to Zod's new toJSONSchema() function in v4, but rather the MCP typescript library which still uses zod v3.

I used a definitions array only to keep the test case simple. I updated it to reference a schema in anyOf instead.

[aldehir]

@CISC, barring any objections, it is ready to merge. I do not have the ability to do so.