{"record":{"id":"267e00dbf886ddf8","repo":"vercel/ai","slug":"google-schema-conversion-only-supports-references","errorCode":null,"errorMessage":"Google schema conversion only supports references to direct children of root-level $defs or definitions.","messagePattern":"Google schema conversion only supports references to direct children of root-level \\$defs or definitions\\.","errorType":"exception","errorClass":"UnsupportedFunctionalityError","httpStatus":null,"severity":"error","filePath":"packages/google/src/convert-json-schema-to-openapi-schema.ts","lineNumber":313,"sourceCode":"\n  const definitionName = decodedDefinitionName.replace(/~[01]/g, match =>\n    match === '~1' ? '/' : '~',\n  );\n\n  if (\n    !Object.prototype.hasOwnProperty.call(source.definitions, definitionName)\n  ) {\n    throwUnsupportedReference(reference);\n  }\n\n  return {\n    definition: source.definitions[definitionName],\n    referenceKey: `${source.prefix}${definitionName}`,\n  };\n}\n\nfunction throwUnsupportedReference(reference: string): never {\n  throw new UnsupportedFunctionalityError({\n    functionality: `JSON Schema reference: ${reference}`,\n    message:\n      'Google schema conversion only supports references to direct children of root-level $defs or definitions.',\n  });\n}\n\ntype EnumValues = NonNullable<JSONSchema7['enum']>;\ntype EnumType = 'string' | 'number' | 'integer' | 'boolean';\ntype GoogleEnumSchema = {\n  type?: JSONSchema7['type'];\n  enum?: JSONSchema7['enum'];\n  format?: JSONSchema7['format'];\n  anyOf?: JSONSchema7['anyOf'];\n  nullable?: boolean;\n};\n\nfunction addEnumToSchema({\n  values,","sourceCodeStart":295,"sourceCodeEnd":331,"githubUrl":"https://github.com/vercel/ai/blob/69428b1f8b037e4d118fb4853428d5c4e620493c/packages/google/src/convert-json-schema-to-openapi-schema.ts#L295-L331","documentation":"The Google schema converter only resolves `$ref` pointers that target a definition directly under the root-level `$defs` (or `definitions`) object, e.g. `#/$defs/Foo`. Any other reference form (nested paths, anchors, external refs, or refs to sub-properties) cannot be mapped to Google's flat OpenAPI schema and throws UnsupportedFunctionalityError via throwUnsupportedReference.","triggerScenarios":"A JSON Schema with `$ref: '#/$defs/Foo/properties/bar'`, `$ref: '#/definitions/A/B'`, relative or external `$ref`s, or definitions nested inside other definitions, passed to a Google model for tool/structured output conversion.","commonSituations":"Hand-edited JSON Schemas with nested refs; schemas generated by tools that emit deep pointer refs; schemas ported from OpenAPI documents with component-internal references.","solutions":["Hoist every referenced type to the top-level `$defs`/`definitions` object and reference it as `#/$defs/Name`.","Inline the referenced sub-schema directly where the ref occurs.","Run a pre-processing step (e.g. with a $ref bundler like @apidevtools/json-schema-ref-parser) to normalize refs before passing to the model."],"exampleFix":"// before\n{ \"type\": \"object\", \"properties\": { \"bar\": { \"$ref\": \"#/$defs/Foo/properties/bar\" } }, \"$defs\": { \"Foo\": { \"properties\": { \"bar\": { \"type\": \"string\" } } } } }\n// after\n{ \"type\": \"object\", \"properties\": { \"bar\": { \"$ref\": \"#/$defs/Bar\" } }, \"$defs\": { \"Bar\": { \"type\": \"string\" } } }","handlingStrategy":"validation","validationCode":"function refsAreDirectChildren(schema) {\n  const allowed = new Set(Object.keys(schema?.$defs ?? schema?.definitions ?? {}).map(k => `#/$defs/${k}`));\n  const refs = JSON.stringify(schema).match(/\"\\$ref\"\\s*:\\s*\"([^\"]+)\"/g) ?? [];\n  return refs.every(r => { const v = JSON.parse(r.replace(/^\"\\$ref\"\\s*:\\s*/, '')); return allowed.has(v); });\n}","typeGuard":"function hasOnlyRootLevelRefs(schema) {\n  const keys = new Set(Object.keys(schema.$defs ?? {}));\n  const walk = (node) => node === null || typeof node !== 'object' ? true\n    : (typeof node.$ref === 'string' ? /^#\\/\\$defs\\/[\\w-]+$/.test(node.$ref) && keys.has(node.$ref.split('/')[2]) : Object.values(node).every(walk));\n  return walk(schema);\n}","tryCatchPattern":"try {\n  await generateObject({ model: googleModel, schema });\n} catch (e) {\n  if (e?.message?.includes('direct children of root-level $defs')) {\n    // normalize refs (inline or hoist) and retry\n  } else throw e;\n}","preventionTips":["Always place referenced types directly under top-level $defs.","Use `$ref: '#/$defs/Name'` form only - no nested pointers, anchors, or external refs.","Bundle/normalize schemas with json-schema-ref-parser before sending to Google."],"tags":["google","json-schema","ref","schema-conversion"],"backgroundTag":"unsupported-json-schema-ref","analyzedSha":"69428b1f8b037e4d118fb4853428d5c4e620493c","analyzedAt":"2026-08-30T12:32:21.016Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}