@fluidframework/tree 2.70.0 → 2.72.0

package/src/simple-tree/core/allowedTypes.ts

@@ -4,7 +4,7 @@
  */
 
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
-import { assert, Lazy } from "@fluidframework/core-utils/internal";
+import { Lazy } from "@fluidframework/core-utils/internal";
 
 import {
 	type ErasedBaseType,
@@ -25,6 +25,7 @@ import {
 	type TreeNodeSchema,
 } from "./treeNodeSchema.js";
 import { schemaAsTreeNodeValid } from "./treeNodeValid.js";
+import type { SimpleAllowedTypeAttributes } from "../simpleSchema.js";
 
 /**
  * Schema for types allowed in some location in a tree (like a field, map entry or array).
@@ -56,7 +57,7 @@ export type AllowedTypes = readonly LazyItem<TreeNodeSchema>[];
 /**
  * Stores annotations for an individual allowed type.
  * @remarks
- * Create using APIs on {@link SchemaFactoryAlpha}, like {@link SchemaStaticsAlpha.staged}.
+ * Create using APIs on {@link SchemaStaticsBeta}, like {@link SchemaStaticsBeta.staged}.
  * @privateRemarks
  * Since this is sealed, users are not supposed to create instances of it directly.
  * Making it extend ErasedType could enforce that.
@@ -252,6 +253,21 @@ export class AnnotatedAllowedTypesInternal<
 		return this.lazyEvaluate.value.identifiers;
 	}
 
+	/**
+	 * Get the {@link SimpleAllowedTypeAttributes} version of the allowed types set.
+	 */
+	public static evaluateSimpleAllowedTypes(
+		annotatedAllowedTypes: AnnotatedAllowedTypes,
+	): ReadonlyMap<string, SimpleAllowedTypeAttributes> {
+		const simpleAllowedTypes = new Map<string, SimpleAllowedTypeAttributes>();
+		for (const type of annotatedAllowedTypes.evaluate().types) {
+			simpleAllowedTypes.set(type.type.identifier, {
+				isStaged: type.metadata.stagedSchemaUpgrade !== undefined,
+			});
+		}
+		return simpleAllowedTypes;
+	}
+
 	public static override [Symbol.hasInstance]<TThis extends { prototype: object }>(
 		this: TThis,
 		value: unknown,
@@ -332,7 +348,7 @@ export class AnnotatedAllowedTypesInternal<
 	public static create<const T extends readonly AnnotatedAllowedType[]>(
 		types: T,
 		metadata: AllowedTypesMetadata = {},
-	): AnnotatedAllowedTypesInternal<T> & AllowedTypesFull<T> {
+	): AnnotatedAllowedTypesInternal<Readonly<T>> & AllowedTypesFull<Readonly<T>> {
 		const result = new AnnotatedAllowedTypesInternal(types, metadata);
 		return result as typeof result & UnannotateAllowedTypesList<T>;
 	}
@@ -340,7 +356,8 @@ export class AnnotatedAllowedTypesInternal<
 	public static createUnannotated<const T extends AllowedTypes>(
 		types: T,
 		metadata: AllowedTypesMetadata = {},
-	): AnnotatedAllowedTypesInternal & T {
+	): AnnotatedAllowedTypesInternal & Readonly<T> {
+		Object.freeze(types);
 		const annotatedTypes: AnnotatedAllowedType[] = types.map(normalizeToAnnotatedAllowedType);
 		const result = AnnotatedAllowedTypesInternal.create(annotatedTypes, metadata);
 		return result as typeof result & T;
@@ -349,6 +366,7 @@ export class AnnotatedAllowedTypesInternal<
 	public static createMixed<
 		const T extends readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[],
 	>(types: T, metadata: AllowedTypesMetadata = {}): AllowedTypesFullFromMixed<T> {
+		Object.freeze(types);
 		const annotatedTypes: AnnotatedAllowedType[] = types.map(normalizeToAnnotatedAllowedType);
 		const result = AnnotatedAllowedTypesInternal.create(annotatedTypes, metadata);
 		return result as AllowedTypesFullFromMixed<T>;
@@ -394,7 +412,7 @@ export interface AllowedTypeMetadata {
 	readonly custom?: unknown;
 
 	/**
-	 * If defined, indicates that an allowed type is {@link SchemaStaticsAlpha.staged | staged}.
+	 * If defined, indicates that an allowed type is {@link SchemaStaticsBeta.staged | staged}.
 	 */
 	readonly stagedSchemaUpgrade?: SchemaUpgrade;
 }
@@ -407,7 +425,7 @@ export let createSchemaUpgrade: () => SchemaUpgrade;
 /**
  * Unique token used to upgrade schemas and determine if a particular upgrade has been completed.
  * @remarks
- * Create using {@link SchemaStaticsAlpha.staged}.
+ * Create using {@link SchemaStaticsBeta.staged}.
  * @privateRemarks
  * TODO:#38722 implement runtime schema upgrades.
  * Until then, the class purely behaves mostly as a placeholder.
@@ -524,14 +542,9 @@ export function normalizeAllowedTypesInternal(
 	// Adding this cache improved the performance of the "large recursive union" test (which mostly just constructs a TreeConfiguration) by ~5 times.
 	// This cache is strictly a performance optimization: it is not required for correctness.
 	return getOrCreate(cachedNormalize, type, () => {
-		// Due to more specific internal type, the above does not narrow sufficiently, so more narrowing is needed.
-		// It is possible this will give a false error if a TreeNodeSchema which matches this check is used.
-		assert(
-			!("types" in type && "metadata" in type),
-			0xc7d /* invalid AnnotatedAllowedTypes */,
-		);
-
-		const annotatedTypes: AnnotatedAllowedType[] = (isReadonlyArray(type) ? type : [type]).map(
+		const inputArray = isReadonlyArray(type) ? type : [type];
+		Object.freeze(inputArray);
+		const annotatedTypes: AnnotatedAllowedType[] = inputArray.map(
 			normalizeToAnnotatedAllowedType,
 		);
 
@@ -637,8 +650,8 @@ export type TreeNodeFromImplicitAllowedTypes<
  * This type exists only to be linked from documentation to provide a single linkable place to document some details of
  * "Input" types and how they handle schema.
  *
- * When a schema is used to describe data which is an input into an API, the API is [contravariant](https://en.wikipedia.org/wiki/Covariance_and_contravariance_(computer_science)) over the schema.
- * (See also, [TypeScript Variance Annotations](https://www.typescriptlang.org/docs/handbook/2/generics.html#variance-annotations)).
+ * When a schema is used to describe data which is an input into an API, the API is {@link https://en.wikipedia.org/wiki/Type_variance | contravariant}) over the schema.
+ * (See also {@link https://www.typescriptlang.org/docs/handbook/2/generics.html#variance-annotations | TypeScript Variance Annotations}).
  *
  * Since these schema are expressed using TypeScript types, it is possible for the user of the API to provide non-exact values of these types which has implications that depended on the variance.
  *

package/src/simple-tree/core/treeNode.ts

@@ -8,7 +8,7 @@ import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import { tryGetTreeNodeSchema } from "./treeNodeKernel.js";
 import { NodeKind, type TreeNodeSchemaClass } from "./treeNodeSchema.js";
-// eslint-disable-next-line import/no-deprecated
+// eslint-disable-next-line import-x/no-deprecated
 import { type WithType, typeNameSymbol, type typeSchemaSymbol } from "./withType.js";
 import { markEager } from "./flexList.js";
 
@@ -80,7 +80,7 @@ export abstract class TreeNode implements WithType {
 	 * Subclasses provide more specific strings for this to get strong typing of otherwise type compatible nodes.
 	 * @deprecated Use {@link typeSchemaSymbol} instead.
 	 */
-	// eslint-disable-next-line import/no-deprecated
+	// eslint-disable-next-line import-x/no-deprecated
 	public abstract get [typeNameSymbol](): string;
 
 	/**

package/src/simple-tree/fieldSchema.ts

@@ -31,7 +31,7 @@ import type {
 } from "./core/index.js";
 import { normalizeAllowedTypes } from "./core/index.js";
 
-import type { SimpleFieldSchema } from "./simpleSchema.js";
+import type { SimpleAllowedTypeAttributes, SimpleFieldSchema } from "./simpleSchema.js";
 import type { UnsafeUnknownSchema } from "./unsafeUnknownSchema.js";
 import type { InsertableContent } from "./unhydratedFlexTreeFromInsertable.js";
 
@@ -412,6 +412,19 @@ export class FieldSchemaAlpha<
 		return this.allowedTypesFull.evaluateIdentifiers();
 	}
 
+	public get simpleAllowedTypes(): ReadonlyMap<string, SimpleAllowedTypeAttributes> {
+		const types = this.allowedTypesFull.evaluate().types;
+		const info = new Map<string, SimpleAllowedTypeAttributes>();
+
+		for (const type of types) {
+			info.set(type.type.identifier, {
+				isStaged: type.metadata.stagedSchemaUpgrade !== undefined,
+			});
+		}
+
+		return info;
+	}
+
 	protected constructor(
 		kind: Kind,
 		types: Types,

package/src/simple-tree/index.ts

@@ -74,6 +74,7 @@ export {
 	type ITreeConfigurationOptions,
 	SchemaFactory,
 	SchemaFactoryBeta,
+	type SchemaStaticsBeta,
 	SchemaFactoryAlpha,
 	type ObjectSchemaOptionsAlpha,
 	type ObjectSchemaOptions,
@@ -180,7 +181,6 @@ export {
 	type TreeChangeEvents,
 	type NodeSchemaOptions,
 	type NodeSchemaOptionsAlpha,
-	type SchemaStaticsAlpha,
 	KeyEncodingOptions,
 	type TreeParsingOptions,
 	incrementalSummaryHint,
@@ -198,6 +198,7 @@ export type {
 	SimpleNodeSchemaBaseAlpha,
 	SimpleObjectFieldSchema,
 	SimpleRecordNodeSchema,
+	SimpleAllowedTypeAttributes,
 } from "./simpleSchema.js";
 export {
 	type ImplicitFieldSchema,
@@ -279,3 +280,7 @@ export {
 	nullSchema,
 } from "./leafNodeSchema.js";
 export type { LeafSchema } from "./leafNodeSchema.js";
+export {
+	encodeSimpleSchema,
+	decodeSimpleSchema,
+} from "./api/index.js";

package/src/simple-tree/node-kinds/array/arrayNode.ts

@@ -16,7 +16,7 @@ import { FieldKinds, isTreeValue } from "../../../feature-libraries/index.js";
 import {
 	CompatibilityLevel,
 	type WithType,
-	// eslint-disable-next-line import/no-deprecated
+	// eslint-disable-next-line import-x/no-deprecated
 	typeNameSymbol,
 	NodeKind,
 	type TreeNode,
@@ -47,6 +47,7 @@ import {
 	type TreeNodeSchemaPrivateData,
 	convertAllowedTypes,
 	withBufferedTreeEvents,
+	AnnotatedAllowedTypesInternal,
 } from "../../core/index.js";
 import {
 	type FactoryContent,
@@ -68,6 +69,7 @@ import type {
 import { brand, type JsonCompatibleReadOnlyObject } from "../../../util/index.js";
 import { nullSchema } from "../../leafNodeSchema.js";
 import { arrayNodeStoredSchema } from "../../toStoredSchema.js";
+import type { SimpleAllowedTypeAttributes } from "../../simpleSchema.js";
 
 /**
  * A covariant base type for {@link (TreeArrayNode:interface)}.
@@ -1168,6 +1170,9 @@ export function arraySchema<
 	const lazyAllowedTypesIdentifiers = new Lazy(
 		() => new Set(normalizedTypes.evaluate().map((type) => type.identifier)),
 	);
+	const lazySimpleAllowedTypes = new Lazy(() => {
+		return AnnotatedAllowedTypesInternal.evaluateSimpleAllowedTypes(normalizedTypes);
+	});
 
 	let privateData: TreeNodeSchemaPrivateData | undefined;
 
@@ -1206,6 +1211,10 @@ export function arraySchema<
 			return lazyAllowedTypesIdentifiers.value;
 		}
 
+		public static get simpleAllowedTypes(): ReadonlyMap<string, SimpleAllowedTypeAttributes> {
+			return lazySimpleAllowedTypes.value;
+		}
+
 		protected static override constructorCached: MostDerivedData | undefined = undefined;
 
 		protected static override oneTimeSetup(): TreeNodeSchemaInitializedData {
@@ -1257,7 +1266,7 @@ export function arraySchema<
 		public static readonly persistedMetadata: JsonCompatibleReadOnlyObject | undefined =
 			persistedMetadata;
 
-		// eslint-disable-next-line import/no-deprecated
+		// eslint-disable-next-line import-x/no-deprecated
 		public get [typeNameSymbol](): TName {
 			return identifier;
 		}

package/src/simple-tree/node-kinds/map/mapNode.ts

@@ -22,7 +22,7 @@ import {
 	type InnerNode,
 	NodeKind,
 	type TreeNodeSchema,
-	// eslint-disable-next-line import/no-deprecated
+	// eslint-disable-next-line import-x/no-deprecated
 	typeNameSymbol,
 	type TreeNode,
 	typeSchemaSymbol,
@@ -43,6 +43,7 @@ import {
 	type FlexContent,
 	type TreeNodeSchemaPrivateData,
 	convertAllowedTypes,
+	AnnotatedAllowedTypesInternal,
 } from "../../core/index.js";
 import {
 	unhydratedFlexTreeFromInsertable,
@@ -66,6 +67,7 @@ import type {
 import { recordLikeDataToFlexContent } from "../common.js";
 import { MapNodeStoredSchema } from "../../../core/index.js";
 import type { NodeSchemaOptionsAlpha } from "../../api/index.js";
+import type { SimpleAllowedTypeAttributes } from "../../simpleSchema.js";
 
 /**
  * A map of string keys to tree objects.
@@ -275,6 +277,9 @@ export function mapSchema<
 	const lazyAllowedTypesIdentifiers = new Lazy(
 		() => new Set(normalizedTypes.evaluate().map((type) => type.identifier)),
 	);
+	const lazySimpleAllowedTypes = new Lazy(() => {
+		return AnnotatedAllowedTypesInternal.evaluateSimpleAllowedTypes(normalizedTypes);
+	});
 
 	let privateData: TreeNodeSchemaPrivateData | undefined;
 	const persistedMetadata = nodeOptions.persistedMetadata;
@@ -303,6 +308,10 @@ export function mapSchema<
 			return lazyAllowedTypesIdentifiers.value;
 		}
 
+		public static get simpleAllowedTypes(): ReadonlyMap<string, SimpleAllowedTypeAttributes> {
+			return lazySimpleAllowedTypes.value;
+		}
+
 		protected static override constructorCached: MostDerivedData | undefined = undefined;
 
 		protected static override oneTimeSetup(): TreeNodeSchemaInitializedData {
@@ -325,7 +334,7 @@ export function mapSchema<
 		public static readonly persistedMetadata: JsonCompatibleReadOnlyObject | undefined =
 			persistedMetadata;
 
-		// eslint-disable-next-line import/no-deprecated
+		// eslint-disable-next-line import-x/no-deprecated
 		public get [typeNameSymbol](): TName {
 			return identifier;
 		}

package/src/simple-tree/node-kinds/object/objectNode.ts

@@ -32,7 +32,7 @@ import {
 	type TreeNodeSchema,
 	NodeKind,
 	type WithType,
-	// eslint-disable-next-line import/no-deprecated
+	// eslint-disable-next-line import-x/no-deprecated
 	typeNameSymbol,
 	typeSchemaSymbol,
 	type InternalTreeNode,
@@ -118,6 +118,23 @@ export type ObjectFromSchemaRecord<T extends RestrictiveStringRecord<ImplicitFie
  * No other own `own` or `enumerable` properties are included on object nodes unless the user of the node manually adds custom session only state.
  * This allows a majority of general purpose JavaScript object processing operations (like `for...in`, `Reflect.ownKeys()` and `Object.entries()`) to enumerate all the children.
  *
+ * Field Assignment and Deletion
+ * Assigning to a field updates the tree value as long as it is still valid based on the schema.
+ * - For required fields, assigning `undefined` is invalid, and will throw.
+ * - For optional fields, assigning `undefined` removes the field's contents, and marks it as empty (non-enumerable and value set to undefined).
+ *
+ * Example:
+ * ```ts
+ * const Foo = schemaFactory.object("Foo", {bar: schemaFactory.optional(schemaFactory.number)});
+ * const node = new Foo({bar: 1})
+ *
+ * // This clears the field, is non-enumerable, and value is undefined.
+ * delete node.bar;
+ *
+ * // This is equivalent to the delete example.
+ * node.bar = undefined
+ * ```
+ *
  * The API for fields is defined by {@link ObjectFromSchemaRecord}.
  * @public
  */
@@ -258,7 +275,7 @@ function createProxyHandler(
 			if (propertyKey === typeSchemaSymbol) {
 				return schema;
 			}
-			// eslint-disable-next-line import/no-deprecated
+			// eslint-disable-next-line import-x/no-deprecated
 			if (propertyKey === typeNameSymbol) {
 				return schema.identifier;
 			}
@@ -275,27 +292,17 @@ function createProxyHandler(
 					: false;
 			}
 
-			const innerNode = getInnerNode(proxy);
-
-			const innerSchema = innerNode.context.schema.nodeSchema.get(brand(schema.identifier));
-			assert(
-				innerSchema instanceof ObjectNodeStoredSchema,
-				0xc18 /* Expected ObjectNodeStoredSchema */,
-			);
-
-			setField(
-				innerNode.getBoxed(fieldInfo.storedKey),
-				fieldInfo.schema,
-				value,
-				innerSchema.getFieldSchema(fieldInfo.storedKey),
-			);
+			applyFieldChange(schema, { kind: "proxy", node: proxy }, fieldInfo, value);
 			return true;
 		},
 		deleteProperty(target, propertyKey): boolean {
-			// TODO: supporting delete when it makes sense (custom local fields, and optional field) could be added as a feature in the future.
-			throw new UsageError(
-				`Object nodes do not support the delete operator. Optional fields can be assigned to undefined instead.`,
-			);
+			const fieldInfo = schema.flexKeyMap.get(propertyKey);
+			if (fieldInfo === undefined) {
+				return allowAdditionalProperties ? Reflect.deleteProperty(target, propertyKey) : false;
+			}
+
+			applyFieldChange(schema, { kind: "target", node: target }, fieldInfo, undefined);
+			return true;
 		},
 		has: (target, propertyKey) => {
 			return (
@@ -566,7 +573,7 @@ export function objectSchema<
 		public static readonly persistedMetadata: JsonCompatibleReadOnlyObject | undefined =
 			nodeOptions.persistedMetadata;
 
-		// eslint-disable-next-line import/no-deprecated
+		// eslint-disable-next-line import-x/no-deprecated
 		public get [typeNameSymbol](): TName {
 			return identifier;
 		}
@@ -750,3 +757,32 @@ function getFieldProperty(
 	}
 	return undefined;
 }
+
+function applyFieldChange(
+	schema: ObjectNodeSchemaPrivate,
+	from: { kind: "proxy"; node: TreeNode } | { kind: "target"; node: object },
+	fieldInfo: { storedKey: FieldKey; schema: FieldSchema },
+	value: InsertableContent | undefined,
+): void {
+	const proxy =
+		from.kind === "proxy"
+			? from.node
+			: (targetToProxy.get(from.node) ?? fail(0xc95 /* missing proxy */));
+	const inner = getInnerNode(proxy);
+	const storedSchema = inner.context.schema.nodeSchema.get(brand(schema.identifier));
+	assert(
+		storedSchema instanceof ObjectNodeStoredSchema,
+		0xc96 /* Expected ObjectNodeStoredSchema */,
+	);
+
+	if (value === undefined && inner.tryGetField(fieldInfo.storedKey) === undefined) {
+		return;
+	}
+
+	setField(
+		inner.getBoxed(fieldInfo.storedKey),
+		fieldInfo.schema,
+		value,
+		storedSchema.getFieldSchema(fieldInfo.storedKey),
+	);
+}

package/src/simple-tree/node-kinds/record/recordNode.ts

@@ -11,7 +11,7 @@ import { type JsonCompatibleReadOnlyObject, brand } from "../../../util/index.js
 import {
 	type TreeNodeSchema,
 	NodeKind,
-	// eslint-disable-next-line import/no-deprecated
+	// eslint-disable-next-line import-x/no-deprecated
 	typeNameSymbol,
 	typeSchemaSymbol,
 	type UnhydratedFlexTreeNode,
@@ -32,6 +32,7 @@ import {
 	CompatibilityLevel,
 	type TreeNodeSchemaPrivateData,
 	convertAllowedTypes,
+	AnnotatedAllowedTypesInternal,
 } from "../../core/index.js";
 import { getTreeNodeSchemaInitializedData } from "../../createContext.js";
 import { tryGetTreeNodeForField } from "../../getTreeNodeForField.js";
@@ -58,6 +59,7 @@ import { prepareForInsertion } from "../../prepareForInsertion.js";
 import { recordLikeDataToFlexContent } from "../common.js";
 import { MapNodeStoredSchema } from "../../../core/index.js";
 import type { NodeSchemaOptionsAlpha } from "../../api/index.js";
+import type { SimpleAllowedTypeAttributes } from "../../simpleSchema.js";
 
 /**
  * Create a proxy which implements the {@link TreeRecordNode} API.
@@ -78,7 +80,7 @@ function createRecordNodeProxy(
 					case typeSchemaSymbol: {
 						return schema;
 					}
-					// eslint-disable-next-line import/no-deprecated
+					// eslint-disable-next-line import-x/no-deprecated
 					case typeNameSymbol: {
 						return schema.identifier;
 					}
@@ -258,6 +260,9 @@ export function recordSchema<
 	const lazyAllowedTypesIdentifiers = new Lazy(
 		() => new Set(normalizedTypes.evaluate().map((type) => type.identifier)),
 	);
+	const lazySimpleAllowedTypes = new Lazy(() => {
+		return AnnotatedAllowedTypesInternal.evaluateSimpleAllowedTypes(normalizedTypes);
+	});
 
 	let privateData: TreeNodeSchemaPrivateData | undefined;
 
@@ -347,6 +352,10 @@ export function recordSchema<
 			return lazyAllowedTypesIdentifiers.value;
 		}
 
+		public static get simpleAllowedTypes(): ReadonlyMap<string, SimpleAllowedTypeAttributes> {
+			return lazySimpleAllowedTypes.value;
+		}
+
 		protected static override constructorCached: MostDerivedData | undefined = undefined;
 
 		public static readonly identifier = identifier;
@@ -361,7 +370,7 @@ export function recordSchema<
 		public static readonly persistedMetadata: JsonCompatibleReadOnlyObject | undefined =
 			persistedMetadata;
 
-		// eslint-disable-next-line import/no-deprecated
+		// eslint-disable-next-line import-x/no-deprecated
 		public get [typeNameSymbol](): TName {
 			return identifier;
 		}

package/src/simple-tree/node-kinds/record/recordNodeTypes.ts

@@ -26,6 +26,22 @@ import type { RestrictiveStringRecord } from "../../../util/index.js";
  * Therefore code assigning to these fields must explicitly construct nodes using the schema's constructor or create method,
  * or using some other method like {@link (TreeAlpha:interface).create}.
  *
+ * Field Assignment and Deletion
+ *
+ * Unlike JavaScript's `Record` type, assigning `undefined` to a key in {@link TreeRecordNode} behaves like a `delete` operation,
+ * removing the field's contents.
+ *
+ * This is to stay consistent with {@link TreeObjectNode} behavior.
+ *
+ * Example:
+ * ```ts
+ * const Numbers = schemaFactory.record("Numbers", schemaFactory.number);
+ * const record = new Numbers({ a:1, b:2 });
+ *
+ * // This is equivalent to delete record.a, and removes the entry.
+ * record.a = undefined
+ * ```
+ *
  * @beta
  */
 export interface TreeRecordNode<

package/src/simple-tree/simpleSchema.ts

@@ -58,6 +58,15 @@ export interface SimpleObjectNodeSchema<out TCustomMetadata = unknown>
 	 * especially if/when TreeNodeSchema for objects provide more maps.
 	 */
 	readonly fields: ReadonlyMap<string, SimpleObjectFieldSchema>;
+
+	/**
+	 * Whether the object node allows unknown optional fields.
+	 *
+	 * @see {@link ObjectSchemaOptions.allowUnknownOptionalFields} for the API where this field is set as part of authoring a schema.
+	 *
+	 * @remarks Only populated for view schemas, undefined otherwise. Relevant for compatibility checking scenarios.
+	 */
+	readonly allowUnknownOptionalFields: boolean | undefined;
 }
 
 /**
@@ -91,7 +100,7 @@ export interface SimpleArrayNodeSchema<out TCustomMetadata = unknown>
 	 * @remarks Refers to the types by identifier.
 	 * A {@link SimpleTreeSchema} is needed to resolve these identifiers to their schema {@link SimpleTreeSchema.definitions}.
 	 */
-	readonly allowedTypesIdentifiers: ReadonlySet<string>;
+	readonly simpleAllowedTypes: ReadonlyMap<string, SimpleAllowedTypeAttributes>;
 }
 
 /**
@@ -108,7 +117,7 @@ export interface SimpleMapNodeSchema<out TCustomMetadata = unknown>
 	 * @remarks Refers to the types by identifier.
 	 * A {@link SimpleTreeSchema} is needed to resolve these identifiers to their schema {@link SimpleTreeSchema.definitions}.
 	 */
-	readonly allowedTypesIdentifiers: ReadonlySet<string>;
+	readonly simpleAllowedTypes: ReadonlyMap<string, SimpleAllowedTypeAttributes>;
 }
 
 /**
@@ -125,7 +134,7 @@ export interface SimpleRecordNodeSchema<out TCustomMetadata = unknown>
 	 * @remarks Refers to the types by identifier.
 	 * A {@link SimpleTreeSchema} is needed to resolve these identifiers to their schema {@link SimpleTreeSchema.definitions}.
 	 */
-	readonly allowedTypesIdentifiers: ReadonlySet<string>;
+	readonly simpleAllowedTypes: ReadonlyMap<string, SimpleAllowedTypeAttributes>;
 }
 
 /**
@@ -162,6 +171,23 @@ export type SimpleNodeSchema =
 	| SimpleObjectNodeSchema
 	| SimpleRecordNodeSchema;
 
+/**
+ * Information about allowed types under a field.
+ *
+ * @alpha
+ * @sealed
+ */
+export interface SimpleAllowedTypeAttributes {
+	/**
+	 * True if this schema is included as a {@link SchemaStaticsBeta.staged | staged} schema upgrade,
+	 * allowing the view schema be compatible with stored schema with (post upgrade) or without it (pre-upgrade).
+	 * New documents and schema upgrades will omit any staged schema.
+	 *
+	 * Undefined if derived from a stored schema.
+	 */
+	readonly isStaged: boolean | undefined;
+}
+
 /**
  * A simple, shallow representation of a schema for a field.
  *
@@ -179,12 +205,12 @@ export interface SimpleFieldSchema {
 	readonly kind: FieldKind;
 
 	/**
-	 * The types allowed under the field.
+	 * Information about the allowed types under this field.
 	 *
 	 * @remarks Refers to the types by identifier.
 	 * A {@link SimpleTreeSchema} is needed to resolve these identifiers to their schema {@link SimpleTreeSchema.definitions}.
 	 */
-	readonly allowedTypesIdentifiers: ReadonlySet<string>;
+	readonly simpleAllowedTypes: ReadonlyMap<string, SimpleAllowedTypeAttributes>;
 
 	/**
 	 * {@inheritDoc FieldSchemaMetadata}
@@ -221,7 +247,7 @@ export interface SimpleTreeSchema {
 	 * @remarks
 	 * The keys are the schemas' {@link TreeNodeSchemaCore.identifier | identifiers}.
 	 *
-	 * Information about if a schema is {@link SchemaStaticsAlpha.staged | staged} or not is not available as the "Simple Schema" layer of abstraction: they are included unconditionally.
+	 * Information about if a schema is {@link SchemaStaticsBeta.staged | staged} or not is not available as the "Simple Schema" layer of abstraction: they are included unconditionally.
 	 * Options for filtering out staged schemas from view schema are available in {@link extractPersistedSchema}.
 	 */
 	readonly definitions: ReadonlyMap<string, SimpleNodeSchema>;