[Proposal] Include explicit empty properties and required fields for better JSON Schema compatibility

[junkisai]

Summary

I'd like to propose an enhancement to @valibot/to-json-schema that would improve compatibility with various JSON Schema parsers by explicitly including empty properties: {} and required: [] fields in generated schemas, even when they would be empty.

Background

I'm a big fan of valibot and use it extensively across multiple packages in our monorepo.
When integrating with tools like LangChain (which officially supports Zod), I could switch to Zod, but I really want to keep using valibot because:

• We've already built our entire validation layer around valibot
• The consistency of using one validation library across all packages is valuable

However, I discovered that some JSON Schema parsers have stricter expectations about object schema structure than what the specification requires. This led me to manually define schemas instead of using the convenient toJsonSchema function - but I'd love to keep using valibot everywhere!

Current Behavior

When converting a valibot schema with record types:

import * as v from 'valibot'
import { toJsonSchema } from '@valibot/to-json-schema'

const schema = v.object({
  name: v.string(),
  metadata: v.record(v.string(), v.string()),
  tags: v.record(v.string(), v.array(v.string())),
})

const jsonSchema = toJsonSchema(schema)

The generated JSON Schema looks like:

{
  "metadata": {
    "type": "object",
    "additionalProperties": {
      "type": "string"
    }
  },
  "tags": {
    "type": "object",
    "additionalProperties": {
      "type": "array",
      "items": { "type": "string" }
    }
  }
}

Proposed Enhancement

I propose that toJsonSchema should generate:

{
  "metadata": {
    "type": "object",
    "properties": {},
    "required": [],
    "additionalProperties": {
      "type": "string"
    }
  },
  "tags": {
    "type": "object",
    "properties": {},
    "required": [],
    "additionalProperties": {
      "type": "array",
      "items": { "type": "string" }
    }
  }
}

Technical Context

According to the JSON Schema draft-07 specification:

• Omitting "properties" "has the same behavior as an empty object"
• Omitting "required" "has the same behavior as an empty array"

However, in practice, some parsers expect these fields to be explicitly present.

Questions for Discussion

1. Would this change align with the project's goals?
2. Are there any potential downsides to always including these fields?
3. Should this be configurable via an option, or should it be the default behavior?

I'd love to hear the community's thoughts on this proposal!

[fabian-hiller]

Feel free to create a PR and change this. In the meantime you can use our new overrideSchema config in the latest version of toJsonSchema to add these properties when converting a record schema.

[junkisai]

I see, you're right, overrideSchema might solve it!
If not, I'll consider submitting a PR.

[fabian-hiller]

I am happy to answer all your questions about the toJsonSchema config. Feel free to also take a look at the src/types.ts file in the to-json-schema package in our repo.