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:

valibot/packages/to-json-schema/src/converters/convertAction/convertAction.ts

Lines 260 to 271 in ca72ba9

	case 'metadata': {
	if (typeof valibotAction.metadata.title === 'string') {
	jsonSchema.title = valibotAction.metadata.title;
	}
	if (typeof valibotAction.metadata.description === 'string') {
	jsonSchema.description = valibotAction.metadata.description;
	}
	if (Array.isArray(valibotAction.metadata.examples)) {
	jsonSchema.examples = valibotAction.metadata.examples;
	}
	break;
	}

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