SchemaCompatibilityStatus Interface
Packages > @fluidframework/tree > SchemaCompatibilityStatus
Information about a view schema’s compatibility with the document’s stored schema.
See SharedTree’s README for more information about choosing a compatibility policy.
Signature
/** @sealed */
export interface SchemaCompatibilityStatus
Properties
Property | Modifiers | Type | Description |
---|---|---|---|
canInitialize |
readonly
|
boolean |
True iff the document is uninitialized (i.e. it has no schema and no content). To initialize the document, call initialize(content). |
canUpgrade |
readonly
|
boolean | True iff the view schema supports all possible documents permitted by the stored schema. When true, it is valid to call upgradeSchema() (though if the stored schema is already an exact match, this is a no-op). |
canView |
readonly
|
boolean |
Whether the current view schema is sufficiently compatible with the stored schema to allow viewing tree data. If false, root will throw upon access.
Currently, this field is true iff Be aware that even with these SharedTree limitations fixed, application logic may not correctly tolerate the documents allowable by the stored schema! Application authors are encouraged to read docs/user-facing/schema-evolution.md and choose a schema compatibility policy that aligns with their application's needs. |
isEquivalent |
readonly
|
boolean | Whether the view schema allows exactly the same set of documents as the stored schema. |
Property Details
canInitialize
True iff the document is uninitialized (i.e. it has no schema and no content).
To initialize the document, call initialize(content) .
Signature
readonly canInitialize: boolean;
Type: boolean
Remarks
It’s not necessary to check this field before calling initialize(content)
in most scenarios; application authors typically know from context that they’re in a flow which creates a new SharedTree
and would like to initialize it.
canUpgrade
True iff the view schema supports all possible documents permitted by the stored schema. When true, it is valid to call upgradeSchema() (though if the stored schema is already an exact match, this is a no-op).
Signature
readonly canUpgrade: boolean;
Type: boolean
canView
Whether the current view schema is sufficiently compatible with the stored schema to allow viewing tree data. If false, root will throw upon access.
Currently, this field is true iff isEquivalent
is true. Do not rely on this: there are near-term plans to extend support for viewing documents when the stored schema contains additional optional fields not present in the view schema. The other two types of backward-compatible changes (field relaxations and addition of allowed field types) will eventually be supported as well, likely through out-of-schema content adapters that the application can provide alongside their view schema.
Be aware that even with these SharedTree limitations fixed, application logic may not correctly tolerate the documents allowable by the stored schema! Application authors are encouraged to read docs/user-facing/schema-evolution.md and choose a schema compatibility policy that aligns with their application’s needs.
Signature
readonly canView: boolean;
Type: boolean
Remarks
When the documents allowed by the view schema is a strict superset of those by the stored schema, this is false because writes to the document using the view schema could make the document violate its stored schema. In this case, the stored schema could be updated to match the provided view schema, allowing read-write access to the tree. See canUpgrade .
Future version of SharedTree may provide readonly access to the document in this case because that would be safe, but this is not currently supported.
isEquivalent
Whether the view schema allows exactly the same set of documents as the stored schema.
Signature
readonly isEquivalent: boolean;
Type: boolean
Remarks
Equivalence here is defined in terms of allowed documents because there are some degenerate cases where schemas are not exact matches in a strict (schema-based) sense but still allow the same documents, and the document notion is more useful to applications.
Examples which are expressible where this may occur include: - schema repository A
has extra schema which schema B
doesn’t have, but they are unused (i.e. not reachable from the root schema) - field in schema A
has allowed field members which the corresponding field in schema B
does not have, but those types are not constructible (ex: an object node type containing a required field with no allowed types)
These cases are typically not interesting to applications.