Skip to content

Schema composability: shared building blocks and team-composed schemas #17

Open

Description

@mindsocket

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.

Relates to #13 (schema reorganization), #15 (strict_ost schema), #9 (team-specific adaptations).

Activity

  1. mindsocket commented on Feb 26, 2026

    @mindsocket
    OwnerAuthor

    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:

    • 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.)

  2. mindsocket commented on Mar 1, 2026

    @mindsocket
    OwnerAuthor

    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.

  3. mindsocket commented on Mar 9, 2026

    @mindsocket
    OwnerAuthor

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions