SchemaCompatibilityStatus Interface

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 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.
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 branch 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.