anthropics / anthropics/anthropic-sdk-typescript
transformJSONSchema drops $defs when the schema root is a $ref
- Linguagem predominante
- TypeScript
- Estrelas
- 2.1k
- Forks
- 403
- Merge médio
- 1d 21h
- PRs com merge (30d)
- 8
Descrição
### Summary
`transformJSONSchema` drops `$defs` when the schema root is a `$ref`, leaving the reference dangling.
`$ref` is popped and returned before `$defs` is ever read ([`src/lib/transform-json-schema.ts#L31-L44`](https://github.com/anthropics/anthropic-sdk-typescript/blob/main/src/lib/transform-json-schema.ts#L31-L44)):
```ts
const ref = pop(jsonSchema, '$ref');
if (ref !== undefined) {
strictSchema['$ref'] = ref;
return strictSchema; // returns before the $defs block below
}
const defs = pop(jsonSchema, '$defs');
```
### Reproduction
No API key, no network — this is local schema normalisation.
```console
$ npm i @anthropic-ai/sdk@0.120.0
```
```js
import { transformJSONSchema } from '@anthropic-ai/sdk/lib/transform-json-schema';
transformJSONSchema({
$ref: '#/$defs/Item',
$defs: { Item: { type: 'object', properties: { a: { type: 'string' } } } },
});
```
```
{ "$ref": "#/$defs/Item" }
```
The definitions are gone, so `#/$defs/Item` resolves to nothing.
### Why this shape shows up
It is what pydantic's `RootModel` and `zod-to-json-schema` emit for a top-level model — the root is a `$ref` and the definitions sit beside it. A `$ref` nested inside `properties` is unaffected; only the root case is.
### The Python SDK already fixed this
Same defect, same function, fixed in [anthropics/anthropic-sdk-python#1642](https://github.com/anthropics/anthropic-sdk-python/pull/1642) (merged 2026-06-04) by moving `$defs` processing above the `$ref` early-return. The Python source still carries the comment explaining why the order matters.
Same input, the two official SDKs today:
| | Python 1.0.0 | TypeScript 0.120.0 |
|---|---|---|
| `{"$ref": "#/$defs/Item", "$defs": {...}}` | definitions preserved | **definitions dropped** |
### Environment
- `@anthropic-ai/sdk@0.120.0` (published package, verified directly)
- also present on `main` at `bfa9197`
- Node 23
PR attached.
Guia de contribuição
Direção de pesquisa
Start in src/lib/transform-json-schema.ts, especially the $ref and $defs handling around lines 31-44, and run the local reproduction from the issue. Done means a root $ref retains its accompanying $defs so the reference resolves, while nested $ref behavior remains unchanged; add or update focused coverage for both cases.
Escrita pelo modelo de indexação a partir do texto da issue.
Avaliação
- Stack de tecnologia
- typescript
- Domínio
- api
- Tipo de issue
- Bug
- Dificuldade
- 2/5
- Tempo estimado
- 1-3 horas
- Status de atividade
- Ativa
- Clareza
- Claramente especificada
- Facilidade para iniciantes
- 88/100