Welcome to SigilJS Discussions!

[weipertda]

Hey everyone! Welcome to the SigilJS discussions page.

SigilJS is an early-stage JavaScript project exploring a simple but important idea:

Executable data contracts for JavaScript.

The goal is to let developers define structure once, then use that structure for runtime validation, parsing, transformation, documentation, and future projections such as JSON Schema, TypeScript, and OpenAPI.

In other words:

Define structure once. Project it everywhere.

What is SigilJS?

SigilJS is a runtime contract system for JavaScript.

A sigil is not just a passive schema. It is intended to be a contract object. Something your program can use to understand, enforce, transform, and eventually project data across system boundaries.

Example:

import { sigil, optional, oneOf, union } from '@weipertda/sigiljs';

const User = sigil.exact({
  id: union(String, Number),
  name: String,
  role: oneOf('admin', 'user'),
  age: optional(Number)
});

const result = User.safeParse({
  id: 1,
  name: 'Alex',
  role: 'admin'
});

SigilJS is meant for places where runtime data crosses a boundary:

• API requests
• API responses
• Config files
• Database reads/writes
• Forms
• Events
• Queues
• Webhooks
• Plugin systems
• Local storage
• AI tool calls
• LLM structured outputs

The deeper idea is:

Unknown data should become trusted runtime data before the rest of your application depends on it.

Why build this?

JavaScript has always had a gap between the structures we expect and the data we actually receive at runtime.

TypeScript helps tremendously during development, but runtime data still needs to be checked when it enters the system.

SigilJS is exploring a contract-first approach:

Define → Enforce → Transform → Project

Define

Declare structure in plain JavaScript.

Enforce

Validate, parse, and assert runtime data.

Transform

Normalize data into a trusted shape.

Project

Generate other structural representations from the same contract.

Projection is the part that makes this more than a validation library.

The long-term vision is that one contract could eventually support:

• Runtime validation
• Path-aware errors
• JSON Schema projection
• TypeScript definition generation
• OpenAPI projection
• Contract diffs
• Test fixtures
• AI structured-output enforcement
• Boundary-specific adapters

Current status

SigilJS is early and evolving quickly.

The package is currently published as:

bun add @weipertda/sigiljs

or:

npm install @weipertda/sigiljs

The project is not trying to be “Zod, but different syntax.”

Zod is excellent and mature.

SigilJS is exploring a different direction:

Zod: Builder-style validation API
SigilJS: Executable contract objects with projection as a core goal

What kind of feedback is welcome?

I would especially love feedback on:

1. API design

• Does the sigil({...}) syntax feel natural?
• Are parse, safeParse, and assert the right enforcement methods?
• Are helpers like optional, union, and oneOf clear?

2. Contract model

• Does the contract object idea make sense?
• What should describe() output look like?
• What should be considered stable vs internal?

3. Projection

• What would you expect from toJSONSchema()?
• What would you expect from toTypeScript()?
• What would you expect from toOpenAPI()?

4. Boundary use cases

• Where would this be most useful in real apps?
• API requests?
• Webhooks?
• Config files?
• AI structured outputs?
• Something else?

5. Naming and positioning

• Does “executable data contracts” make sense?
• Is “contract object” clear?
• Is the positioning too broad, or does it feel accurate?

Discussion categories I’d like to see

Please feel free to start discussions around:

• Ideas
• Questions
• API feedback
• Bug reports
• Projection behavior
• Boundary examples
• AI structured-output use cases
• Comparisons with existing tools
• Docs improvements
• Roadmap suggestions

Closing thought

SigilJS is still early, but the goal is serious:

Build a small, JavaScript-native contract layer for runtime data.

Not just validation. Not just schemas.

Executable contracts that can define, enforce, transform, and project structure across the places where real applications meet uncertain data.

Thanks for checking it out. I’d love your thoughts. 😎