@sanity/schema-descriptor-utils

Convert Lexicon schema descriptors into Sanity schema definitions.

Installation

pnpm add @sanity/schema-descriptor-utils

Note: This is a private @sanity-scoped package. Requires npm registry authentication.

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.

Types

import type {SchemaTypeDefinition} from 'sanity'

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

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.

Requirements

• Node.js ≥ 24
• pnpm