Shared Tree: Persisted Schema Format v2 with persisted metadata support

.changeset/brown-dingos-switch.md

@@ -0,0 +1,7 @@
+---
+"@fluidframework/tree": minor
+"__section": feature
+---
+Added a v2 Shared Tree schema with support for persisted metadata.
+
+This change adds support for persisted metadata, but does not enable it by default.

packages/dds/tree/api-report/tree.alpha.api.md

@@ -216,6 +216,7 @@ export interface FieldSchemaAlphaUnsafe<out Kind extends FieldKind, out Types ex
 export interface FieldSchemaMetadata<TCustomMetadata = unknown> {
     readonly custom?: TCustomMetadata;
     readonly description?: string | undefined;
+    readonly persistedMetadata?: JsonCompatibleReadOnlyObject | undefined;
 }
 
 // @alpha
@@ -443,6 +444,14 @@ export type JsonCompatibleObject<TExtra = never> = {
     [P in string]?: JsonCompatible<TExtra>;
 };
 
+// @public
+export type JsonCompatibleReadOnly = string | number | boolean | null | readonly JsonCompatibleReadOnly[] | JsonCompatibleReadOnlyObject;
+
+// @public
+export type JsonCompatibleReadOnlyObject = {
+    readonly [P in string]?: JsonCompatibleReadOnly;
+};
+
 // @alpha @sealed
 export type JsonFieldSchema = {
     readonly description?: string | undefined;
@@ -584,6 +593,7 @@ export enum NodeKind {
 export interface NodeSchemaMetadata<out TCustomMetadata = unknown> {
     readonly custom?: TCustomMetadata | undefined;
     readonly description?: string | undefined;
+    readonly persistedMetadata?: JsonCompatibleReadOnlyObject | undefined;
 }
 
 // @public @sealed

packages/dds/tree/api-report/tree.beta.api.md

@@ -77,6 +77,7 @@ export class FieldSchema<out Kind extends FieldKind = FieldKind, out Types exten
 export interface FieldSchemaMetadata<TCustomMetadata = unknown> {
     readonly custom?: TCustomMetadata;
     readonly description?: string | undefined;
+    readonly persistedMetadata?: JsonCompatibleReadOnlyObject | undefined;
 }
 
 // @public @system
@@ -176,6 +177,14 @@ export interface ITreeViewConfiguration<TSchema extends ImplicitFieldSchema = Im
     readonly schema: TSchema;
 }
 
+// @public
+export type JsonCompatibleReadOnly = string | number | boolean | null | readonly JsonCompatibleReadOnly[] | JsonCompatibleReadOnlyObject;
+
+// @public
+export type JsonCompatibleReadOnlyObject = {
+    readonly [P in string]?: JsonCompatibleReadOnly;
+};
+
 // @public
 export type LazyItem<Item = unknown> = Item | (() => Item);
 
@@ -227,6 +236,7 @@ export enum NodeKind {
 export interface NodeSchemaMetadata<out TCustomMetadata = unknown> {
     readonly custom?: TCustomMetadata | undefined;
     readonly description?: string | undefined;
+    readonly persistedMetadata?: JsonCompatibleReadOnlyObject | undefined;
 }
 
 // @public @sealed

packages/dds/tree/api-report/tree.legacy.alpha.api.md

@@ -77,6 +77,7 @@ export class FieldSchema<out Kind extends FieldKind = FieldKind, out Types exten
 export interface FieldSchemaMetadata<TCustomMetadata = unknown> {
     readonly custom?: TCustomMetadata;
     readonly description?: string | undefined;
+    readonly persistedMetadata?: JsonCompatibleReadOnlyObject | undefined;
 }
 
 // @public @system
@@ -176,6 +177,14 @@ export interface ITreeViewConfiguration<TSchema extends ImplicitFieldSchema = Im
     readonly schema: TSchema;
 }
 
+// @public
+export type JsonCompatibleReadOnly = string | number | boolean | null | readonly JsonCompatibleReadOnly[] | JsonCompatibleReadOnlyObject;
+
+// @public
+export type JsonCompatibleReadOnlyObject = {
+    readonly [P in string]?: JsonCompatibleReadOnly;
+};
+
 // @public
 export type LazyItem<Item = unknown> = Item | (() => Item);
 
@@ -222,6 +231,7 @@ export enum NodeKind {
 export interface NodeSchemaMetadata<out TCustomMetadata = unknown> {
     readonly custom?: TCustomMetadata | undefined;
     readonly description?: string | undefined;
+    readonly persistedMetadata?: JsonCompatibleReadOnlyObject | undefined;
 }
 
 // @public @sealed

packages/dds/tree/api-report/tree.legacy.public.api.md

@@ -77,6 +77,7 @@ export class FieldSchema<out Kind extends FieldKind = FieldKind, out Types exten
 export interface FieldSchemaMetadata<TCustomMetadata = unknown> {
     readonly custom?: TCustomMetadata;
     readonly description?: string | undefined;
+    readonly persistedMetadata?: JsonCompatibleReadOnlyObject | undefined;
 }
 
 // @public @system
@@ -176,6 +177,14 @@ export interface ITreeViewConfiguration<TSchema extends ImplicitFieldSchema = Im
     readonly schema: TSchema;
 }
 
+// @public
+export type JsonCompatibleReadOnly = string | number | boolean | null | readonly JsonCompatibleReadOnly[] | JsonCompatibleReadOnlyObject;
+
+// @public
+export type JsonCompatibleReadOnlyObject = {
+    readonly [P in string]?: JsonCompatibleReadOnly;
+};
+
 // @public
 export type LazyItem<Item = unknown> = Item | (() => Item);
 
@@ -222,6 +231,7 @@ export enum NodeKind {
 export interface NodeSchemaMetadata<out TCustomMetadata = unknown> {
     readonly custom?: TCustomMetadata | undefined;
     readonly description?: string | undefined;
+    readonly persistedMetadata?: JsonCompatibleReadOnlyObject | undefined;
 }
 
 // @public @sealed

packages/dds/tree/api-report/tree.public.api.md

@@ -77,6 +77,7 @@ export class FieldSchema<out Kind extends FieldKind = FieldKind, out Types exten
 export interface FieldSchemaMetadata<TCustomMetadata = unknown> {
     readonly custom?: TCustomMetadata;
     readonly description?: string | undefined;
+    readonly persistedMetadata?: JsonCompatibleReadOnlyObject | undefined;
 }
 
 // @public @system
@@ -176,6 +177,14 @@ export interface ITreeViewConfiguration<TSchema extends ImplicitFieldSchema = Im
     readonly schema: TSchema;
 }
 
+// @public
+export type JsonCompatibleReadOnly = string | number | boolean | null | readonly JsonCompatibleReadOnly[] | JsonCompatibleReadOnlyObject;
+
+// @public
+export type JsonCompatibleReadOnlyObject = {
+    readonly [P in string]?: JsonCompatibleReadOnly;
+};
+
 // @public
 export type LazyItem<Item = unknown> = Item | (() => Item);
 
@@ -222,6 +231,7 @@ export enum NodeKind {
 export interface NodeSchemaMetadata<out TCustomMetadata = unknown> {
     readonly custom?: TCustomMetadata | undefined;
     readonly description?: string | undefined;
+    readonly persistedMetadata?: JsonCompatibleReadOnlyObject | undefined;
 }
 
 // @public @sealed

packages/dds/tree/src/core/index.ts

@@ -138,11 +138,13 @@ export {
 	storedEmptyFieldSchema,
 	type StoredSchemaCollection,
 	schemaFormatV1,
+	schemaFormatV2,
 	LeafNodeStoredSchema,
 	ObjectNodeStoredSchema,
 	MapNodeStoredSchema,
 	decodeFieldSchema,
-	encodeFieldSchema,
+	encodeFieldSchemaV1,
+	encodeFieldSchemaV2,
 	storedSchemaDecodeDispatcher,
 	type SchemaAndPolicy,
 	Multiplicity,

packages/dds/tree/src/core/schema-stored/formatV2.ts

@@ -0,0 +1,54 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { type ObjectOptions, type Static, Type } from "@sinclair/typebox";
+
+import { JsonCompatibleReadOnlySchema } from "../../util/index.js";
+import {
+	FieldKindIdentifierSchema,
+	TreeNodeSchemaIdentifierSchema,
+	TreeNodeSchemaDataFormat as TreeNodeSchemaUnionFormat,
+} from "./formatV1.js";
+
+export const PersistedMetadataFormat = Type.Optional(JsonCompatibleReadOnlySchema);
+
+const FieldSchemaFormatBase = Type.Object({
+	kind: FieldKindIdentifierSchema,
+	types: Type.Array(TreeNodeSchemaIdentifierSchema),
+	metadata: PersistedMetadataFormat,
+});
+
+const noAdditionalProps: ObjectOptions = { additionalProperties: false };
+
+export const FieldSchemaFormat = Type.Composite([FieldSchemaFormatBase], noAdditionalProps);
+
+/**
+ * Format for {@link TreeNodeStoredSchema}.
+ *
+ * See {@link DiscriminatedUnionDispatcher} for more information on this pattern.
+ */
+export const TreeNodeSchemaDataFormat = Type.Object(
+	{
+		/**
+		 * Node kind specific data.
+		 */
+		kind: TreeNodeSchemaUnionFormat,
+
+		// Data in common for all TreeNode schemas:
+		/**
+		 * Leaf node union member.
+		 */
+		metadata: PersistedMetadataFormat,
+	},
+	noAdditionalProps,
+);
+
+export type TreeNodeSchemaDataFormat = Static<typeof TreeNodeSchemaDataFormat>;
+
+export type FieldSchemaFormat = Static<typeof FieldSchemaFormat>;
+
+export type PersistedMetadataFormat = Static<typeof PersistedMetadataFormat>;
+
+export { TreeNodeSchemaUnionFormat };

packages/dds/tree/src/core/schema-stored/index.ts

@@ -18,7 +18,8 @@ export {
 	ObjectNodeStoredSchema,
 	MapNodeStoredSchema,
 	decodeFieldSchema,
-	encodeFieldSchema,
+	encodeFieldSchemaV1,
+	encodeFieldSchemaV2,
 	storedSchemaDecodeDispatcher,
 	type SchemaAndPolicy,
 	type SchemaPolicy,
@@ -37,3 +38,5 @@ export type { TreeNodeSchemaIdentifier, FieldKey, FieldKindIdentifier } from "./
 
 import * as schemaFormatV1 from "./formatV1.js";
 export { schemaFormatV1 };
+import * as schemaFormatV2 from "./formatV2.js";
+export { schemaFormatV2 };