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

Sealed

This type is "sealed," meaning that code outside of the library defining it should not implement or extend it. Future versions of this type may add members or make typing of readonly members more specific.

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 when upgradeSchema() can add support for all content required to be supported by the view schema.
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.
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 when upgradeSchema() can add support for all content required to be supported by the view schema.

Signature

readonly canUpgrade: boolean;

Type: boolean

Remarks

When true, it is valid to call upgradeSchema() (though if the stored schema is already an exact match, this is a no-op).

When adding optional fields to schema which previously were marked with allowUnknownOptionalFields the schema upgrade (assuming no other changes are included) will allow the previous version to view. Even this case must still must be done with caution however as only clients with the newly added field will be able to do future upgrades. Thus if a version of an application is shipped that adds an unknown optional field, all future versions should include it, even if its no longer used, to ensure that documents containing it can still be upgraded.

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.

Signature

readonly canView: boolean;

Type: boolean

Remarks

If the view schema does not opt into supporting any additional cases, then canView is only true when isEquivalent is also true. The view schema can however opt into supporting additional cases, and thus can also view documents with stored schema which would be equivalent, except for the following discrepancies:

• An object node with allowUnknownOptionalFields to set to true that has additional optional fields in the stored schema beyond those mentioned in its view schema.

• An additional type allowed at a location in the stored schema where it is staged in the view schema.

In these cases canUpgrade and isEquivalent will be false.

When the documents allowed by the view schema is a strict superset of those by the stored schema, canView 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 versions 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 (for example: an object node type containing a required field with no allowed types)

These cases are typically not interesting to applications.

Note that other content in the stored schema that does not impact document compatibility, like persistedMetadata, does not affect this field.

For the computation of this equivalence, staged schemas are not included. If there are any unknown optional fields, even if allowed by allowUnknownOptionalFields, isEquivalent will be false.