Composition

Validation modes: Validation modes reference

Compose provides static methods for deriving new schemas from existing ones. All methods return new schema objects - input schemas are never mutated. The TypeScript types are inferred at compile time; the output is valid JSON Schema at runtime.

Which one do I want

Several methods look similar because they share the same allOf-shaped output or the same "is-a" framing. Pick by what you're actually trying to say:

• Adding fields to a base schema? Use extend. It's the default choice for "I have a base and I want a few more fields."
• Need multi-parent taxonomy, or want the ontology to read as explicit classification? Use subClassOf instead of extend - same allOf + $ref wire shape, but it accepts multiple parents and signals "is-a" rather than "has more fields."
• Need every constituent schema's required constraints enforced simultaneously, with all of them inlined (not just referenced)? Use intersection.
• Need a semantic alias with identical structure (a domain-specific name for a shared primitive, no new fields, no new constraints)? Use equivalent. If the two schemas differ structurally at all, equivalent is the wrong tool - reach for extend or a standalone schema instead.

In short: extend, intersection, and subClassOf all produce allOf-shaped output, but differ in cardinality (single vs. multi-parent) and in whether the base is referenced or fully inlined. equivalent, subClassOf, and extend are all "is-a"-adjacent, but only equivalent requires byte-for-byte structural identity.

Core composition operations

Method	Description	Mode
extend	Add properties to a base schema	Compile-time + Runtime
pick / omit	Keep or remove specific properties	Compile-time + Runtime
partial / required	Make all properties optional or required	Compile-time + Runtime
intersection	Combine schemas with allOf	Compile-time + Runtime
discriminatedUnion / narrow	oneOf with type discriminator	Compile-time + Runtime
getDefaults	Extract declared default values	Runtime
equivalent	Declare two schemas as semantically equivalent	Compile-time

OWL class axioms (opt-in)

Method	Description	Mode
subClassOf	OWL subclass axiom	Compile-time
disjointWith	OWL disjoint-class axiom	Compile-time + Runtime
complementOf	OWL complement axiom	Compile-time
restrictions	OWL property restrictions	Compile-time

All examples use the bookstore domain. Composed schemas build on each other - see Getting Started for the basics.

Related

• set - register composed schemas before use
• instantiate - coerce values through composed schemas
• materialize - fill defaults through composed schemas

See also

• Bookstore domain - base schemas used throughout composition examples
• Argument conventions - how composed schemas work as SchemaRef
• Graph-native authoring - when to extract vs compose