@sanity/schema-descriptor-utils

Convert Lexicon schema descriptors into Sanity schema definitions.

Installation

pnpm add @sanity/schema-descriptor-utils

Usage

import {convertToDefinition} from '@sanity/schema-descriptor-utils'
import {createSchema} from 'sanity'

// Fetch a schema descriptor from the Lexicon API
const res = await fetch(`https://api.sanity.io/v1/descriptors/schemas/${descriptorId}`)
const descriptor = await res.json()

// Convert to Sanity schema definitions
const {types} = convertToDefinition(descriptor, {format: 'plain'})

// Compile into a usable schema
const schema = createSchema({name: 'default', types})

Formats

The format option controls how the output is shaped:

• plain (default) — preserves validation rules as raw descriptor JSON. Use when you need the schema structure but handle validation separately.
• createSchema — produces output that can be passed directly to createSchema(). Strips validation and adds dummy fields for cross-dataset/global document references.
• manifest — produces schema definitions with validation serialized as Sanity manifest rule specs. Pass this through createSchemaFromManifestTypes() to compile manifest validation into Studio-compatible validation functions.

import {createSchemaFromManifestTypes} from '@sanity/schema/_internal'
import {convertToDefinition} from '@sanity/schema-descriptor-utils'
import {defineConfig, type SchemaTypeDefinition} from 'sanity'

type ManifestSchemaWithOriginal = ReturnType<typeof createSchemaFromManifestTypes> & {
  _original: {types: SchemaTypeDefinition[]}
}

const manifestDefinition = convertToDefinition(descriptor, {format: 'manifest'})
const manifestSchema = createSchemaFromManifestTypes(
  manifestDefinition,
) as ManifestSchemaWithOriginal
const schemaTypes = manifestSchema._original.types

export default defineConfig({
  schema: {
    types: schemaTypes,
  },
})

Types

import type {createSchemaFromManifestTypes} from '@sanity/schema/_internal'
import type {SchemaTypeDefinition} from 'sanity'

interface SchemaSummary {
  types: Record<string, TypeDef>
  hoisted: Record<string, unknown>
  registries: string[]
}

type ManifestDefinition = Parameters<typeof createSchemaFromManifestTypes>[0]

function convertToDefinition(input: SchemaSummary, opts: {format: 'manifest'}): ManifestDefinition

function convertToDefinition(
  input: SchemaSummary,
  opts?: {format?: 'createSchema' | 'plain'},
): {name: string; types: Array<SchemaTypeDefinition>}

SchemaSummary matches the response shape from GET /v1/descriptors/schemas/{descriptorId}.

Build

Outputs ESM and .d.ts type declarations via @sanity/pkg-utils.

pnpm build     # Build all formats
pnpm test      # Run tests
pnpm typecheck # Type-check without emitting

Validation note

Descriptor validation format differs from the manifest format used by @sanity/schema. See the descriptor validation types for details.

manifest format converts descriptor validation rules to the manifest validation format used by createSchemaFromManifestTypes(). Rules that cannot be represented by the manifest compiler are omitted: composed rules (allOf/anyOf), datetime, field references, and numeric-only constraints with non-numeric values. Localized validation messages cannot be represented by the manifest compiler, so the validation rule is preserved without the message.

Requirements

• Node.js ≥ 24
• pnpm