Repository navigation
feat(tree): Backport schema discrepancy API and SchemaArtifact telemetry tagging to release/client/2.118 - #28155
Merged
jzaffiro merged 9 commits intoSep 3, 2026
Conversation
…a metadata (microsoft#28090) Cherry-pick of microsoft#28090 from main into release/client/2.118. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: edc4b0db-aab4-4e27-bb42-e90ca8db801d
github-actions
Bot
added
area: tools
area: dds
Contributor
|
Warning WARNING: This PR is targeting a release branch! All changes must first be merged into Changes to release branches require approval from the Patch Triage group before merging. For more details, see our internal documentation for the patch policy and processes for |
Contributor
|
Hi! Thank you for opening this PR. Want me to review it? Based on the diff (2069 lines, 56 files), I've queued these reviewers:
How this works
|
jzaffiro
changed the title
Taylor Williams (taylorsw04)
approved these changes
Sep 2, 2026
jzaffiro
enabled auto-merge (squash)
September 2, 2026 21:38
microsoft#28044) Cherry-pick of microsoft@e4c4fea from main into release/client/2.118. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: edc4b0db-aab4-4e27-bb42-e90ca8db801d
github-actions
Bot
added
area: framework
Joshua Smithrud (Josmithr)
approved these changes
Sep 3, 2026
Tony Murphy (anthony-murphy)
approved these changes
Sep 3, 2026
jzaffiro
disabled auto-merge
September 3, 2026 17:23
jzaffiro
enabled auto-merge (squash)
September 3, 2026 17:29
…#28136) ## Description Simplifies the `TreeView.root` incompatible-schema `UsageError` so its message no longer embeds application-defined schema identifiers or field keys. The incompatibilities are serialized as structured `schemaIncompatibilityDetails` telemetry and tagged as `SchemaArtifact`. The error continues to explain whether callers should initialize the document, upgrade its stored schema, use a compatible view schema, or migrate the schema and data. Tests verify the stable messages and tagged telemetry details for upgradable and non-upgradable schemas. ## Reviewer Guidance The review process is outlined in [the pull request guidelines](../docs/content/Contributing/PR-Guidelines.md#guidelines). Please review the structured telemetry shape and confirm the schema-artifact classification is appropriate for all included values. --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Co-authored-by: Alex Villarreal <716334+alexvy86@users.noreply.github.com>
Adds `TreeViewBeta.compatibility.discrepancies`, which exposes typed
`SchemaDiscrepancy` objects describing differences between the view
schema and stored schema when a beta tree view cannot access the tree. A
new `SchemaCompatibilityStatusBeta` type carries this beta-only
compatibility detail without changing the stable
`SchemaCompatibilityStatus` API.
Each entry includes a `mismatch` discriminator for allowed-type,
field-kind, value-schema, and node-kind differences. Allowed-type
discrepancies include staged types absent from the stored schema in
`stagedView`, while discrepancies on staged optional fields include
`viewIsStagedOptional: true`. Staged-only differences remain compatible
and do not produce discrepancies by themselves.
For example, if the stored schema allows `string` for `Todo.title` but
the view schema expects `number`:
```typescript
const sf = new SchemaFactory("com.example");
class Todo extends sf.object("Todo", {
title: sf.number,
}) {}
const view = asBeta(tree.viewWith(new TreeViewConfiguration({ schema: Todo })));
if (!view.compatibility.canView) {
// [{
// mismatch: "allowedTypes",
// location: { nodeType: "com.example.Todo", fieldKey: "title" },
// view: ["com.fluidframework.leaf.number"],
// stored: ["com.fluidframework.leaf.string"],
// }]
console.error(view.compatibility.discrepancies);
}
```
The `location` identifies the incompatible field, while `view` and
`stored` show the type identifiers allowed by each schema. Applications
can switch on `mismatch` to select the relevant fields when presenting
diagnostics.
Discrepancies and staged-upgrade status are collected during the same
compatibility walk. The discrepancy array remains structured for API
consumers and is JSON-serialized only when attached to schema
incompatibility telemetry. The stable `TreeView` and
`SchemaCompatibilityStatus` APIs remain unchanged.
The review process is outlined in [the pull request
guidelines](../docs/content/Contributing/PR-Guidelines.md#guidelines).
Please review the beta compatibility-status API, typed discrepancy
union, and staged-schema context. This `@beta` API addition requires API
Council approval in addition to area-owner review.
---------
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Wayne Ferrao (WayneFerrao)
approved these changes
Sep 3, 2026
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
github-actions
Bot
added
public api change
jzaffiro
changed the title
## Description Marks `SchemaDiscrepancy` and `SchemaCompatibilityStatusBeta`, introduced in microsoft#28142, as sealed APIs. This communicates that consumers should use these types as returned rather than implementing or extending them. Updates the `@fluidframework/tree` and `fluid-framework` API reports accordingly. ## Reviewer Guidance The review process is outlined in [the pull request guidelines](../docs/content/Contributing/PR-Guidelines.md#guidelines). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
## Description
Updates `TreeView.upgradeSchema()` to include staged schema upgrades
that are already enabled in the document by default. This prevents an
upgrade from attempting to narrow stored schema when another client
previously enabled a staged upgrade.
Applications that need to exclude previously enabled upgrades can
compose an explicit opt-out into their staged upgrade policy:
```typescript
const stagedUpgradePolicy = {
includeAlreadyEnabledUpgrades: false,
...StagedSchemaUpgradePolicy.enabledStagedUpgrades(myUpgrade),
};
```
Adds coverage for staged allowed-type and staged-optional upgrades,
including the explicit opt-out behavior.
## Reviewer Guidance
The review process is outlined in [the pull request
guidelines](../docs/content/Contributing/PR-Guidelines.md#guidelines).
The customer-facing addition is `@alpha` and does not require API
Council approval. Please focus on the policy composition and
compatibility calculations.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Joshua Smithrud (Josmithr)
approved these changes
Sep 3, 2026
Taylor Williams (taylorsw04)
approved these changes
Sep 3, 2026
Contributor
|
🔗 Found some broken links! 💔 Run a link check locally to find them. See Checking for Broken Links for more information. linkcheck output |
Contributor
Bundle size comparisonBase commit: Notable changesNo bundles changed by ≥ 500 bytes parsed. Per-bundle deltas
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Cherry-pick of these changes from
mainintorelease/client/2.118:Reviewer Guidance
The review process is outlined in the pull request guidelines.
This is a straight cherry-pick, no adaptation was needed beyond ensuring the base branch had the prerequisite refactor. See the original PRs for full review discussion.