SchemaFactoryAlpha Class

SchemaFactory with additional alpha APIs.

This API is provided as an alpha preview and may change without notice.

To use, import via fluid-framework/alpha.

For more information about our API support guarantees, see here.

Signature

export declare class SchemaFactoryAlpha<out TScope extends string | undefined = string | undefined, TName extends number | string = string> extends SchemaFactoryBeta<TScope, TName>

Extends: SchemaFactoryBeta<TScope, TName>

Type Parameters

Parameter	Constraint	Default	Description
TScope	string | undefined	string | undefined
TName	number | string	string

Static Properties

Property	Alerts	Modifiers	Type	Description
identifier	Alpha	readonly	<const TCustomMetadata = unknown>(props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlpha<FieldKind.Identifier, LeafSchema<"string", string> & SimpleLeafNodeSchema, TCustomMetadata>	Like identifier but static and a factory function that can be provided FieldProps.
leaves	Alpha	readonly	readonly [LeafSchema<"string", string> & SimpleLeafNodeSchema, LeafSchema<"number", number> & SimpleLeafNodeSchema, LeafSchema<"boolean", boolean> & SimpleLeafNodeSchema, LeafSchema<"null", null> & SimpleLeafNodeSchema, LeafSchema<"handle", import("@fluidframework/core-interfaces").IFluidHandle<unknown>> & SimpleLeafNodeSchema]	AllowedTypes for holding any of the leaf types.
optional	Alpha	readonly	<const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlpha<FieldKind.Optional, T, TCustomMetadata>	Make a field optional instead of the default, which is required.
optionalRecursive	Alpha	readonly	<const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlphaUnsafe<FieldKind.Optional, T, TCustomMetadata>	optional except tweaked to work better for recursive types. Use with ValidateRecursiveSchema for improved type safety.
required	Alpha	readonly	<const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlpha<FieldKind.Required, T, TCustomMetadata>	Make a field explicitly required.
requiredRecursive	Alpha	readonly	<const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlphaUnsafe<FieldKind.Required, T, TCustomMetadata>	required except tweaked to work better for recursive types. Use with ValidateRecursiveSchema for improved type safety.
staged	Alpha		<const T extends LazyItem<TreeNodeSchema>>(t: T | AnnotatedAllowedType<T>) => AnnotatedAllowedType<T>	Declares a staged type in a set of AllowedTypes.
stagedRecursive	Alpha		<const T extends unknown>(t: T) => AnnotatedAllowedTypeUnsafe<UnannotateAllowedTypeUnsafe<T>>	staged except tweaked to work better for recursive types. Use with ValidateRecursiveSchema for improved type safety.
types	Alpha		<const T extends readonly (LazyItem<TreeNodeSchema> | AnnotatedAllowedType<LazyItem<TreeNodeSchema>>)[]>(t: T, metadata?: AllowedTypesMetadata | undefined) => AllowedTypesFullFromMixed<T>	Normalize information about a set of AllowedTypes into an AllowedTypesFull.
typesRecursive	Alpha		<const T extends readonly unknown[]>(t: T, metadata?: AllowedTypesMetadata | undefined) => AllowedTypesFullFromMixedUnsafe<T>	types except tweaked to work better for recursive types. Use with ValidateRecursiveSchema for improved type safety.

Properties

Property	Alerts	Modifiers	Type	Description
leaves	Alpha	readonly	readonly [LeafSchema<"string", string> & SimpleLeafNodeSchema, LeafSchema<"number", number> & SimpleLeafNodeSchema, LeafSchema<"boolean", boolean> & SimpleLeafNodeSchema, LeafSchema<"null", null> & SimpleLeafNodeSchema, LeafSchema<"handle", import("@fluidframework/core-interfaces").IFluidHandle<unknown>> & SimpleLeafNodeSchema]	AllowedTypes for holding any of the leaf types.
optional	Alpha	readonly	<const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlpha<FieldKind.Optional, T, TCustomMetadata>	Make a field optional instead of the default, which is required.
optionalRecursive	Alpha	readonly	<const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlphaUnsafe<FieldKind.Optional, T, TCustomMetadata>	optional except tweaked to work better for recursive types. Use with ValidateRecursiveSchema for improved type safety.
required	Alpha	readonly	<const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlpha<FieldKind.Required, T, TCustomMetadata>	Make a field explicitly required.
requiredRecursive	Alpha	readonly	<const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlphaUnsafe<FieldKind.Required, T, TCustomMetadata>	required except tweaked to work better for recursive types. Use with ValidateRecursiveSchema for improved type safety.
staged	Alpha		<const T extends LazyItem<TreeNodeSchema>>(t: T | AnnotatedAllowedType<T>) => AnnotatedAllowedType<T>	Declares a staged type in a set of AllowedTypes.
stagedRecursive	Alpha		<const T extends unknown>(t: T) => AnnotatedAllowedTypeUnsafe<UnannotateAllowedTypeUnsafe<T>>	staged except tweaked to work better for recursive types. Use with ValidateRecursiveSchema for improved type safety.
types	Alpha		<const T extends readonly (LazyItem<TreeNodeSchema> | AnnotatedAllowedType<LazyItem<TreeNodeSchema>>)[]>(t: T, metadata?: AllowedTypesMetadata | undefined) => AllowedTypesFullFromMixed<T>	Normalize information about a set of AllowedTypes into an AllowedTypesFull.
typesRecursive	Alpha		<const T extends readonly unknown[]>(t: T, metadata?: AllowedTypesMetadata | undefined) => AllowedTypesFullFromMixedUnsafe<T>	types except tweaked to work better for recursive types. Use with ValidateRecursiveSchema for improved type safety.

Property Details

identifier

Like identifier but static and a factory function that can be provided FieldProps.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature

static readonly identifier: <const TCustomMetadata = unknown>(props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlpha<FieldKind.Identifier, LeafSchema<"string", string> & SimpleLeafNodeSchema, TCustomMetadata>;

Type: <const TCustomMetadata = unknown>(props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlpha<FieldKind.Identifier, LeafSchema<"string", string> & SimpleLeafNodeSchema, TCustomMetadata>

leaves

AllowedTypes for holding any of the leaf types.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature

readonly leaves: readonly [LeafSchema<"string", string> & SimpleLeafNodeSchema, LeafSchema<"number", number> & SimpleLeafNodeSchema, LeafSchema<"boolean", boolean> & SimpleLeafNodeSchema, LeafSchema<"null", null> & SimpleLeafNodeSchema, LeafSchema<"handle", import("@fluidframework/core-interfaces").IFluidHandle<unknown>> & SimpleLeafNodeSchema];

Type: readonly [LeafSchema<"string", string> & SimpleLeafNodeSchema, LeafSchema<"number", number> & SimpleLeafNodeSchema, LeafSchema<"boolean", boolean> & SimpleLeafNodeSchema, LeafSchema<"null", null> & SimpleLeafNodeSchema, LeafSchema<"handle", import("@fluidframework/core-interfaces").IFluidHandle<unknown>> & SimpleLeafNodeSchema]

leaves

AllowedTypes for holding any of the leaf types.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature

static readonly leaves: readonly [LeafSchema<"string", string> & SimpleLeafNodeSchema, LeafSchema<"number", number> & SimpleLeafNodeSchema, LeafSchema<"boolean", boolean> & SimpleLeafNodeSchema, LeafSchema<"null", null> & SimpleLeafNodeSchema, LeafSchema<"handle", import("@fluidframework/core-interfaces").IFluidHandle<unknown>> & SimpleLeafNodeSchema];

Type: readonly [LeafSchema<"string", string> & SimpleLeafNodeSchema, LeafSchema<"number", number> & SimpleLeafNodeSchema, LeafSchema<"boolean", boolean> & SimpleLeafNodeSchema, LeafSchema<"null", null> & SimpleLeafNodeSchema, LeafSchema<"handle", import("@fluidframework/core-interfaces").IFluidHandle<unknown>> & SimpleLeafNodeSchema]

optional

Make a field optional instead of the default, which is required.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature

readonly optional: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlpha<FieldKind.Optional, T, TCustomMetadata>;

Type: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlpha<FieldKind.Optional, T, TCustomMetadata>

optional

Make a field optional instead of the default, which is required.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature

static readonly optional: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlpha<FieldKind.Optional, T, TCustomMetadata>;

Type: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlpha<FieldKind.Optional, T, TCustomMetadata>

optionalRecursive

optional except tweaked to work better for recursive types. Use with ValidateRecursiveSchema for improved type safety.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature

readonly optionalRecursive: <const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlphaUnsafe<FieldKind.Optional, T, TCustomMetadata>;

Type: <const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlphaUnsafe<FieldKind.Optional, T, TCustomMetadata>

Remarks

This version of optional has fewer type constraints to work around TypeScript limitations, see Unenforced. See ValidateRecursiveSchema for additional information about using recursive schema.

optionalRecursive

optional except tweaked to work better for recursive types. Use with ValidateRecursiveSchema for improved type safety.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature

static readonly optionalRecursive: <const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlphaUnsafe<FieldKind.Optional, T, TCustomMetadata>;

Type: <const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlphaUnsafe<FieldKind.Optional, T, TCustomMetadata>

Remarks

This version of optional has fewer type constraints to work around TypeScript limitations, see Unenforced. See ValidateRecursiveSchema for additional information about using recursive schema.

required

Make a field explicitly required.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature

readonly required: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlpha<FieldKind.Required, T, TCustomMetadata>;

Type: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlpha<FieldKind.Required, T, TCustomMetadata>

Remarks

Fields are required by default, but this API can be used to make the required nature explicit in the schema, and allows associating custom properties with the field.

required

Make a field explicitly required.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature

static readonly required: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlpha<FieldKind.Required, T, TCustomMetadata>;

Type: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlpha<FieldKind.Required, T, TCustomMetadata>

Remarks

Fields are required by default, but this API can be used to make the required nature explicit in the schema, and allows associating custom properties with the field.

requiredRecursive

required except tweaked to work better for recursive types. Use with ValidateRecursiveSchema for improved type safety.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature

readonly requiredRecursive: <const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlphaUnsafe<FieldKind.Required, T, TCustomMetadata>;

Type: <const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlphaUnsafe<FieldKind.Required, T, TCustomMetadata>

Remarks

This version of required has fewer type constraints to work around TypeScript limitations, see Unenforced. See ValidateRecursiveSchema for additional information about using recursive schema.

requiredRecursive

required except tweaked to work better for recursive types. Use with ValidateRecursiveSchema for improved type safety.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature

static readonly requiredRecursive: <const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlphaUnsafe<FieldKind.Required, T, TCustomMetadata>;

Type: <const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlphaUnsafe<FieldKind.Required, T, TCustomMetadata>

Remarks

This version of required has fewer type constraints to work around TypeScript limitations, see Unenforced. See ValidateRecursiveSchema for additional information about using recursive schema.

staged

Declares a staged type in a set of AllowedTypes.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature

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:

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

Currently, staged is not supported in the recursive type APIs: this is a known limitation which future versions of the API will address.

staged

Declares a staged type in a set of AllowedTypes.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature

static 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:

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

Currently, staged is not supported in the recursive type APIs: this is a known limitation which future versions of the API will address.

stagedRecursive

staged except tweaked to work better for recursive types. Use with ValidateRecursiveSchema for improved type safety.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature

stagedRecursive: <const T extends unknown>(t: T) => AnnotatedAllowedTypeUnsafe<UnannotateAllowedTypeUnsafe<T>>;

Type: <const T extends unknown>(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.

stagedRecursive

staged except tweaked to work better for recursive types. Use with ValidateRecursiveSchema for improved type safety.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature

static stagedRecursive: <const T extends unknown>(t: T) => AnnotatedAllowedTypeUnsafe<UnannotateAllowedTypeUnsafe<T>>;

Type: <const T extends unknown>(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.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature

types: <const T extends readonly (LazyItem<TreeNodeSchema> | AnnotatedAllowedType<LazyItem<TreeNodeSchema>>)[]>(t: T, metadata?: AllowedTypesMetadata | undefined) => AllowedTypesFullFromMixed<T>;

Type: <const T extends readonly (LazyItem<TreeNodeSchema> | AnnotatedAllowedType<LazyItem<TreeNodeSchema>>)[]>(t: T, metadata?: AllowedTypesMetadata | undefined) => AllowedTypesFullFromMixed<T>

Remarks

This can take in AnnotatedAllowedType to preserve their annotations.

types

Normalize information about a set of AllowedTypes into an AllowedTypesFull.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature

static types: <const T extends readonly (LazyItem<TreeNodeSchema> | AnnotatedAllowedType<LazyItem<TreeNodeSchema>>)[]>(t: T, metadata?: AllowedTypesMetadata | undefined) => AllowedTypesFullFromMixed<T>;

Type: <const T extends readonly (LazyItem<TreeNodeSchema> | AnnotatedAllowedType<LazyItem<TreeNodeSchema>>)[]>(t: T, metadata?: AllowedTypesMetadata | undefined) => 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.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature

typesRecursive: <const T extends readonly unknown[]>(t: T, metadata?: AllowedTypesMetadata | undefined) => AllowedTypesFullFromMixedUnsafe<T>;

Type: <const T extends readonly unknown[]>(t: T, metadata?: AllowedTypesMetadata | undefined) => 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.

typesRecursive

types except tweaked to work better for recursive types. Use with ValidateRecursiveSchema for improved type safety.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature

static typesRecursive: <const T extends readonly unknown[]>(t: T, metadata?: AllowedTypesMetadata | undefined) => AllowedTypesFullFromMixedUnsafe<T>;

Type: <const T extends readonly unknown[]>(t: T, metadata?: AllowedTypesMetadata | undefined) => 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.