anthropics / anthropics/anthropic-sdk-typescript

transformJSONSchema drops $defs when the schema root is a $ref

Aberta Para iniciantes
#1,162 0 comentários 0 reações 0 responsáveis Ver no GitHub
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

Abrir o 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

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.