Support for JSONSchema custom annotations via arbitrary metadata fields

[jagregory]

The JSONSchema spec has support for arbitrary additional properties, called Custom Annotations. It's recommended these only be x- prefixed because a yet-to-exist future draft will enforce the prefix, but historically these annotations could be any non-reserved keyword. These custom annotations are typically used to provide additional tool-specific metadata about fields or schemas, extra validation or type hints etc. OpenAPI, AsyncAPI encourage the use of x- prefixed annotations.

Right now convertAction specifically picks only a handful of well-known annotations:

https://github.com/fabian-hiller/valibot/blob/ca72ba98f79ef70a80dfc5dc3d978a73ac79ad46/packages/to-json-schema/src/converters/convertAction/convertAction.ts#L260-L271

It would be useful if any arbitary annotations would just be passed-through to the JSONSchema.

So something like this:

pipe(blah, metadata({
  'x-my-annotation': true
});

Would result in a JSONSchema with the annotations included:

"name": {
  "type": "string",
  "x-my-annotation": true
}

See also:

• https://redocly.com/docs/realm/content/api-docs/openapi-extensions
• https://json-schema.org/blog/posts/custom-annotations-will-continue
• https://github.com/json-schema-org/json-schema-spec/blob/main/adr/2023-04-sva-prefix.md
• https://json-schema.org/blog/posts/stable-json-schema#compatibility-with-draft-2020-12