You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Schema composability: shared building blocks and team-composed schemas #17
Architecture for composable schemas so teams can express their specific model without forking the core schema files.
Context
The schema reorganization (#13) introduces schemas/_shared.json with common $defs, and strict_ost.json (#15) demonstrates a schema that selects a subset of entity types with tighter rules. These are already a form of composability. This issue tracks the broader design.
Vision
A team should be able to say: "I want the general entity types, but with RICE scoring fields on opportunities and strict parent validation for solutions" — and compose that schema from building blocks rather than duplicating and editing general.json.
Possible building blocks:
RICE / ICE scoring field sets
confidence field
Strict parentage rules for specific entity types
Custom status enums
Questions to explore
What's the right JSON Schema composition mechanism? (allOf with $ref overlays, unevaluatedProperties, schema inheritance patterns?)
Where do building blocks live? (schemas/blocks/?)
How does a team add custom blocks without modifying core files?
What's the boundary between "composable building block" and "just write your own schema"?
Approach
Don't over-engineer early. Let concrete needs drive the design. The immediate value is in the shared $defs and the two explicit schemas. Revisit this issue when a third distinct schema is needed and repetition becomes a real problem.
Rules (from #16) could form a shared library — defined once, enabled or disabled per composed schema, similar to how linters work (think ESLint configs). Good-practice rules would be on by default; a team or schema can opt out of specific rules that don't fit their context.
Example: a rule like "only one opportunity active at a time" is in the shared rule library and enabled by default in strict_ost. A team's composed schema might disable it because their workflow intentionally tracks multiple parallel opportunities.
This framing means:
The shared rule library is the canonical source of what "good" looks like
Individual schemas declare which rules apply (or override defaults)
Rule enablement config could live in the schema itself or alongside it
This makes "composable schemas" more than just mixing entity types and field definitions — the rule set is also a composable dimension.
(Deliberately not opening the can of worms on rule categories and severity levels for now.)
A key element remaining in the scope of this issue is composable rules - currently metadata is only taken from one schema file and overwrites any others.
This issue depends on #33 (Support full cross-schema resolution of refs) - we need to be able to resolve references across schema files before we can implement shared building blocks and team-composed schemas.
Activity
mindsocket commentedon Feb 26, 2026
Bonus idea connecting #8 and #16:
Rules (from #16) could form a shared library — defined once, enabled or disabled per composed schema, similar to how linters work (think ESLint configs). Good-practice rules would be on by default; a team or schema can opt out of specific rules that don't fit their context.
Example: a rule like "only one opportunity active at a time" is in the shared rule library and enabled by default in
strict_ost. A team's composed schema might disable it because their workflow intentionally tracks multiple parallel opportunities.This framing means:
This makes "composable schemas" more than just mixing entity types and field definitions — the rule set is also a composable dimension.
(Deliberately not opening the can of worms on rule categories and severity levels for now.)
mindsocket commentedon Mar 1, 2026
A key element remaining in the scope of this issue is composable rules - currently metadata is only taken from one schema file and overwrites any others.
mindsocket commentedon Mar 9, 2026
This issue depends on #33 (Support full cross-schema resolution of refs) - we need to be able to resolve references across schema files before we can implement shared building blocks and team-composed schemas.
feat(schema): support plugin-contributed schemas and partials