@winglet/json-schema

yarn add @winglet/json-schema

Utility library for JSON Schema manipulation. Provides depth-first schema traversal with a visitor pattern, $ref resolution, circular reference detection, and schema type-guard functions.

Installation

yarn add @winglet/json-schema

Sub-path Exports

Import path	Contents
@winglet/json-schema	All exports
@winglet/json-schema/scanner	JsonSchemaScanner (synchronous)
@winglet/json-schema/async-scanner	JsonSchemaScannerAsync
@winglet/json-schema/filter	Schema type-guard functions

Key Exports

Schema Scanner

• JsonSchemaScanner — depth-first traversal with enter/exit visitor callbacks
• JsonSchemaScannerAsync — async variant for remote $ref resolution

Schema Filters (/filter)

Type-guard functions for each JSON Schema type:

• isObjectSchema, isArraySchema, isStringSchema, isNumberSchema, isBooleanSchema, isNullSchema
• Nullable/Non-nullable variants: isNonNullableObjectSchema, isNullableObjectSchema, etc.
• isCompatibleSchemaType, isIdenticalSchemaType

Types

• InferValueType<Schema> — infers TypeScript type from a JSON Schema definition

Usage Examples

import { JsonSchemaScanner } from '@winglet/json-schema/scanner';

const schema = {
  type: 'object',
  properties: {
    name: { type: 'string' },
    age:  { type: 'number' },
  },
};

const scanner = new JsonSchemaScanner({
  visitor: {
    enter(entry) {
      console.log(entry.path, entry.schema.type);
    },
  },
});

scanner.scan(schema);
// '' 'object'
// '/properties/name' 'string'
// '/properties/age' 'number'

import { isObjectSchema, isArraySchema } from '@winglet/json-schema/filter';

isObjectSchema({ type: 'object', properties: {} }); // true
isArraySchema({ type: 'array', items: {} });         // true

Claude Code Integration

@winglet/json-schema ships Claude Code assets — the json-schema-skill expert skill and its knowledge base covering schema scanner, filter type guards, and reference resolution — under docs/claude/. They are published alongside the package so AI assistants can reason about schema traversal and $ref handling with package-specific context.

Inject those assets into your local Claude Code environment with @slats/claude-assets-sync (bin: inject-claude-settings):

npx -p @slats/claude-assets-sync inject-claude-settings --package=@winglet/json-schema --scope=user         # inject into ~/.claude (user-level)
npx -p @slats/claude-assets-sync inject-claude-settings --package=@winglet/json-schema --scope=project      # inject into the nearest existing .claude, walking up from cwd

# Preview / overwrite flags
npx -p @slats/claude-assets-sync inject-claude-settings --package=@winglet/json-schema --scope=user --dry-run   # show the plan without writing
npx -p @slats/claude-assets-sync inject-claude-settings --package=@winglet/json-schema --scope=user --force     # overwrite locally-modified files

The CLI resolves @winglet/json-schema/package.json via createRequire, reads its claude.assetPath (docs/claude), and applies hash-based diff into the selected .claude/ (skip unchanged, warn on divergence, require --force to overwrite).

AI Agent Reference

AI Reference

Package: @winglet/json-schema v0.10.0 Purpose: JSON Schema traversal, type-guard filters, and $ref resolution.

Key exports

./scanner → JsonSchemaScanner
            JsonScannerOptions (type)
            SchemaVisitor (type)
            SchemaEntry (type)
./async-scanner → JsonSchemaScannerAsync
                  JsonScannerOptionsAsync (type)
                  SchemaVisitor (type)
                  SchemaEntry (type)
./filter → isArraySchema
           isNonNullableArraySchema
           isNullableArraySchema
           isBooleanSchema
           isNonNullableBooleanSchema
           isNullableBooleanSchema
           isNullSchema
           isNonNullableNumberSchema
           isNullableNumberSchema
           isNumberSchema
           isNonNullableObjectSchema
           isNullableObjectSchema
           isObjectSchema
           isNonNullableStringSchema
           isNullableStringSchema
           isStringSchema
           hasNullInType
           isCompatibleSchemaType
           isIdenticalSchemaType