Describe

Every schema builder supports .describe(text). This attaches a human-readable description to the schema as metadata only — it has no effect on validation, but it is accessible via .introspect().description and is automatically emitted as the description field by toJsonSchema() (including nested properties).

import { object, string, number } from '@cleverbrush/schema';
import { toJsonSchema } from '@cleverbrush/schema-json';

const ProductSchema = object({
    id:    string().uuid().describe('Unique product identifier'),
    name:  string().nonempty().describe('Display name shown to customers'),
    price: number().positive().describe('Price in USD')
}).describe('A product in the catalogue');

// Read description back at runtime
console.log(ProductSchema.introspect().description);
// 'A product in the catalogue'

// toJsonSchema emits description fields automatically
const schema = toJsonSchema(ProductSchema, { $schema: false });
// {
//   type: 'object',
//   description: 'A product in the catalogue',
//   properties: {
//     id:    { type: 'string', format: 'uuid', description: 'Unique product identifier' },
//     name:  { type: 'string', minLength: 1,   description: 'Display name shown to customers' },
//     price: { type: 'number', exclusiveMinimum: 0, description: 'Price in USD' }
//   }
// }

// Chains naturally with all other modifiers — order does not matter
const field = string().optional().describe('Optional note').minLength(1);