@fluidframework/tree 2.31.0 → 2.32.0

package/src/shared-tree/treeApiAlpha.ts

@@ -30,10 +30,9 @@ import {
 	applySchemaToParserOptions,
 	cursorFromVerbose,
 	verboseFromCursor,
-	type ParseOptions,
+	type TreeEncodingOptions,
 	type VerboseTree,
 	toStoredSchema,
-	type EncodeOptions,
 	extractPersistedSchema,
 	TreeViewConfiguration,
 	type TreeBranch,
@@ -129,20 +128,20 @@ export const TreeAlpha: {
 	importVerbose<const TSchema extends ImplicitFieldSchema>(
 		schema: TSchema,
 		data: VerboseTree | undefined,
-		options?: Partial<ParseOptions>,
+		options?: Partial<TreeEncodingOptions>,
 	): Unhydrated<TreeFieldFromImplicitField<TSchema>>;
 
 	/**
 	 * Copy a snapshot of the current version of a TreeNode into a {@link ConciseTree}.
 	 */
-	exportConcise(node: TreeNode | TreeLeafValue, options?: EncodeOptions): ConciseTree;
+	exportConcise(node: TreeNode | TreeLeafValue, options?: TreeEncodingOptions): ConciseTree;
 
 	/**
 	 * Copy a snapshot of the current version of a TreeNode into a {@link ConciseTree}, allowing undefined.
 	 */
 	exportConcise(
 		node: TreeNode | TreeLeafValue | undefined,
-		options?: EncodeOptions,
+		options?: TreeEncodingOptions,
 	): ConciseTree | undefined;
 
 	/**
@@ -159,7 +158,7 @@ export const TreeAlpha: {
 	 *
 	 * 3. When easy access to the type is desired.
 	 */
-	exportVerbose(node: TreeNode | TreeLeafValue, options?: EncodeOptions): VerboseTree;
+	exportVerbose(node: TreeNode | TreeLeafValue, options?: TreeEncodingOptions): VerboseTree;
 
 	/**
 	 * Export the content of the provided `tree` in a compressed JSON compatible format.
@@ -167,7 +166,7 @@ export const TreeAlpha: {
 	 * If an `idCompressor` is provided, it will be used to compress identifiers and thus will be needed to decompress the data.
 	 *
 	 * Always uses "stored" keys.
-	 * See {@link EncodeOptions.useStoredKeys} for details.
+	 * See {@link TreeEncodingOptions.useStoredKeys} for details.
 	 * @privateRemarks
 	 * TODO: It is currently not clear how to work with the idCompressors correctly in the package API.
 	 * Better APIs should probably be provided as there is currently no way to associate an un-hydrated tree with an idCompressor,
@@ -243,9 +242,9 @@ export const TreeAlpha: {
 	importVerbose<const TSchema extends ImplicitFieldSchema>(
 		schema: TSchema,
 		data: VerboseTree | undefined,
-		options?: ParseOptions,
+		options?: TreeEncodingOptions,
 	): Unhydrated<TreeFieldFromImplicitField<TSchema>> {
-		const config: ParseOptions = { ...options };
+		const config: TreeEncodingOptions = { ...options };
 		// Create a config which is standalone, and thus can be used without having to refer back to the schema.
 		const schemalessConfig = applySchemaToParserOptions(schema, config);
 		if (data === undefined) {
@@ -261,8 +260,8 @@ export const TreeAlpha: {
 
 	exportConcise,
 
-	exportVerbose(node: TreeNode | TreeLeafValue, options?: EncodeOptions): VerboseTree {
-		const config: EncodeOptions = { ...options };
+	exportVerbose(node: TreeNode | TreeLeafValue, options?: TreeEncodingOptions): VerboseTree {
+		const config: TreeEncodingOptions = { ...options };
 
 		const cursor = borrowCursorFromTreeNodeOrValue(node);
 		return verboseFromCursor(
@@ -314,21 +313,24 @@ export const TreeAlpha: {
 	},
 };
 
-function exportConcise(node: TreeNode | TreeLeafValue, options?: EncodeOptions): ConciseTree;
+function exportConcise(
+	node: TreeNode | TreeLeafValue,
+	options?: TreeEncodingOptions,
+): ConciseTree;
 
 function exportConcise(
 	node: TreeNode | TreeLeafValue | undefined,
-	options?: EncodeOptions,
+	options?: TreeEncodingOptions,
 ): ConciseTree | undefined;
 
 function exportConcise(
 	node: TreeNode | TreeLeafValue | undefined,
-	options?: EncodeOptions,
+	options?: TreeEncodingOptions,
 ): ConciseTree | undefined {
 	if (node === undefined) {
 		return undefined;
 	}
-	const config: EncodeOptions = { ...options };
+	const config: TreeEncodingOptions = { ...options };
 
 	const cursor = borrowCursorFromTreeNodeOrValue(node);
 	return conciseFromCursor(

package/src/shared-tree-core/sharedTreeCore.ts

@@ -6,7 +6,6 @@
 import { assert } from "@fluidframework/core-utils/internal";
 import type { IChannelStorageService } from "@fluidframework/datastore-definitions/internal";
 import type { IIdCompressor, SessionId } from "@fluidframework/id-compressor";
-import type { ISequencedDocumentMessage } from "@fluidframework/driver-definitions/internal";
 import type {
 	IExperimentalIncrementalSummaryContext,
 	IRuntimeMessageCollection,
@@ -331,28 +330,6 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 		this.resubmitMachine.onCommitSubmitted(enrichedCommit);
 	}
 
-	/**
-	 * Process a message from the runtime.
-	 * @deprecated - Use processMessagesCore to process a bunch of messages together.
-	 */
-	public processCore(
-		message: ISequencedDocumentMessage,
-		local: boolean,
-		localOpMetadata: unknown,
-	): void {
-		this.processMessagesCore({
-			envelope: message,
-			local,
-			messagesContent: [
-				{
-					clientSequenceNumber: message.clientSequenceNumber,
-					contents: message.contents,
-					localOpMetadata,
-				},
-			],
-		});
-	}
-
 	/**
 	 * Process a bunch of messages from the runtime. SharedObject will call this method with a bunch of messages.
 	 */

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

@@ -11,7 +11,7 @@ import type { TreeNodeSchema } from "../core/index.js";
 import {
 	customFromCursor,
 	replaceHandles,
-	type EncodeOptions,
+	type TreeEncodingOptions,
 	type HandleConverter,
 } from "./customTree.js";
 import { getUnhydratedContext } from "../createContext.js";
@@ -44,9 +44,9 @@ export type ConciseTree<THandle = IFluidHandle> =
 export function conciseFromCursor(
 	reader: ITreeCursor,
 	rootSchema: ImplicitAllowedTypes,
-	options: EncodeOptions,
+	options: TreeEncodingOptions,
 ): ConciseTree {
-	const config: Required<EncodeOptions> = {
+	const config: Required<TreeEncodingOptions> = {
 		useStoredKeys: false,
 		...options,
 	};
@@ -57,7 +57,7 @@ export function conciseFromCursor(
 
 function conciseFromCursorInner(
 	reader: ITreeCursor,
-	options: Required<EncodeOptions>,
+	options: Required<TreeEncodingOptions>,
 	schema: ReadonlyMap<string, TreeNodeSchema>,
 ): ConciseTree {
 	return customFromCursor(reader, options, schema, conciseFromCursorInner);

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

@@ -33,26 +33,20 @@ import { isObjectNodeSchema } from "../objectNodeTypes.js";
 import { FieldKinds, valueSchemaAllows } from "../../feature-libraries/index.js";
 
 /**
- * Options for how to encode a tree.
+ * Options for how to interpret or encode a tree when schema information is available.
  * @alpha
  */
-export interface EncodeOptions {
+export interface TreeEncodingOptions {
 	/**
-	 * If true, interpret the input keys of object nodes as stored keys.
-	 * If false, interpret them as property keys.
+	 * If true, use the stored keys of object nodes.
+	 * If false, use the property keys.
+	 * @remarks
+	 * Has no effect on {@link NodeKind}s other than {@link NodeKind.Object}.
 	 * @defaultValue false.
 	 */
 	readonly useStoredKeys?: boolean;
 }
 
-/**
- * Options for how to transcode handles.
- * @remarks
- * Can be applied using {@link replaceHandles}.
- * @alpha
- */
-export type HandleConverter<TCustom> = (data: IFluidHandle) => TCustom;
-
 /**
  * Options for how to interpret a `ConciseTree<TCustom>` without relying on schema.
  */
@@ -86,11 +80,11 @@ export type CustomTreeNode<TChild> = TChild[] | { [key: string]: TChild };
  */
 export function customFromCursor<TChild>(
 	reader: ITreeCursor,
-	options: Required<EncodeOptions>,
+	options: Required<TreeEncodingOptions>,
 	schema: ReadonlyMap<string, TreeNodeSchema>,
 	childHandler: (
 		reader: ITreeCursor,
-		options: Required<EncodeOptions>,
+		options: Required<TreeEncodingOptions>,
 		schema: ReadonlyMap<string, TreeNodeSchema>,
 	) => TChild,
 ): CustomTree<TChild> {
@@ -203,6 +197,14 @@ export function tryStoredSchemaAsArray(
 	}
 }
 
+/**
+ * Options for how to transcode handles.
+ * @remarks
+ * Can be applied using {@link replaceHandles}.
+ * @alpha
+ */
+export type HandleConverter<TCustom> = (data: IFluidHandle) => TCustom;
+
 /**
  * Clones tree, replacing any handles.
  * @remarks

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

@@ -4,16 +4,25 @@
  */
 
 import type { JsonTreeSchema } from "./jsonSchema.js";
-import type { ImplicitFieldSchema } from "../schemaTypes.js";
+import type { ImplicitAllowedTypes } from "../schemaTypes.js";
 import { toJsonSchema } from "./simpleSchemaToJsonSchema.js";
-import { getSimpleSchema } from "./getSimpleSchema.js";
-import { getOrCreate } from "../../util/index.js";
-import type { TreeNodeSchema } from "../core/index.js";
+import type { TreeEncodingOptions } from "./customTree.js";
+import { TreeViewConfigurationAlpha } from "./tree.js";
 
 /**
- * Cache in which the results of {@link getJsonSchema} are saved.
+ * Options for how to interpret or encode a tree when schema information is available.
+ * @alpha
  */
-const jsonSchemaCache = new WeakMap<TreeNodeSchema, JsonTreeSchema>();
+export interface TreeSchemaEncodingOptions extends TreeEncodingOptions {
+	/**
+	 * If true, fields with default providers (like {@link SchemaFactory.identifier}) will be required.
+	 * If false, they will be optional.
+	 * @remarks
+	 * Has no effect on {@link NodeKind}s other than {@link NodeKind.Object}.
+	 * @defaultValue false.
+	 */
+	readonly requireFieldsWithDefaults?: boolean;
+}
 
 /**
  * Creates a {@link https://json-schema.org/ | JSON Schema} representation of the provided {@link TreeNodeSchema}.
@@ -63,18 +72,18 @@ const jsonSchemaCache = new WeakMap<TreeNodeSchema, JsonTreeSchema>();
  * TODO:
  * This API should allow generating JSON schema for the whole matrix of combinations:
  *
- * 1. VerboseTree and ConciseTree
- * 2. With and without requiring values with defaults (for insertion vs reading)
- * 3. Using stored keys and property keys
- *
- * This current API seems to give ConciseTree with property keys and ignoring default values.
+ * 1. VerboseTree and (Done) ConciseTree
+ * 2. (Done) With and without requiring values with defaults (for insertion vs reading)
+ * 3. (Done) Using stored keys and property keys.
  *
+ * This takes in `ImplicitAllowedTypes` since underlying `toJsonSchema` can't handle optional roots.
  *
  * @alpha
  */
-export function getJsonSchema(schema: ImplicitFieldSchema): JsonTreeSchema {
-	return getOrCreate(jsonSchemaCache, schema, () => {
-		const simpleSchema = getSimpleSchema(schema);
-		return toJsonSchema(simpleSchema);
-	});
+export function getJsonSchema(
+	schema: ImplicitAllowedTypes,
+	options: Required<TreeSchemaEncodingOptions>,
+): JsonTreeSchema {
+	const treeSchema = new TreeViewConfigurationAlpha({ schema });
+	return toJsonSchema(treeSchema, options);
 }

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

@@ -3,39 +3,25 @@
  * Licensed under the MIT License.
  */
 
-import { getOrCreate } from "../../util/index.js";
-import type { TreeNodeSchema } from "../core/index.js";
 import type { ImplicitFieldSchema } from "../schemaTypes.js";
 import type { SimpleTreeSchema } from "../simpleSchema.js";
 import { toSimpleTreeSchema } from "./viewSchemaToSimpleSchema.js";
 
 /**
- * Cache in which the results of {@link getSimpleSchema} saved.
- */
-const simpleSchemaCache = new WeakMap<TreeNodeSchema, SimpleTreeSchema>();
-
-/**
- * Creates a {@link SimpleTreeSchema} from the provided {@link ImplicitFieldSchema}.
+ * Copies data from {@link ImplicitFieldSchema} to create  a {@link SimpleTreeSchema} out of new plain JavaScript objects, Sets and Maps.
  *
  * @remarks
- * This provides easy access by identifier to any schema transitively referenced by the input schema via {@link SimpleTreeSchema.definitions}.
- *
- * Caches the result on the input schema for future calls.
+ * See also {@link TreeViewConfigurationAlpha} which implements {@link SimpleTreeSchema} as a way to get a `SimpleTreeSchema` without copying the node and field schema and without losing as much type information.
  *
  * @privateRemarks
  * In the future, we may wish to move this to a more discoverable API location.
  * For now, while still an experimental API, it is surfaced as a free function.
  *
- * If the main use for this is the "definitions" map, we should provide a better way to access it (that doesn't type erase the TreeNodeSchema down to SimpleNodeSchema).
- * TODO: Having TreeViewConfiguration implement SimpleTreeSchema directly but with more specific types would be a good way to do this.
- *
  * Note that all TreeNodeSchema get a {@link Context} cached on them as part of one time initialization which contains a map from identifier to all transitively referenced schema.
  * Perhaps exposing access to that would cover this use-case as well.
  *
- * TODO: does having this caching layer add value? Maybe this wrapper around toSimpleTreeSchema should be removed.
- *
- * @internal
+ * @alpha
  */
 export function getSimpleSchema(schema: ImplicitFieldSchema): SimpleTreeSchema {
-	return getOrCreate(simpleSchemaCache, schema, () => toSimpleTreeSchema(schema, false));
+	return toSimpleTreeSchema(schema, true);
 }

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

@@ -9,6 +9,8 @@ export {
 	type ViewableTree,
 	type TreeViewEvents,
 	TreeViewConfiguration,
+	TreeViewConfigurationAlpha,
+	type TreeSchema,
 	type ITreeViewConfiguration,
 	type SchemaCompatibilityStatus,
 	type ITreeConfigurationOptions,
@@ -51,6 +53,7 @@ export {
 	type JsonFieldSchema,
 	type JsonLeafSchemaType,
 } from "./jsonSchema.js";
+export type { TreeSchemaEncodingOptions } from "./getJsonSchema.js";
 export { getJsonSchema } from "./getJsonSchema.js";
 export { getSimpleSchema } from "./getSimpleSchema.js";
 export { ViewSchema } from "./view.js";
@@ -85,7 +88,6 @@ export type {
 
 export {
 	type VerboseTreeNode,
-	type ParseOptions,
 	type VerboseTree,
 	applySchemaToParserOptions,
 	cursorFromVerbose,
@@ -94,7 +96,7 @@ export {
 } from "./verboseTree.js";
 
 export {
-	type EncodeOptions,
+	type TreeEncodingOptions,
 	customFromCursorStored,
 	type CustomTreeNode,
 	type CustomTreeValue,

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

@@ -69,7 +69,19 @@ export class SchemaFactoryAlpha<
 		name: Name,
 		fields: T,
 		options?: SchemaFactoryObjectOptions<TCustomMetadata>,
-	): ObjectNodeSchema<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata> {
+	): ObjectNodeSchema<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata> & {
+		/**
+		 * Typing checking workaround: not for for actual use.
+		 * @remarks
+		 * This API collides with {@link TreeNodeSchemaCore.createFromInsertable} to disable a type checking optimization which produces different and undesired results.
+		 * See {@link https://github.com/microsoft/TypeScript/issues/59049#issuecomment-2773459693} for more details.
+		 * @privateRemarks
+		 * The specific issue here is non-empty POJO mode object schema not being assignable to `ObjectNodeSchema`,
+		 * See the above link and the tests in objectNode.spec.ts which reference it.
+		 * @system
+		 */
+		readonly createFromInsertable: unknown;
+	} {
 		return objectSchema(
 			this.scoped2(name),
 			fields,
@@ -136,6 +148,11 @@ export class SchemaFactoryAlpha<
 			>;
 	}
 
+	/**
+	 * {@inheritDoc SchemaStatics.optional}
+	 */
+	public static override readonly leaves = schemaStatics.leaves;
+
 	/**
 	 * {@inheritDoc SchemaStatics.optional}
 	 */

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

@@ -10,14 +10,15 @@ import {
 	type AllowedTypes,
 	type FieldSchemaAlpha,
 	FieldKind,
+	type FieldProps,
 } from "../schemaTypes.js";
-import { SchemaFactory } from "./schemaFactory.js";
 import type {
 	SimpleFieldSchema,
 	SimpleNodeSchema,
 	SimpleTreeSchema,
 } from "../simpleSchema.js";
 import { SchemaFactoryAlpha } from "./schemaFactoryAlpha.js";
+import type { TreeSchema } from "./tree.js";
 
 const factory = new SchemaFactoryAlpha(undefined);
 
@@ -30,31 +31,53 @@ const factory = new SchemaFactoryAlpha(undefined);
  * will produce a poor TypeScript typing experience which is subject to change.
  *
  * Editing through a view produced using this schema can easily violate invariants other users of the document might expect and must be done with great care.
+ *
+ * This API bakes in some arbitrary policy choices for how to handle data that is not included in the SimpleTreeSchema API, for example the value of `allowUnknownOptionalFields`.
+ * If any particular choice is required for such cases, this API should not be used.
  * @alpha
  */
-export function generateSchemaFromSimpleSchema(simple: SimpleTreeSchema): FieldSchemaAlpha {
+export function generateSchemaFromSimpleSchema(simple: SimpleTreeSchema): TreeSchema {
 	const context: Context = new Map(
-		[...simple.definitions].map(([id, schema]): [string, () => TreeNodeSchema] => [
-			id,
-			// This relies on the caching in evaluateLazySchema so that it only runs once.
-			() => generateNode(id, schema, context),
-		]),
+		[...simple.definitions].map(
+			([id, schema]): [string, () => TreeNodeSchema & SimpleNodeSchema] => [
+				id,
+				// This relies on the caching in evaluateLazySchema so that it only runs once.
+				() => generateNode(id, schema, context),
+			],
+		),
 	);
-	return generateFieldSchema(simple, context);
+	const root = generateFieldSchema(simple.root, context, undefined);
+	const definitions = new Map<string, TreeNodeSchema & SimpleNodeSchema>();
+	for (const [id, lazy] of context) {
+		definitions.set(id, lazy());
+	}
+	return {
+		root,
+		definitions,
+	};
 }
 
-type Context = ReadonlyMap<string, () => TreeNodeSchema>;
+type Context = ReadonlyMap<string, () => TreeNodeSchema & SimpleNodeSchema>;
 
-function generateFieldSchema(simple: SimpleFieldSchema, context: Context): FieldSchemaAlpha {
+function generateFieldSchema(
+	simple: SimpleFieldSchema,
+	context: Context,
+	storedKey: string | undefined,
+): FieldSchemaAlpha {
 	const allowed = generateAllowedTypes(simple.allowedTypesIdentifiers, context);
+	const props: Omit<FieldProps, "defaultProvider"> = {
+		metadata: simple.metadata,
+		key: storedKey,
+	};
+
 	// Using createFieldSchema could work, but would require setting up the default providers.
 	switch (simple.kind) {
 		case FieldKind.Identifier:
-			return SchemaFactoryAlpha.identifier({ metadata: simple.metadata });
+			return SchemaFactoryAlpha.identifier(props);
 		case FieldKind.Optional:
-			return SchemaFactoryAlpha.optional(allowed, { metadata: simple.metadata });
+			return SchemaFactoryAlpha.optional(allowed, props);
 		case FieldKind.Required:
-			return SchemaFactoryAlpha.required(allowed, { metadata: simple.metadata });
+			return SchemaFactoryAlpha.required(allowed, props);
 		default:
 			return unreachableCase(simple.kind);
 	}
@@ -64,13 +87,19 @@ function generateAllowedTypes(allowed: ReadonlySet<string>, context: Context): A
 	return [...allowed].map((id) => context.get(id) ?? fail(0xb5a /* Missing schema */));
 }
 
-function generateNode(id: string, schema: SimpleNodeSchema, context: Context): TreeNodeSchema {
+function generateNode(
+	id: string,
+	schema: SimpleNodeSchema,
+	context: Context,
+): TreeNodeSchema & SimpleNodeSchema {
 	switch (schema.kind) {
 		case NodeKind.Object: {
 			const fields: Record<string, FieldSchema> = {};
 			for (const [key, field] of schema.fields) {
-				fields[key] = generateFieldSchema(field, context);
+				fields[key] = generateFieldSchema(field, context, field.storedKey);
 			}
+			// 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 });
 		}
 		case NodeKind.Array:
@@ -87,7 +116,7 @@ function generateNode(id: string, schema: SimpleNodeSchema, context: Context): T
 			);
 		case NodeKind.Leaf:
 			return (
-				SchemaFactory.leaves.find((leaf) => leaf.identifier === id) ??
+				SchemaFactoryAlpha.leaves.find((leaf) => leaf.identifier === id) ??
 				fail(0xb5b /* Missing schema */)
 			);
 		default:

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

@@ -6,7 +6,7 @@
 import { unreachableCase } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import { ValueSchema } from "../../core/index.js";
-import { copyProperty, getOrCreate, hasSingle, type Mutable } from "../../util/index.js";
+import { copyProperty, hasSingle, type Mutable } from "../../util/index.js";
 import type {
 	JsonArrayNodeSchema,
 	JsonFieldSchema,
@@ -24,24 +24,39 @@ import type {
 	SimpleArrayNodeSchema,
 	SimpleLeafNodeSchema,
 	SimpleMapNodeSchema,
-	SimpleNodeSchema,
-	SimpleObjectNodeSchema,
-	SimpleTreeSchema,
 } from "../simpleSchema.js";
-import { NodeKind } from "../core/index.js";
+import { NodeKind, type TreeNodeSchema } from "../core/index.js";
+import type { TreeSchema } from "./tree.js";
+import type { TreeSchemaEncodingOptions } from "./getJsonSchema.js";
+import { ObjectNodeSchema } from "../objectNodeTypes.js";
+import { ArrayNodeSchema } from "../arrayNodeTypes.js";
+import { MapNodeSchema } from "../mapNodeTypes.js";
+import { LeafNodeSchema } from "../leafNodeSchema.js";
 
 /**
  * Generates a JSON Schema representation from a simple tree schema.
+ * @remarks
+ * This expects the data to be in the {@link ConciseTree} format.
+ *
+ * This cannot handle the case where the root is undefined since undefined is not a concept in JSON.
+ * This also cannot handle {@link SchemaStatics.handle} since they also are not supported in JSON.
+ *
  * @internal
  */
-export function toJsonSchema(schema: SimpleTreeSchema): JsonTreeSchema {
-	const definitions = convertDefinitions(schema.definitions);
+export function toJsonSchema(
+	schema: TreeSchema,
+	options: Required<TreeSchemaEncodingOptions>,
+): JsonTreeSchema {
+	const definitions = convertDefinitions(schema.definitions, options);
 
 	const allowedTypes: JsonSchemaRef[] = [];
-	for (const allowedType of schema.allowedTypesIdentifiers) {
+	for (const allowedType of schema.root.allowedTypesIdentifiers) {
 		allowedTypes.push(createSchemaRef(allowedType));
 	}
 
+	// TODO: deduplicate field handling logic from convertObjectNodeSchema: at least include metadata's description.
+	// TODO: maybe account for consider schema.kind, or just take in ImplicitAllowedTypes
+	// TODO: handle case where allowedTypes is empty.
 	return hasSingle(allowedTypes)
 		? {
 				...allowedTypes[0],
@@ -54,40 +69,35 @@ export function toJsonSchema(schema: SimpleTreeSchema): JsonTreeSchema {
 }
 
 function convertDefinitions(
-	definitions: ReadonlyMap<string, SimpleNodeSchema>,
+	definitions: ReadonlyMap<string, TreeNodeSchema>,
+	options: Required<TreeSchemaEncodingOptions>,
 ): Record<string, JsonNodeSchema> {
 	const result: Record<string, JsonNodeSchema> = {};
 	for (const [key, value] of definitions) {
-		result[key] = convertNodeSchema(value);
+		result[key] = convertNodeSchema(value, options);
 	}
 	return result;
 }
 
-/**
- * Private symbol under which the results of {@link convertNodeSchema} are cached on an input {@link SimpleNodeSchema}.
- */
-const nodeJsonSchemaCache = new WeakMap<SimpleNodeSchema, JsonNodeSchema>();
-
 /**
  * Converts an input {@link SimpleNodeSchema} to a {@link JsonNodeSchema}.
  *
  * @remarks Caches the result on the input schema for future calls.
  */
-function convertNodeSchema(schema: SimpleNodeSchema): JsonNodeSchema {
-	return getOrCreate(nodeJsonSchemaCache, schema, () => {
-		switch (schema.kind) {
-			case NodeKind.Array:
-				return convertArrayNodeSchema(schema);
-			case NodeKind.Leaf:
-				return convertLeafNodeSchema(schema);
-			case NodeKind.Map:
-				return convertMapNodeSchema(schema);
-			case NodeKind.Object:
-				return convertObjectNodeSchema(schema);
-			default:
-				throw new TypeError(`Unknown node schema kind: ${(schema as SimpleNodeSchema).kind}`);
-		}
-	});
+function convertNodeSchema(
+	schema: TreeNodeSchema,
+	options: Required<TreeSchemaEncodingOptions>,
+): JsonNodeSchema {
+	if (schema instanceof ArrayNodeSchema) {
+		return convertArrayNodeSchema(schema);
+	} else if (schema instanceof MapNodeSchema) {
+		return convertMapNodeSchema(schema);
+	} else if (schema instanceof ObjectNodeSchema) {
+		return convertObjectNodeSchema(schema, options);
+	} else if (schema instanceof LeafNodeSchema) {
+		return convertLeafNodeSchema(schema);
+	}
+	throw new TypeError(`Unknown node schema kind: ${schema.kind}`);
 }
 
 function convertArrayNodeSchema(schema: SimpleArrayNodeSchema): JsonArrayNodeSchema {
@@ -138,10 +148,14 @@ function convertLeafNodeSchema(schema: SimpleLeafNodeSchema): JsonLeafNodeSchema
 	};
 }
 
-export function convertObjectNodeSchema(schema: SimpleObjectNodeSchema): JsonObjectNodeSchema {
+export function convertObjectNodeSchema(
+	schema: ObjectNodeSchema,
+	options: Required<TreeSchemaEncodingOptions>,
+): JsonObjectNodeSchema {
 	const properties: Record<string, JsonFieldSchema> = {};
 	const required: string[] = [];
-	for (const [key, fieldSchema] of schema.fields) {
+	for (const [propertyKey, fieldSchema] of schema.fields) {
+		const key = options.useStoredKeys ? fieldSchema.storedKey : propertyKey;
 		const allowedTypes: JsonSchemaRef[] = [];
 		for (const allowedType of fieldSchema.allowedTypesIdentifiers) {
 			allowedTypes.push(createSchemaRef(allowedType));
@@ -156,8 +170,13 @@ export function convertObjectNodeSchema(schema: SimpleObjectNodeSchema): JsonObj
 		copyProperty(fieldSchema.metadata, "description", output);
 		properties[key] = output;
 
-		if (fieldSchema.kind === FieldKind.Required) {
-			required.push(key);
+		if (fieldSchema.kind !== FieldKind.Optional) {
+			if (
+				options.requireFieldsWithDefaults ||
+				fieldSchema.props?.defaultProvider === undefined
+			) {
+				required.push(key);
+			}
 		}
 	}