SchemaStaticsBeta Interface
Stateless APIs exposed via SchemaFactoryBeta as both instance properties and as statics.
For more information about our API support guarantees, see here.
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 SchemaStaticsBeta
Properties
| Property | Alerts | Modifiers | Type | Description |
|---|---|---|---|---|
| staged | Beta | readonly | <const T extends LazyItem<TreeNodeSchema>>(t: T | AnnotatedAllowedType<T>) => AnnotatedAllowedType<T> | Declares a staged type in a set of AllowedTypes. |
| stagedRecursive | Beta | <const T extends Unenforced<AnnotatedAllowedType | LazyItem<TreeNodeSchema>>>(t: T) => AnnotatedAllowedTypeUnsafe<UnannotateAllowedTypeUnsafe<T>> | staged except tweaked to work better for recursive types. Use with ValidateRecursiveSchema for improved type safety. | |
| types | Beta | readonly | <const T extends readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[]>(t: T, metadata?: AllowedTypesMetadata) => AllowedTypesFullFromMixed<T> | Normalize information about a set of AllowedTypes into an AllowedTypesFull. |
| typesRecursive | Beta | readonly | <const T extends readonly Unenforced<AnnotatedAllowedType | LazyItem<TreeNodeSchema>>[]>(t: T, metadata?: AllowedTypesMetadata) => AllowedTypesFullFromMixedUnsafe<T> | types except tweaked to work better for recursive types. Use with ValidateRecursiveSchema for improved type safety. |
Property Details
staged
Declares a staged type in a set of AllowedTypes.
For more information about our API support guarantees, see here.
Signature
readonly staged: <const T extends LazyItem<TreeNodeSchema>>(t: T | AnnotatedAllowedType<T>) => AnnotatedAllowedType<T>;
Type: <const T extends LazyItem<TreeNodeSchema>>(t: T | AnnotatedAllowedType<T>) => AnnotatedAllowedType<T>
Remarks
Staged allowed types add support for loading documents which may contain that type at the declared location. This allows for an incremental rollout of a schema change to add a TreeNodeSchema to an AllowedTypes without breaking cross version collaboration. A guide on this process can be found here: https://fluidframework.com/docs/data-structures/tree/schema-evolution/allowed-types-rollout
Once enough clients have the type staged (and thus can read documents which allow it), documents can start being created and upgraded to allow the staged type. This is done by deploying a new version of the app which removes the staged wrapper around the allowed type in the the schema definition. This will also require upgrading the schema for existing documents.
Using a staged allowed type in a schema is just like using the schema as an allowed type with the following exceptions:
- initialize(content) will omit the staged allowed type from the newly created stored schema. 2. upgradeSchema() will omit the staged allowed type from the the upgraded stored schema. 3. When evaluating compatibility, it will be viewable even if the staged allowed type is not present in the stored schema's corresponding allowed types. 4. Because of the above, it is possible to get errors when inserting content which uses the staged allowed type into a tree whose stored schema does not permit it.
For recursive schemas, use stagedRecursive instead. It offers equivalent runtime behavior with relaxed compile-time typing for recursive type.
Example
A full code example of the schema migration process can be found in our tests.
stagedRecursive
staged except tweaked to work better for recursive types. Use with ValidateRecursiveSchema for improved type safety.
For more information about our API support guarantees, see here.
Signature
stagedRecursive: <const T extends Unenforced<AnnotatedAllowedType | LazyItem<TreeNodeSchema>>>(t: T) => AnnotatedAllowedTypeUnsafe<UnannotateAllowedTypeUnsafe<T>>;
Type: <const T extends Unenforced<AnnotatedAllowedType | LazyItem<TreeNodeSchema>>>(t: T) => AnnotatedAllowedTypeUnsafe<UnannotateAllowedTypeUnsafe<T>>
Remarks
This version of staged has fewer type constraints to work around TypeScript limitations, see Unenforced. See ValidateRecursiveSchema for additional information about using recursive schema.
types
Normalize information about a set of AllowedTypes into an AllowedTypesFull.
For more information about our API support guarantees, see here.
Signature
readonly types: <const T extends readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[]>(t: T, metadata?: AllowedTypesMetadata) => AllowedTypesFullFromMixed<T>;
Type: <const T extends readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[]>(t: T, metadata?: AllowedTypesMetadata) => AllowedTypesFullFromMixed<T>
Remarks
This can take in AnnotatedAllowedType to preserve their annotations.
typesRecursive
types except tweaked to work better for recursive types. Use with ValidateRecursiveSchema for improved type safety.
For more information about our API support guarantees, see here.
Signature
readonly typesRecursive: <const T extends readonly Unenforced<AnnotatedAllowedType | LazyItem<TreeNodeSchema>>[]>(t: T, metadata?: AllowedTypesMetadata) => AllowedTypesFullFromMixedUnsafe<T>;
Type: <const T extends readonly Unenforced<AnnotatedAllowedType | LazyItem<TreeNodeSchema>>[]>(t: T, metadata?: AllowedTypesMetadata) => AllowedTypesFullFromMixedUnsafe<T>
Remarks
This version of types has fewer type constraints to work around TypeScript limitations, see Unenforced. See ValidateRecursiveSchema for additional information about using recursive schema.
See Also
SchemaStatics for why this is useful.