Skip to content

Commit c6e182f

Browse files
authored
Merge pull request #3506 from hey-api/docs/zod-valibot-metadata
docs: expand metadata section for zod and valibot
2 parents 5eb2996 + 334954b commit c6e182f

3 files changed

Lines changed: 100 additions & 3 deletions

File tree

docs/openapi-ts/plugins/valibot.md

Lines changed: 35 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -178,7 +178,7 @@ You can customize the naming and casing pattern for `definitions` schemas using
178178

179179
## Metadata
180180

181-
It's often useful to associate a schema with some additional [metadata](https://valibot.dev/api/metadata/) for documentation, code generation, AI structured outputs, form validation, and other purposes. If this is your use case, you can set `metadata` to `true` to generate additional metadata about schemas.
181+
It's often useful to associate a schema with some additional [metadata](https://valibot.dev/api/metadata/) for documentation, code generation, AI structured outputs, form validation, and other purposes. You can set `metadata` to `true` to attach descriptions to schemas when available.
182182

183183
::: code-group
184184

@@ -207,6 +207,40 @@ export default {
207207

208208
:::
209209

210+
For more control over metadata, you can provide your own function. It receives the source `schema`, the target `node` object, and the `$` builder for populating metadata.
211+
212+
::: code-group
213+
214+
```ts [example]
215+
export const vFoo = v.pipe(
216+
v.string(),
217+
v.metadata({
218+
hasTitle: false,
219+
createdAt: 1735732800000,
220+
}),
221+
);
222+
```
223+
224+
```js [config]
225+
export default {
226+
input: 'hey-api/backend', // sign up at app.heyapi.dev
227+
output: 'src/client',
228+
plugins: [
229+
// ...other plugins
230+
{
231+
name: 'valibot',
232+
metadata({ $, node, schema }) {
233+
// [!code ++]
234+
node.prop('hasTitle', $.literal(Boolean(schema.title))); // [!code ++]
235+
node.prop('createdAt', $.literal(Date.now())); // [!code ++]
236+
}, // [!code ++]
237+
},
238+
],
239+
};
240+
```
241+
242+
:::
243+
210244
## Resolvers
211245

212246
You can further customize this plugin's behavior using [resolvers](/openapi-ts/plugins/concepts/resolvers).

docs/openapi-ts/plugins/zod.md

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -238,7 +238,7 @@ export default {
238238

239239
## Metadata
240240

241-
It's often useful to associate a schema with some additional [metadata](https://zod.dev/metadata) for documentation, code generation, AI structured outputs, form validation, and other purposes. If this is your use case, you can set `metadata` to `true` to generate additional metadata about schemas.
241+
It's often useful to associate a schema with some additional [metadata](https://zod.dev/metadata) for documentation, code generation, AI structured outputs, form validation, and other purposes. You can set `metadata` to `true` to attach descriptions to schemas when available.
242242

243243
::: code-group
244244

@@ -264,6 +264,37 @@ export default {
264264

265265
:::
266266

267+
For more control over metadata, you can provide your own function. It receives the source `schema`, the target `node` object, and the `$` builder for populating metadata.
268+
269+
::: code-group
270+
271+
```ts [example]
272+
export const zFoo = z.string().register(z.globalRegistry, {
273+
hasTitle: true,
274+
createdAt: 1735732800000,
275+
});
276+
```
277+
278+
```js [config]
279+
export default {
280+
input: 'hey-api/backend', // sign up at app.heyapi.dev
281+
output: 'src/client',
282+
plugins: [
283+
// ...other plugins
284+
{
285+
name: 'zod',
286+
metadata({ $, node, schema }) {
287+
// [!code ++]
288+
node.prop('hasTitle', $.literal(Boolean(schema.title))); // [!code ++]
289+
node.prop('createdAt', $.literal(Date.now())); // [!code ++]
290+
}, // [!code ++]
291+
},
292+
],
293+
};
294+
```
295+
296+
:::
297+
267298
## Types
268299

269300
In addition to Zod schemas, you can generate schema-specific types. These can be generated for all schemas or for specific resources.

docs/openapi-ts/plugins/zod/mini.md

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -249,7 +249,7 @@ export default {
249249

250250
## Metadata
251251

252-
It's often useful to associate a schema with some additional [metadata](https://zod.dev/metadata) for documentation, code generation, AI structured outputs, form validation, and other purposes. If this is your use case, you can set `metadata` to `true` to generate additional metadata about schemas.
252+
It's often useful to associate a schema with some additional [metadata](https://zod.dev/metadata) for documentation, code generation, AI structured outputs, form validation, and other purposes. You can set `metadata` to `true` to attach descriptions to schemas when available.
253253

254254
::: code-group
255255

@@ -276,6 +276,38 @@ export default {
276276

277277
:::
278278

279+
For more control over metadata, you can provide your own function. It receives the source `schema`, the target `node` object, and the `$` builder for populating metadata.
280+
281+
::: code-group
282+
283+
```ts [example]
284+
export const zFoo = z.string().register(z.globalRegistry, {
285+
hasTitle: true,
286+
createdAt: 1735732800000,
287+
});
288+
```
289+
290+
```js [config]
291+
export default {
292+
input: 'hey-api/backend', // sign up at app.heyapi.dev
293+
output: 'src/client',
294+
plugins: [
295+
// ...other plugins
296+
{
297+
name: 'zod',
298+
compatibilityVersion: 'mini',
299+
metadata({ $, node, schema }) {
300+
// [!code ++]
301+
node.prop('hasTitle', $.literal(Boolean(schema.title))); // [!code ++]
302+
node.prop('createdAt', $.literal(Date.now())); // [!code ++]
303+
}, // [!code ++]
304+
},
305+
],
306+
};
307+
```
308+
309+
:::
310+
279311
## Types
280312

281313
In addition to Zod schemas, you can generate schema-specific types. These can be generated for all schemas or for specific resources.

0 commit comments

Comments
 (0)