@fluidframework/tree 2.33.2 → 2.40.0

package/src/simple-tree/api/schemaFactory.ts

@@ -39,6 +39,9 @@ import {
 	type NodeSchemaOptions,
 	markSchemaMostDerived,
 	type FieldSchemaAlpha,
+	type ImplicitAnnotatedAllowedTypes,
+	type UnannotateImplicitAllowedTypes,
+	type UnannotateSchemaRecord,
 } from "../schemaTypes.js";
 import type {
 	NodeKind,
@@ -125,7 +128,7 @@ export interface SchemaFactoryObjectOptions<TCustomMetadata = unknown>
 	 * ```
 	 *
 	 * If an application wants to be particularly careful to preserve all data on a node when editing it, it can use
-	 * {@link TreeAlpha.importVerbose|import}/{@link TreeAlpha.exportVerbose|export} APIs with persistent keys.
+	 * {@link (TreeAlpha:interface).importVerbose|import}/{@link (TreeAlpha:interface).exportVerbose|export} APIs with persistent keys.
 	 *
 	 * Note that public API methods which operate on entire nodes (such as `moveTo`, `moveToEnd`, etc. on arrays) do not encounter
 	 * this problem as SharedTree's implementation stores the entire node in its lower layers. It's only when application code
@@ -179,7 +182,9 @@ export interface SchemaStatics {
 	 *
 	 * @remarks
 	 * The number is a {@link https://en.wikipedia.org/wiki/Double-precision_floating-point_format | double-precision 64-bit binary format IEEE 754} value, however there are some exceptions:
+	 *
 	 * - `NaN`, and the infinities are converted to `null` (and may therefore only be used where `null` is allowed by the schema).
+	 *
 	 * - `-0` may be converted to `0` in some cases.
 	 *
 	 * These limitations match the limitations of JSON.
@@ -289,6 +294,58 @@ const defaultOptionalProvider: DefaultProvider = getDefaultProvider(() => {
 	return undefined;
 });
 
+// The following overloads for optional and required are used to get around the fact that
+// the compiler can't infer that UnannotateImplicitAllowedTypes<T> is equal to T when T is known to extend ImplicitAllowedTypes
+
+function optional<const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(
+	t: T,
+	props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">,
+): FieldSchemaAlpha<FieldKind.Optional, T, TCustomMetadata>;
+
+function optional<
+	const T extends ImplicitAnnotatedAllowedTypes,
+	const TCustomMetadata = unknown,
+>(
+	t: T,
+	props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">,
+): FieldSchemaAlpha<FieldKind.Optional, UnannotateImplicitAllowedTypes<T>, TCustomMetadata>;
+
+function optional<
+	const T extends ImplicitAnnotatedAllowedTypes,
+	const TCustomMetadata = unknown,
+>(
+	t: T,
+	props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">,
+): FieldSchemaAlpha<FieldKind.Optional, UnannotateImplicitAllowedTypes<T>, TCustomMetadata> {
+	return createFieldSchema(FieldKind.Optional, t, {
+		defaultProvider: defaultOptionalProvider,
+		...props,
+	});
+}
+
+function required<const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(
+	t: T,
+	props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">,
+): FieldSchemaAlpha<FieldKind.Required, T, TCustomMetadata>;
+
+function required<
+	const T extends ImplicitAnnotatedAllowedTypes,
+	const TCustomMetadata = unknown,
+>(
+	t: T,
+	props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">,
+): FieldSchemaAlpha<FieldKind.Required, UnannotateImplicitAllowedTypes<T>, TCustomMetadata>;
+
+function required<
+	const T extends ImplicitAnnotatedAllowedTypes,
+	const TCustomMetadata = unknown,
+>(
+	t: T,
+	props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">,
+): FieldSchemaAlpha<FieldKind.Required, UnannotateImplicitAllowedTypes<T>, TCustomMetadata> {
+	return createFieldSchema(FieldKind.Required, t, props);
+}
+
 /**
  * Implementation of {@link SchemaStatics}.
  * @remarks
@@ -303,22 +360,9 @@ export const schemaStaticsBase = {
 	handle: handleSchema,
 	leaves: [stringSchema, numberSchema, booleanSchema, nullSchema, handleSchema],
 
-	optional: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(
-		t: T,
-		props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">,
-	): FieldSchemaAlpha<FieldKind.Optional, T, TCustomMetadata> => {
-		return createFieldSchema(FieldKind.Optional, t, {
-			defaultProvider: defaultOptionalProvider,
-			...props,
-		});
-	},
+	optional,
 
-	required: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(
-		t: T,
-		props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">,
-	): FieldSchemaAlpha<FieldKind.Required, T, TCustomMetadata> => {
-		return createFieldSchema(FieldKind.Required, t, props);
-	},
+	required,
 
 	optionalRecursive: <
 		const T extends System_Unsafe.ImplicitAllowedTypesUnsafe,
@@ -387,9 +431,13 @@ const schemaStaticsPublic: SchemaStatics = schemaStatics;
  * It is legal to subclass the returned class, and even subclass that class,
  * but only a single class from that class hierarchy can ever be instantiated or passed to any API as a {@link TreeNodeSchema|schema}.
  * These base classes can be used with `instanceof`, but not with schema based APIs like `Tree.is`.
+ *
  * 2. If overriding the constructor, the constructor must accept the same argument as the base constructor `super` and forward it to `super` unchanged.
+ *
  * 3. Properties for fields defined in the schema should not be overridden.
+ *
  * 4. Additional static members added to schema should pick relatively unique keys to reduce the risk of colliding with implementation details what are not exposed in the API.
+ *
  * 5. If exporting the schema from a package which uses API-Extractor, export the base class and derived class separately to work around [a known limitation](https://github.com/microsoft/rushstack/issues/4429).
  *
  * Note:
@@ -607,12 +655,36 @@ export class SchemaFactory<
 		true,
 		T
 	> {
-		return objectSchema(
+		// The compiler can't infer that UnannotateSchemaRecord<T> is equal to T so we have to do a bunch of typing to make the error go away.
+		const object: TreeNodeSchemaClass<
+			ScopedSchemaName<TScope, Name>,
+			NodeKind.Object,
+			TreeObjectNode<UnannotateSchemaRecord<T>, ScopedSchemaName<TScope, Name>>,
+			object & InsertableObjectFromSchemaRecord<UnannotateSchemaRecord<T>>,
+			true,
+			T
+		> = objectSchema(
 			this.scoped(name),
 			fields,
 			true,
 			defaultSchemaFactoryObjectOptions.allowUnknownOptionalFields,
 		);
+
+		return object as TreeNodeSchemaClass<
+			ScopedSchemaName<TScope, Name>,
+			NodeKind.Object,
+			TreeObjectNode<RestrictiveStringRecord<ImplicitFieldSchema>>,
+			unknown,
+			true,
+			T
+		> as TreeNodeSchemaClass<
+			ScopedSchemaName<TScope, Name>,
+			NodeKind.Object,
+			TreeObjectNode<T, ScopedSchemaName<TScope, Name>>,
+			object & InsertableObjectFromSchemaRecord<T>,
+			true,
+			T
+		>;
 	}
 
 	/**
@@ -747,7 +819,17 @@ export class SchemaFactory<
 		T,
 		undefined
 	> {
-		return mapSchema(
+		// The compiler can't infer that UnannotateImplicitAllowedTypes<T> is equal to T so we have to do a bunch of typing to make the error go away.
+		const map: TreeNodeSchemaBoth<
+			ScopedSchemaName<TScope, Name>,
+			NodeKind.Map,
+			TreeMapNode<UnannotateImplicitAllowedTypes<T>> &
+				WithType<ScopedSchemaName<TScope, Name>, NodeKind.Map>,
+			MapNodeInsertableData<UnannotateImplicitAllowedTypes<T>>,
+			ImplicitlyConstructable,
+			T,
+			undefined
+		> = mapSchema(
 			this.scoped(name),
 			allowedTypes,
 			implicitlyConstructable,
@@ -755,6 +837,25 @@ export class SchemaFactory<
 			!customizable,
 			undefined,
 		);
+
+		return map as TreeNodeSchemaBoth<
+			ScopedSchemaName<TScope, Name>,
+			NodeKind.Map,
+			TreeMapNode<UnannotateImplicitAllowedTypes<T>> &
+				WithType<ScopedSchemaName<TScope, Name>, NodeKind.Map>,
+			MapNodeInsertableData<ImplicitAllowedTypes>,
+			ImplicitlyConstructable,
+			T,
+			undefined
+		> as TreeNodeSchemaBoth<
+			ScopedSchemaName<TScope, Name>,
+			NodeKind.Map,
+			TreeMapNode<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Map>,
+			MapNodeInsertableData<T>,
+			ImplicitlyConstructable,
+			T,
+			undefined
+		>;
 	}
 
 	/**
@@ -901,7 +1002,22 @@ export class SchemaFactory<
 		T,
 		undefined
 	> {
-		return arraySchema(this.scoped(name), allowedTypes, implicitlyConstructable, customizable);
+		const array = arraySchema(
+			this.scoped(name),
+			allowedTypes,
+			implicitlyConstructable,
+			customizable,
+		);
+
+		return array as TreeNodeSchemaBoth<
+			ScopedSchemaName<TScope, Name>,
+			NodeKind.Array,
+			TreeArrayNode<T> & WithType<ScopedSchemaName<TScope, string>, NodeKind.Array>,
+			Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,
+			ImplicitlyConstructable,
+			T,
+			undefined
+		>;
 	}
 
 	/**
@@ -954,8 +1070,11 @@ export class SchemaFactory<
 	 * The identifier generated by the SharedTree has the following properties:
 	 *
 	 * - It is a UUID which will not collide with other generated UUIDs.
+	 *
 	 * - It is compressed to a space-efficient representation when stored in the document.
+	 *
 	 * - A compressed form of the identifier can be accessed at runtime via the {@link TreeNodeApi.shortId|Tree.shortId()} API.
+	 *
 	 * - It will error if read (and will not be present in the object's iterable properties) before the node has been inserted into a tree.
 	 *
 	 * However, a user may alternatively supply their own string as the identifier if desired (for example, if importing identifiers from another system).
@@ -1022,6 +1141,7 @@ export class SchemaFactory<
 	 * @remarks
 	 * This version of `SchemaFactory.array` uses the same workarounds as {@link SchemaFactory.objectRecursive}.
 	 * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.
+	 * See also {@link FixRecursiveArraySchema} for additional information specific to recursive arrays schema exports.
 	 */
 	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 	public arrayRecursive<

package/src/simple-tree/api/schemaFactoryAlpha.ts

@@ -12,6 +12,8 @@ import {
 } from "./schemaFactory.js";
 import type {
 	ImplicitAllowedTypes,
+	ImplicitAnnotatedAllowedTypes,
+	ImplicitAnnotatedFieldSchema,
 	ImplicitFieldSchema,
 	NodeSchemaOptions,
 } from "../schemaTypes.js";
@@ -56,9 +58,9 @@ export class SchemaFactoryAlpha<
 	 * @param fields - Schema for fields of the object node's schema. Defines what children can be placed under each key.
 	 * @param options - Additional options for the schema.
 	 */
-	public override object<
+	public objectAlpha<
 		const Name extends TName,
-		const T extends RestrictiveStringRecord<ImplicitFieldSchema>,
+		const T extends RestrictiveStringRecord<ImplicitAnnotatedFieldSchema>,
 		const TCustomMetadata = unknown,
 	>(
 		name: Name,
@@ -121,7 +123,7 @@ export class SchemaFactoryAlpha<
 		Pick<ObjectNodeSchema, "fields"> {
 		// TODO: syntax highting is vs code is broken here. Don't trust it. Use the compiler instead.
 		type TScopedName = ScopedSchemaName<TScope, Name>;
-		return this.object(
+		return this.objectAlpha(
 			name,
 			t as T & RestrictiveStringRecord<ImplicitFieldSchema>,
 			options,
@@ -184,7 +186,7 @@ export class SchemaFactoryAlpha<
 	 */
 	public mapAlpha<
 		Name extends TName,
-		const T extends ImplicitAllowedTypes,
+		const T extends ImplicitAnnotatedAllowedTypes,
 		const TCustomMetadata = unknown,
 	>(
 		name: Name,
@@ -228,7 +230,7 @@ export class SchemaFactoryAlpha<
 	 */
 	public arrayAlpha<
 		const Name extends TName,
-		const T extends ImplicitAllowedTypes,
+		const T extends ImplicitAnnotatedAllowedTypes,
 		const TCustomMetadata = unknown,
 	>(
 		name: Name,

package/src/simple-tree/api/schemaFactoryRecursive.ts

@@ -14,13 +14,7 @@ import {
 	type ImplicitFieldSchema,
 	type InsertableTreeNodeFromImplicitAllowedTypes,
 } from "../schemaTypes.js";
-import type {
-	NodeKind,
-	TreeNodeSchemaClass,
-	TreeNodeSchema,
-	WithType,
-	TreeNode,
-} from "../core/index.js";
+import type { NodeKind, TreeNodeSchema, WithType, TreeNode } from "../core/index.js";
 import type { FieldSchemaAlphaUnsafe, System_Unsafe } from "./typesUnsafe.js";
 
 export function createFieldSchemaUnsafe<
@@ -33,7 +27,11 @@ export function createFieldSchemaUnsafe<
 	props?: FieldProps<TCustomMetadata>,
 ): FieldSchemaAlphaUnsafe<Kind, Types, TCustomMetadata> {
 	// At runtime, we still want this to be a FieldSchema instance, but we can't satisfy its extends clause, so just return it as an FieldSchemaUnsafe
-	return createFieldSchema(kind, allowedTypes as ImplicitAllowedTypes & Types, props);
+	return createFieldSchema(
+		kind,
+		allowedTypes as ImplicitAllowedTypes & Types,
+		props,
+	) as FieldSchemaAlphaUnsafe<Kind, Types, TCustomMetadata>;
 }
 
 /**
@@ -159,37 +157,103 @@ export function createFieldSchemaUnsafe<
  */
 export type ValidateRecursiveSchema<
 	// Recursive types should always be using TreeNodeSchemaClass (not TreeNodeSchemaNonClass) as thats part of the requirements for the type to work across compilation boundaries correctly.
-	T extends TreeNodeSchemaClass<
-		// Name: This validator places no restrictions on the name other than that it's a string (as required by TreeNodeSchemaClass).
-		string,
-		// NodeKind: These are the NodeKinds which currently can be used recursively.
-		NodeKind.Array | NodeKind.Map | NodeKind.Object,
-		// TNode: The produced node API. This is pretty minimal validation: more could be added if similar to how TInsertable works below if needed.
-		TreeNode & WithType<T["identifier"], T["kind"]>,
-		// TInsertable: What can be passed to the constructor. This should be enough to catch most issues with incorrect schema.
-		// These match whats defined in the recursive methods on `SchemaFactory` except they do not use `Unenforced`.
-		{
-			[NodeKind.Object]: T["info"] extends RestrictiveStringRecord<ImplicitFieldSchema>
-				? InsertableObjectFromSchemaRecord<T["info"]>
-				: unknown;
-			[NodeKind.Array]: T["info"] extends ImplicitAllowedTypes
-				? Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T["info"]>>
-				: unknown;
-			[NodeKind.Map]: T["info"] extends ImplicitAllowedTypes
-				? Iterable<[string, InsertableTreeNodeFromImplicitAllowedTypes<T["info"]>]>
-				: unknown;
-		}[T["kind"]],
-		// ImplicitlyConstructable: recursive types are currently not implicitly constructable.
-		false,
-		// Info: What's passed to the method to create the schema. Constraining these here should be about as effective as if the actual constraints existed on the actual method itself.
-		{
-			[NodeKind.Object]: RestrictiveStringRecord<ImplicitFieldSchema>;
-			[NodeKind.Array]: ImplicitAllowedTypes;
-			[NodeKind.Map]: ImplicitAllowedTypes;
-		}[T["kind"]]
-	>,
+	T extends ValidateRecursiveSchemaTemplate<T>,
 > = true;
 
+/**
+ * Validation logic used by {@link ValidateRecursiveSchema}.
+ * @system @public
+ */
+export type ValidateRecursiveSchemaTemplate<T extends TreeNodeSchema> = TreeNodeSchema<
+	// Name: This validator places no restrictions on the name other than that it's a string (as required by TreeNodeSchemaClass).
+	string,
+	// NodeKind: These are the NodeKinds which currently can be used recursively.
+	NodeKind.Array | NodeKind.Map | NodeKind.Object,
+	// TNode: The produced node API. This is pretty minimal validation: more could be added if similar to how TInsertable works below if needed.
+	TreeNode & WithType<T["identifier"], T["kind"]>,
+	// TInsertable: What can be passed to the constructor. This should be enough to catch most issues with incorrect schema.
+	// These match whats defined in the recursive methods on `SchemaFactory` except they do not use `Unenforced`.
+	{
+		[NodeKind.Object]: T["info"] extends RestrictiveStringRecord<ImplicitFieldSchema>
+			? InsertableObjectFromSchemaRecord<T["info"]>
+			: unknown;
+		[NodeKind.Array]: T["info"] extends ImplicitAllowedTypes
+			? Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T["info"]>>
+			: unknown;
+		[NodeKind.Map]: T["info"] extends ImplicitAllowedTypes
+			? Iterable<[string, InsertableTreeNodeFromImplicitAllowedTypes<T["info"]>]>
+			: unknown;
+		[NodeKind.Leaf]: unknown;
+	}[T["kind"]],
+	// ImplicitlyConstructable: recursive types are currently not implicitly constructable.
+	false,
+	// Info: What's passed to the method to create the schema. Constraining these here should be about as effective as if the actual constraints existed on the actual method itself.
+	{
+		[NodeKind.Object]: RestrictiveStringRecord<ImplicitFieldSchema>;
+		[NodeKind.Array]: ImplicitAllowedTypes;
+		[NodeKind.Map]: ImplicitAllowedTypes;
+		[NodeKind.Leaf]: unknown;
+	}[T["kind"]]
+>;
+
+/**
+ * Workaround for "Type instantiation is excessively deep and possibly infinite.ts" errors.
+ * @remarks
+ *
+ * Generally this workaround should be avoided if possible,
+ * especially for exported types, as it is likely to result in issues when exporting or importing schema where the user will be forced to use the workaround as well.
+ * This is particularly problematic since in some cases it may not be possible for the user to replicate the pattern.
+ * Additionally, which cases hit these limits may vary based on TypeScript version and implementation details of this library.
+ *
+ * This workaround is provided and documented as a last resort to be able to keep an app compiling.
+ * Future version of SharedTree should provide schema type erasure functionality as a better alternative for most cases.
+ *
+ * When TypeScript gives the error "Error (TS2589) Type instantiation is excessively deep and possibly infinite." on the invocation of `ValidateRecursiveSchema`
+ * for a large schema, it can sometimes be worked around by repeating the usage of the type multiple times.
+ * This works because the TypeScript compiler caches some of the intermediate results from the first usage, and thus can get further on the second.
+ *
+ * This utility can be referenced when applying this pattern.
+ * For recursive types this can be used directly:
+ *
+ * ```typescript
+ * {
+ *     // @ts-expect-error Recursion limit
+ *     type _check1 = FixRecursiveRecursionLimit<typeof LargeType>;
+ *     type _check2 = FixRecursiveRecursionLimit<typeof LargeType>;
+ *     type _check3 = ValidateRecursiveSchemaTemplate<typeof LargeType>;
+ * }
+ * ```
+ *
+ * For non-recursive types, they can be ported to the more flexible recursive APIs and use the pattern above.
+ *
+ * Non-recursive types can also use this workaround by making a duplicate copy of the problematic schema written using the recursive APIs.
+ * Then this pattern can be applied to the duplicate copy.
+ *
+ * ```typescript
+ * // Workaround TypeScript recursion limit
+ * 	{
+ * 		class LargeUnionObjectNode_Fix extends schema.objectRecursive("ObjectNode", {
+ * 			x: largeUnion,
+ * 		}) {}
+ *
+ * 		// @ts-expect-error Recursion limit
+ * 		allowUnused<FixRecursiveRecursionLimit<typeof LargeUnionObjectNode_Fix>>();
+ * 		allowUnused<FixRecursiveRecursionLimit<typeof LargeUnionObjectNode_Fix>>();
+ * 		allowUnused<ValidateRecursiveSchema<typeof LargeUnionObjectNode_Fix>>();
+ * 		}
+ *
+ * 	// Fails to compile without the above workaround.
+ * 	class LargeUnionObjectNode extends schema.object("ObjectNode", { x: largeUnion }) {}
+ * ```
+ * @privateRemarks
+ * Using this is real sketchy, and leads to a lot of issues (errors which depend on how the schema is compiled, making different build setups produce different results and complicating exports).
+ * This is being kept as internal for now: if a customer really needs it, we have this as a documented workaround, but it would be much better to find an alternative solution before using this one.
+ * This uses ValidateRecursiveSchemaTemplate since it was found to evaluate enough of the type to work.
+ * @internal
+ */
+export type FixRecursiveRecursionLimit<T extends TreeNodeSchema> =
+	T extends ValidateRecursiveSchemaTemplate<T> ? undefined : undefined;
+
 /**
  * Does nothing with the provided value, but appears to use it to make unused locals warnings and errors go away.
  *
@@ -215,7 +279,7 @@ export function allowUnused<T>(t?: T): void {}
  *
  * This type always evaluates to `undefined` to ensure the dummy export (which doesn't exist at runtime) is typed correctly.
  *
- * [TypeScript Issue 59550](https://github.com/microsoft/TypeScript/issues/59550) tracks a suggestion which would make this workaround unnecessary.
+ * {@link https://github.com/microsoft/TypeScript/issues/59550|TypeScript Issue 59550} tracks a suggestion which would make this workaround unnecessary.
  *
  * @example Usage
  * Since recursive type handling in TypeScript is order dependent, putting just the right kind of usages of the type before the declarations can cause it to not hit this error.

package/src/simple-tree/api/schemaFromSimple.ts

@@ -18,7 +18,7 @@ import type {
 	SimpleTreeSchema,
 } from "../simpleSchema.js";
 import { SchemaFactoryAlpha } from "./schemaFactoryAlpha.js";
-import type { TreeSchema } from "./tree.js";
+import type { TreeSchema } from "./configuration.js";
 
 const factory = new SchemaFactoryAlpha(undefined);
 
@@ -100,7 +100,7 @@ function generateNode(
 			}
 			// Here allowUnknownOptionalFields is implicitly defaulting. This is a subjective policy choice:
 			// users of this code are expected to handle what ever choice this code makes for cases like this.
-			return factory.object(id, fields, { metadata: schema.metadata });
+			return factory.objectAlpha(id, fields, { metadata: schema.metadata });
 		}
 		case NodeKind.Array:
 			return factory.arrayAlpha(

package/src/simple-tree/api/simpleSchemaToJsonSchema.ts

@@ -26,7 +26,7 @@ import type {
 	SimpleMapNodeSchema,
 } from "../simpleSchema.js";
 import { NodeKind, type TreeNodeSchema } from "../core/index.js";
-import type { TreeSchema } from "./tree.js";
+import type { TreeSchema } from "./configuration.js";
 import type { TreeSchemaEncodingOptions } from "./getJsonSchema.js";
 import { ObjectNodeSchema } from "../objectNodeTypes.js";
 import { ArrayNodeSchema } from "../arrayNodeTypes.js";

package/src/simple-tree/api/storedSchema.ts

@@ -3,29 +3,34 @@
  * Licensed under the MIT License.
  */
 
-import type { ICodecOptions } from "../../codec/index.js";
+import type { FluidClientVersion, ICodecOptions } from "../../codec/index.js";
 import type { TreeStoredSchema } from "../../core/index.js";
 import {
 	defaultSchemaPolicy,
 	encodeTreeSchema,
 	makeSchemaCodec,
+	SchemaCodecVersion,
 } from "../../feature-libraries/index.js";
-// eslint-disable-next-line import/no-internal-modules
-import type { Format } from "../../feature-libraries/schema-index/index.js";
+import {
+	clientVersionToSchemaVersion,
+	type Format,
+	// eslint-disable-next-line import/no-internal-modules
+} from "../../feature-libraries/schema-index/index.js";
 import type { JsonCompatible } from "../../util/index.js";
-import type { ImplicitFieldSchema } from "../schemaTypes.js";
-import { toStoredSchema } from "../toStoredSchema.js";
+import { normalizeFieldSchema, type ImplicitFieldSchema } from "../schemaTypes.js";
+import { simpleToStoredSchema } from "../toStoredSchema.js";
 import type { SchemaCompatibilityStatus } from "./tree.js";
-import { ViewSchema } from "./view.js";
+import { SchemaCompatibilityTester } from "./schemaCompatibilityTester.js";
+import type { SimpleTreeSchema } from "../simpleSchema.js";
 
 /**
- * Dumps the "persisted" schema subset of the provided `schema` into a deterministic JSON-compatible, semi-human-readable, but unspecified format.
+ * Dumps the "persisted" schema subset of the provided `schema` into a deterministic JSON-compatible, semi-human-readable format.
+ *
+ * @param schema - The schema to dump.
  *
  * @remarks
  * This can be used to help inspect schema for debugging, and to save a snapshot of schema to help detect and review changes to an applications schema.
- *
- * This format may change across major versions of this package: such changes are considered breaking.
- * Beyond that, no compatibility guarantee is provided for this format: it should never be relied upon to load data, it should only be used for comparing outputs from this function.
+ * This format is also compatible with {@link ViewContent.schema}, {@link comparePersistedSchema} and {@link persistedToSimpleSchema}.
  *
  * This only includes the "persisted" subset of schema information, which means the portion which gets included in documents.
  * It thus uses "persisted" keys, see {@link FieldProps.key}.
@@ -38,7 +43,7 @@ import { ViewSchema } from "./view.js";
  * An application could use this API to generate a `schema.json` file when it first releases,
  * then test that the schema is sill compatible with documents from that version with a test like :
  * ```typescript
- * assert.deepEqual(extractPersistedSchema(MySchema), require("./schema.json"));
+ * assert.deepEqual(extractPersistedSchema(MySchema, FluidClientVersion.v2_0), require("./schema.json"));
  * ```
  *
  * @privateRemarks
@@ -48,9 +53,13 @@ import { ViewSchema } from "./view.js";
  * Public API surface uses "persisted" terminology while internally we use "stored".
  * @alpha
  */
-export function extractPersistedSchema(schema: ImplicitFieldSchema): JsonCompatible {
-	const stored = toStoredSchema(schema);
-	return encodeTreeSchema(stored);
+export function extractPersistedSchema(
+	schema: SimpleTreeSchema,
+	oldestCompatibleClient: FluidClientVersion,
+): JsonCompatible {
+	const stored = simpleToStoredSchema(schema);
+	const writeVersion = clientVersionToSchemaVersion(oldestCompatibleClient);
+	return encodeTreeSchema(stored, writeVersion);
 }
 
 /**
@@ -89,9 +98,15 @@ export function comparePersistedSchema(
 	options: ICodecOptions,
 	canInitialize: boolean,
 ): SchemaCompatibilityStatus {
-	const schemaCodec = makeSchemaCodec(options);
+	// Any version can be passed down to makeSchemaCodec here.
+	// We only use the decode part, which always dispatches to the correct codec based on the version in the data, not the version passed to `makeSchemaCodec`.
+	const schemaCodec = makeSchemaCodec(options, SchemaCodecVersion.v1);
 	const stored = schemaCodec.decode(persisted as Format);
-	const viewSchema = new ViewSchema(defaultSchemaPolicy, {}, view);
+	const viewSchema = new SchemaCompatibilityTester(
+		defaultSchemaPolicy,
+		{},
+		normalizeFieldSchema(view),
+	);
 	return comparePersistedSchemaInternal(stored, viewSchema, canInitialize);
 }
 
@@ -101,7 +116,7 @@ export function comparePersistedSchema(
  */
 export function comparePersistedSchemaInternal(
 	stored: TreeStoredSchema,
-	viewSchema: ViewSchema,
+	viewSchema: SchemaCompatibilityTester,
 	canInitialize: boolean,
 ): SchemaCompatibilityStatus {
 	return {