Minimal Schema Compatibility Testing API

[CraigMacomber]

Description

Adds checkSchemaCompatibilitySnapshots, a minimal (in terms of API surface and code needed to use it) API for snapshot based schema compatibility testing.

Reviewer Guidance

The review process is outlined on this wiki page.

[CraigMacomber]

This file (its name) is intentionally backdated to be for version 2.80.0 rather than the current 2.81.0 to ensure that bumping the fluid version does not cause the test using this to fail. This particular domain has not changed in a long time, so this is accurate for what was in it in that version, and since the domain is alpha.

[CraigMacomber]

Here is what using this new testing setup looks like for content inside this package. Quite clean in my opinion.

[CraigMacomber]

Here is the direct usage of checkSchemaCompatibilitySnapshots for testing content in this package. This resembles how other users would use this, though they would get their versions and paths from different places.

Note that nothing here has any opinionated details about what compatibility means or forwards vs back compat or anything like that: this high level API encapsulates all of that, hiding it from uses.

[Copilot]

Pull request overview

This PR adds a minimal API for snapshot-based schema compatibility testing through the new checkSchemaCompatibilitySnapshots function. This utility allows developers to test that schema changes across versions maintain the expected compatibility guarantees for viewing and collaborating with documents created by historical versions.

Changes:

• Added checkSchemaCompatibilitySnapshots function and supporting types (SnapshotFileSystem, SchemaCompatibilitySnapshotsOptions) to enable snapshot-based schema compatibility testing
• Refactored version selection logic in runtime-utils by extracting selectVersionRoundedDown for reuse across the codebase
• Added test infrastructure and helper functions for schema compatibility snapshot testing

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
packages/runtime/runtime-utils/src/index.ts	Exports new selectVersionRoundedDown function
packages/runtime/runtime-utils/src/compatibilityBase.ts	Refactors version selection logic into reusable selectVersionRoundedDown function
packages/dds/tree/src/simple-tree/api/snapshotCompatibilityChecker.ts	Implements core checkSchemaCompatibilitySnapshots API with file system abstraction and validation logic
packages/dds/tree/src/simple-tree/api/tree.ts	Updates documentation to reference new schema compatibility testing API
packages/dds/tree/src/test/snapshots/snapshotTools.ts	Adds testSchemaCompatibilitySnapshots helper and exports regenerateSnapshots flag
packages/dds/tree/src/test/simple-tree/api/snapshotCompatibilityChecker.spec.ts	Comprehensive tests for the new API including workflow examples and edge cases
packages/dds/tree/src/test/jsonDomainSchema.spec.ts	Adds compatibility test for JSON domain schema
packages/dds/tree/src/test/schemaSnapshots/point/*.json	Test snapshot files for Point schema versions
packages/dds/tree/src/test/domain-schema-compatibility-snapshots/json/2.80.0.json	Snapshot file for JSON domain schema
packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md	API surface additions for alpha exports
packages/dds/tree/api-report/tree.alpha.api.md	API surface additions for tree package
packages/dds/tree/.eslintrc.cjs	Ignores schema snapshot directories from linting
biome.jsonc	Ignores schema snapshot JSON files from formatting

[github-actions]

🔗 No broken links found! ✅

Your attention to detail is admirable.

linkcheck output

> [email protected] ci:check-links /home/runner/work/FluidFramework/FluidFramework/docs
> start-server-and-test "npm run serve -- --no-open" 3000 check-links

1: starting server using command "npm run serve -- --no-open"
and when url "[ 'http://127.0.0.1:3000' ]" is responding with HTTP status code 200
running tests using command "npm run check-links"


> [email protected] serve
> docusaurus serve --no-open

[SUCCESS] Serving "build" directory at: http://localhost:3000/

> [email protected] check-links
> linkcheck http://localhost:3000 --skip-file skipped-urls.txt

Crawling...

Stats:
  248787 links
    1796 destination URLs
    2036 URLs ignored
       0 warnings
       0 errors