Adding support for .example() to document schema examples

[erunion]

I've added a new .example() method that, like .describe(), will allow consumers to document example values and representations of their schemas.

const documentedString = z
  .string()
  .url()
  .example("https://example.com")
  .example("https://example.local");

documentedString.examples; // ["https://example.com", "https://example.local"]

Like the JSON Schema examples array this currently has no type or shape restrictions. It may at some point be nice to restrict content being supplied to .example() to match the schema type (eg. only strings can be supplied on z.string()) but I've not (yet) done that here.

This work is being done to resolve #2266, and should, with a followup change to zod-to-json-schema¹, allow Zod consumers to document schema examples within their generated JSON Schema representations.

Footnotes

1. I plan on submitting a change to support examples to zod-to-json-schema after this work is in. ↩

[samchungy]

I feel that having an any type makes it pretty unusable. It would make it impossible to catch any drift from the schema which is a huge red flag.

The biggest challenge will be whether the input or output should be used in the type definition. Or both?

[erunion]

@samchungy What if instead .example() is moved from being a global like .describe() and instead exists only on primitives?

[maryam-saeidi]

Any update on this feature?

The biggest challenge will be whether the input or output should be used in the type definition.

In which scenario might we want to use the output type? It seems to me the example is for input type, so we can start by using only input.

Btw, we can also provide an example directly to a type definition function, like the following, right?

z.string({
  description: 'An identifier for the resource.',
  example: '9c235211-6834-11ea-a78c-6feb38a34414',
})

Maybe it is worth mentioning it in the documentation.

[samchungy]

In which scenario might we want to use the output type?

In my case, when you're representing a response type. Eg this is the type that it should be after a transform.

[maryam-saeidi]

In my case, when you're representing a response type. Eg this is the type that it should be after a transform.

Since this PR's main focus is related to json-schema example and the OpenAPI Specification, input type seems more relevant. Shall we start with that?

I think if we remove any usage and use the input type, this PR should be ready for review, and hopefully, it will be merged soon. 🤞🏻

[samchungy]

In my case, when you're representing a response type. Eg this is the type that it should be after a transform.

Since this PR's main focus is related to json-schema example and the OpenAPI Specification, input type seems more relevant. Shall we start with that?

I think if we remove any usage and use the input type, this PR should be ready for review, and hopefully, it will be merged soon. 🤞🏻

You can use a JSON Schema to represent a response type too

[maryam-saeidi]

You can use a JSON Schema to represent a response type too

🤔 Do you have an example?

[erunion]

So what should I do here? Move .example() to only exist on primitives? Something else?

[maryam-saeidi]

I like the idea of first covering primitive types and avoiding any.

@colinhacks, do you have any input regarding this feature and the criteria that need to be covered in order to merge this PR?

[samchungy]

You can use a JSON Schema to represent a response type too

🤔 Do you have an example?

The simplest example is any open api schema you can describe a request and response type.