Skip to content

Require the Search Schema everywhere below it, and delete the schema-less degraded modes #767

Description

@ddeboer

What

Make the Search Schema a required, non-nullable argument everywhere below the schema on the write side, and delete the schema-less degraded modes it currently guards:

  • physicalFields(field, schema) – the trigger for this issue: since feat(search): narrow a reference’s facet to the keys its target admits #765 the physical fanout is a function of (field, schema), not of the declaration alone (a facetable reference inheriting a facet policy facets its ${name}_facet companion, which only the schema can resolve).
  • projectDocument(node, type, schema, context?) – drops the degraded reading “without a schema: no inline nesting, no re-keying, no facet companion”.
  • buildCollectionDefinition(type, { schema, … }) – its two “needs the schema” throws for surfaced inline and joinable references disappear: what they guard becomes statically guaranteed.
  • BuildSearchParamsOptions.schema – the compiler stops silently faceting the field itself and tokenising membership when the option is unset.
  • The rebuild writers’ options (RebuildOptions), so new InPlaceRebuild(client, type) becomes new InPlaceRebuild(client, type, { schema }) – which the provenance-sweep guard added in feat(search): narrow a reference’s facet to the keys its target admits #765 already wants in order to do its job fully.

projectRoots and parseSearchResponse already require the schema; this extends their philosophy – “a function of the whole schema, exactly as the engine is” (the parseSearchResponse JSDoc) – to the rest of the surface, instead of leaving the package with two philosophies side by side.

Why

  • The degraded modes have no user. No production path projects or builds a collection definition schema-less: the pipeline goes through projectRoots (schema required), and the engine, indexer and writers all hold one. The modes serve tests and a hypothetical library caller, for whom the ceremony after this change is one call: projectDocument(node, place, searchSchema(place)).
  • Deleting the modes removes concepts rather than policing them. No “without a schema, X silently does not happen” caveats to document, no schema === undefined branches to cover, and the silently wrong physical field name bug class ceases to exist instead of becoming visible. feat(search): narrow a reference’s facet to the keys its target admits #765’s review caught a live instance of that class (the provenance-sweep guard judging facet status from the declaration); a required schema is the structural form of that fix.

Rejected: required-but-nullable

physicalFields(field, schema: SearchSchema | undefined) – every caller must write the argument, undefined stays legal. Considered first (and a smaller diff), but it keeps all three degraded modes and adds explicitness on top, and it is a second breaking change on the road to the same end state. If we pay a ! at all, pay it once for the simpler surface.

Scope and costs

  • Two breaking commits: feat(search)! and feat(search-typesense)! (zero-major scheme: minor bumps).
  • Mechanical test churn: ~70+ schema-less projectDocument/buildCollectionDefinition/physicalFields call sites gain a searchSchema(type) wrap.
  • One edge to watch: searchSchema validates, so a test fixture that deliberately projects a type validation would reject needs rethinking.
  • documentKeyOf, validateSearchType and the other pre-schema entry points are untouched – they are deliberately schema-free.

Activity

  1. added theissue type on Aug 24, 2026
  2. changed the title [-]Require the schema argument on physicalFields, nullable[/-] [+]Require the Search Schema everywhere below it, and delete the schema-less degraded modes[/+] on Aug 24, 2026
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

    No labels
    No labels

    Type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions