Convert and validate schemas

Use Standard Schema values for validation and JSON Schema conversion.

This page describes the v0 API from v0.5.1. Use v0 package builds with these examples. Install valibot and @valibot/to-json-schema for the schema examples.

npm i xsschema@0.5.1

Why xsSchema?

xsschema uses the Standard Schema contract for validation. It also converts supported schema vendors to JSON Schema.

Compare

The original page compared three packages at specific historical releases. Those releases were xsschema 0.4.0-beta.3, @standard-community/standard-json 0.3.1, and @typeschema/main 0.14.1. The comparison is historical. It does not describe their current releases.

xsschema 0.4.0-beta.3

The historical comparison listed 17 KB and ESM-only output.

@standard-community/standard-json 0.3.1

The historical comparison listed 96 KB and CommonJS support.

@typeschema/main 0.14.1

The historical comparison listed 68 KB and an interface outside Standard Schema.

Coverage

validate works with any Standard Schema-compatible library. Conversion support is a separate contract.

toJsonSchema supports these historical vendor versions:

Implementer	Version(s)	Status
Zod (zod/v4, zod/v4/mini)	v3.25+	Supported
Zod (zod/v3, with zod-to-json-schema)	v3.25+	Supported
Valibot (with @valibot/to-json-schema)	v1.0+	Supported
ArkType	v2.1+	Supported
Effect Schema	v3.16+	Supported
Sury	v10.0+	Supported

Usage

Some xsAI packages depend on xsschema. If your application imports xsschema directly, declare it as a direct dependency.

toJsonSchema

const arktypeSchema = type({
  myString: 'string',
  myUnion: 'number | boolean',
}).describe('My neat object schema')

const arktypeJsonSchema = await toJsonSchema(arktypeSchema)

const effectSchema = Schema.standardSchemaV1( 
  Schema.Struct({
    myString: Schema.String,
    myUnion: Schema.Union(Schema.Number, Schema.Boolean),
  }).annotations({ description: 'My neat object schema' })
)

const effectJsonSchema = await toJsonSchema(effectSchema)

const surySchema = S.schema({
  myString: S.string,
  myUnion: S.union([S.number, S.boolean]),
}).with(S.meta, { description: 'My neat object schema' })

const suryJsonSchema = await toJsonSchema(surySchema)

const valibotSchema = v.pipe(
  v.object({
    myString: v.string(),
    myUnion: v.union([v.number(), v.boolean()]),
  }),
  v.description('My neat object schema'),
)

const valibotJsonSchema = await toJsonSchema(valibotSchema)

const zodSchema = z.object({
  myString: z.string(),
  myUnion: z.union([z.number(), z.boolean()]),
}).describe('My neat object schema')

const zodJsonSchema = await toJsonSchema(zodSchema)

validate

const arktypeSchema = type('string')
const effectSchema = Schema.standardSchemaV1(Schema.String)
const surySchema = S.string
const valibotSchema = v.string()
const zodSchema = z.string()

const arktypeResult = await validate(arktypeSchema, '123')
const effectResult = await validate(effectSchema, '123')
const suryResult = await validate(surySchema, '123')
const valibotResult = await validate(valibotSchema, '123')
const zodResult = await validate(zodSchema, '123')

jsonSchema

Define a JSON Schema.

const schema = jsonSchema({
  properties: {
    productId: {
      description: 'The unique identifier for a product',
      type: 'integer'
    }
  },
  type: 'object'
})

strictJsonSchema

Define a JSON Schema with additionalProperties: false.

const schema = strictJsonSchema({
  properties: {
    productId: {
      description: 'The unique identifier for a product',
      type: 'integer'
    }
  },
  type: 'object'
})

// false
console.log(schema.additionalProperties)

Types

Schema

A type export of StandardSchemaV1 from @standard-schema/spec.

SchemaWithJson

A type export of StandardJSONSchemaV1 from @standard-schema/spec. Use it for schemas that provide JSON Schema directly.

JsonSchema

A type export of JSONSchema7 from @types/json-schema.

Infer (deprecated)

Alias for StandardSchemaV1.Infer.

InferIn (deprecated)

Alias for StandardSchemaV1.InferInput.

Errors

Missing dependencies

Some vendors require an additional package for JSON Schema conversion.

Install the converter for the vendor that you use:

npm i zod-to-json-schema # Zod v3
npm i @valibot/to-json-schema # Valibot

All optional peer dependencies are noted in Coverage.

Unsupported schema vendor

The converter does not support this schema vendor.

The historical contribution policy requires one of these conditions:

• The library has more than 100 GitHub stars.
• The npm package has more than 1,000 weekly downloads.

Result

The examples convert schemas, validate values, and define JSON Schema objects.