improvement(tree): getJsonSchema supports field schema input (micro…

…soft#22579)

The API previously only supported `ImplicitAllowedTypes` input, but did
not allow for `ImplicitFieldSchema` input. This meant that it could not
be called via `getJsonSchema(node.schema)`.

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

@@ -99,7 +99,7 @@ export function getBranch(tree: ITree): TreeBranch;
 export function getBranch(view: TreeView<ImplicitFieldSchema>): TreeBranch;
 
 // @alpha
-export function getJsonSchema(schema: ImplicitAllowedTypes): JsonTreeSchema;
+export function getJsonSchema(schema: ImplicitFieldSchema): JsonTreeSchema;
 
 // @public
 export type ImplicitAllowedTypes = AllowedTypes | TreeNodeSchema;

packages/dds/tree/src/simple-tree/api/getJsonSchema.ts

@@ -4,7 +4,7 @@
  */
 
 import type { JsonTreeSchema } from "./jsonSchema.js";
-import type { ImplicitAllowedTypes } from "../schemaTypes.js";
+import type { ImplicitFieldSchema } from "../schemaTypes.js";
 import { toJsonSchema } from "./simpleSchemaToJsonSchema.js";
 import { getSimpleSchema } from "./getSimpleSchema.js";
 import { getOrCreate } from "../../util/index.js";
@@ -53,7 +53,7 @@ const jsonSchemaCache = new WeakMap<TreeNodeSchema, JsonTreeSchema>();
  * 			"required": ["foo"],
  * 		},
  * 	},
- * 	"anyOf": [ { "$ref": "#/$defs/com.myapp.MyObject" } ],
+ * 	"$ref": "#/$defs/com.myapp.MyObject",
  * }
  * ```
  *
@@ -62,7 +62,7 @@ const jsonSchemaCache = new WeakMap<TreeNodeSchema, JsonTreeSchema>();
  *
  * @alpha
  */
-export function getJsonSchema(schema: ImplicitAllowedTypes): JsonTreeSchema {
+export function getJsonSchema(schema: ImplicitFieldSchema): JsonTreeSchema {
 	return getOrCreate(jsonSchemaCache, schema, () => {
 		const simpleSchema = getSimpleSchema(schema);
 		return toJsonSchema(simpleSchema);

packages/dds/tree/src/simple-tree/api/getSimpleSchema.ts

@@ -5,7 +5,7 @@
 
 import { getOrCreate } from "../../util/index.js";
 import type { TreeNodeSchema } from "../core/index.js";
-import type { ImplicitAllowedTypes } from "../schemaTypes.js";
+import type { ImplicitFieldSchema } from "../schemaTypes.js";
 import type { SimpleTreeSchema } from "./simpleSchema.js";
 import { toSimpleTreeSchema } from "./viewSchemaToSimpleSchema.js";
 
@@ -64,6 +64,6 @@ const simpleSchemaCache = new WeakMap<TreeNodeSchema, SimpleTreeSchema>();
  * @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.
  */
-export function getSimpleSchema(schema: ImplicitAllowedTypes): SimpleTreeSchema {
+export function getSimpleSchema(schema: ImplicitFieldSchema): SimpleTreeSchema {
 	return getOrCreate(simpleSchemaCache, schema, () => toSimpleTreeSchema(schema));
 }

packages/dds/tree/src/simple-tree/api/simpleSchema.ts

@@ -99,7 +99,7 @@ export type SimpleNodeSchema =
  */
 export interface SimpleFieldSchema {
 	/**
-	 * The kind of object field.
+	 * The kind of tree field.
 	 */
 	readonly kind: FieldKind;
 
@@ -120,24 +120,29 @@ export interface SimpleFieldSchema {
 /**
  * A simplified representation of a schema for a tree.
  *
- * @remarks Contains the complete set of schema {@link SimpleTreeSchema.definitions} required to resolve references
- * by schema identifier.
+ * @remarks Contains the complete set of schema {@link SimpleTreeSchema.definitions} required to resolve references,
+ * which are represented inline with identifiers.
  *
  * @sealed
  */
-export interface SimpleTreeSchema {
+export interface SimpleTreeSchema extends SimpleFieldSchema {
 	/**
-	 * The complete set of node schema definitions recursively referenced by the tree's {@link SimpleTreeSchema.allowedTypes}.
-	 *
-	 * @remarks the keys are the schemas' {@link TreeNodeSchemaCore.identifier | identifiers}.
+	 * The kind of tree field representing the root of the tree.
 	 */
-	readonly definitions: ReadonlyMap<string, SimpleNodeSchema>;
+	readonly kind: FieldKind;
 
 	/**
-	 * The types allowed under the root of the tree.
+	 * The types allowed under the tree root.
 	 *
 	 * @remarks Refers to the types by identifier.
-	 * {@link SimpleTreeSchema.definitions} can be used to resolve these identifiers to their associated schema definition.
+	 * Can be resolved via {@link SimpleTreeSchema.definitions}.
 	 */
 	readonly allowedTypes: ReadonlySet<string>;
+
+	/**
+	 * The complete set of node schema definitions recursively referenced by the tree's {@link SimpleTreeSchema.allowedTypes}.
+	 *
+	 * @remarks the keys are the schemas' {@link TreeNodeSchemaCore.identifier | identifiers}.
+	 */
+	readonly definitions: ReadonlyMap<string, SimpleNodeSchema>;
 }

packages/dds/tree/src/simple-tree/api/viewSchemaToSimpleSchema.ts

@@ -8,6 +8,7 @@ import {
 	normalizeFieldSchema,
 	type FieldSchema,
 	type ImplicitAllowedTypes,
+	type ImplicitFieldSchema,
 } from "../schemaTypes.js";
 import type {
 	SimpleArrayNodeSchema,
@@ -26,18 +27,26 @@ import { NodeKind, type TreeNodeSchema } from "../core/index.js";
 /**
  * Converts a "view" schema to a "simple" schema representation.
  */
-export function toSimpleTreeSchema(schema: ImplicitAllowedTypes): SimpleTreeSchema {
+export function toSimpleTreeSchema(schema: ImplicitFieldSchema): SimpleTreeSchema {
 	const normalizedSchema = normalizeFieldSchema(schema);
 
 	const allowedTypes = allowedTypesFromFieldSchema(normalizedSchema);
 
 	const definitions = new Map<string, SimpleNodeSchema>();
 	populateSchemaDefinitionsForField(normalizedSchema, definitions);
 
-	return {
+	const output: Mutable<SimpleTreeSchema> = {
+		kind: normalizedSchema.kind,
 		allowedTypes,
 		definitions,
 	};
+
+	// Include the "description" property only if it's present on the input.
+	if (normalizedSchema.metadata?.description !== undefined) {
+		output.description = normalizedSchema.metadata.description;
+	}
+
+	return output;
 }
 
 /**

packages/dds/tree/src/test/simple-tree/api/simpleSchemaToJsonSchema.spec.ts

@@ -18,6 +18,7 @@ import { ValueSchema } from "../../../core/index.js";
 describe("simpleSchemaToJsonSchema", () => {
 	it("Leaf schema", async () => {
 		const input: SimpleTreeSchema = {
+			kind: FieldKind.Required,
 			definitions: new Map<string, SimpleNodeSchema>([
 				["test.string", { leafKind: ValueSchema.String, kind: NodeKind.Leaf }],
 			]),
@@ -50,6 +51,7 @@ describe("simpleSchemaToJsonSchema", () => {
 	// Ensure the code throws if a handle is encountered.
 	it("Leaf node (Fluid Handle)", async () => {
 		const input: SimpleTreeSchema = {
+			kind: FieldKind.Required,
 			definitions: new Map<string, SimpleNodeSchema>([
 				["test.handle", { leafKind: ValueSchema.FluidHandle, kind: NodeKind.Leaf }],
 			]),
@@ -61,6 +63,7 @@ describe("simpleSchemaToJsonSchema", () => {
 
 	it("Array schema", () => {
 		const input: SimpleTreeSchema = {
+			kind: FieldKind.Required,
 			definitions: new Map<string, SimpleNodeSchema>([
 				[
 					"test.array",
@@ -105,6 +108,7 @@ describe("simpleSchemaToJsonSchema", () => {
 
 	it("Map schema", () => {
 		const input: SimpleTreeSchema = {
+			kind: FieldKind.Required,
 			definitions: new Map<string, SimpleNodeSchema>([
 				["test.map", { kind: NodeKind.Map, allowedTypes: new Set<string>(["test.string"]) }],
 				["test.string", { leafKind: ValueSchema.String, kind: NodeKind.Leaf }],
@@ -158,6 +162,7 @@ describe("simpleSchemaToJsonSchema", () => {
 
 	it("Object schema", () => {
 		const input: SimpleTreeSchema = {
+			kind: FieldKind.Required,
 			definitions: new Map<string, SimpleNodeSchema>([
 				[
 					"test.object",
@@ -254,6 +259,7 @@ describe("simpleSchemaToJsonSchema", () => {
 
 	it("Object schema including an identifier field", () => {
 		const input: SimpleTreeSchema = {
+			kind: FieldKind.Required,
 			definitions: new Map<string, SimpleNodeSchema>([
 				[
 					"test.object",
@@ -297,6 +303,7 @@ describe("simpleSchemaToJsonSchema", () => {
 
 	it("Object schema including a union field", () => {
 		const input: SimpleTreeSchema = {
+			kind: FieldKind.Required,
 			definitions: new Map<string, SimpleNodeSchema>([
 				[
 					"test.object",
@@ -347,6 +354,7 @@ describe("simpleSchemaToJsonSchema", () => {
 
 	it("Recursive object schema", () => {
 		const input: SimpleTreeSchema = {
+			kind: FieldKind.Required,
 			definitions: new Map<string, SimpleNodeSchema>([
 				[
 					"test.recursive-object",

packages/dds/tree/src/test/simple-tree/getJsonSchema.spec.ts

@@ -15,6 +15,37 @@ import { hydrate } from "./utils.js";
 import { getJsonValidator } from "./jsonSchemaUtilities.js";
 
 describe("getJsonSchema", () => {
+	it("Field Schema", async () => {
+		const schemaFactory = new SchemaFactory("test");
+		const Schema = schemaFactory.optional(schemaFactory.string, {
+			metadata: { description: "An optional string." },
+		});
+
+		const actual = getJsonSchema(Schema);
+
+		const expected: JsonTreeSchema = {
+			$defs: {
+				"com.fluidframework.leaf.string": {
+					type: "string",
+					_treeNodeSchemaKind: NodeKind.Leaf,
+				},
+			},
+			$ref: "#/$defs/com.fluidframework.leaf.string",
+		};
+		assert.deepEqual(actual, expected);
+
+		// Verify that the generated schema is valid.
+		const validator = getJsonValidator(actual);
+
+		// Verify expected data validation behavior.
+		validator(hydrate(Schema, "Hello world"), true);
+		validator("Hello world", true);
+		validator(42, false);
+		validator({}, false);
+		validator([], false);
+		validator(null, false);
+	});
+
 	it("Leaf node", async () => {
 		const schemaFactory = new SchemaFactory("test");
 		const Schema = schemaFactory.string;

packages/dds/tree/src/test/simple-tree/getSimpleSchema.spec.ts

@@ -14,13 +14,39 @@ import {
 import { ValueSchema } from "../../core/index.js";
 
 describe("getSimpleSchema", () => {
+	it("Field Schema", async () => {
+		const schemaFactory = new SchemaFactory("test");
+		const Schema = schemaFactory.optional(schemaFactory.string, {
+			metadata: { description: "An optional string." },
+		});
+
+		const actual = getSimpleSchema(Schema);
+
+		const expected: SimpleTreeSchema = {
+			kind: FieldKind.Optional,
+			definitions: new Map([
+				[
+					"com.fluidframework.leaf.string",
+					{
+						leafKind: ValueSchema.String,
+						kind: NodeKind.Leaf,
+					},
+				],
+			]),
+			allowedTypes: new Set(["com.fluidframework.leaf.string"]),
+			description: "An optional string.",
+		};
+		assert.deepEqual(actual, expected);
+	});
+
 	it("Leaf node", async () => {
 		const schemaFactory = new SchemaFactory("test");
 		const Schema = schemaFactory.string;
 
 		const actual = getSimpleSchema(Schema);
 
 		const expected: SimpleTreeSchema = {
+			kind: FieldKind.Required,
 			definitions: new Map([
 				[
 					"com.fluidframework.leaf.string",
@@ -42,6 +68,7 @@ describe("getSimpleSchema", () => {
 		const actual = getSimpleSchema(Schema);
 
 		const expected: SimpleTreeSchema = {
+			kind: FieldKind.Required,
 			definitions: new Map([
 				[
 					"com.fluidframework.leaf.number",
@@ -73,6 +100,7 @@ describe("getSimpleSchema", () => {
 		const actual = getSimpleSchema(Schema);
 
 		const expected: SimpleTreeSchema = {
+			kind: FieldKind.Required,
 			definitions: new Map([
 				[
 					"test.array",
@@ -100,6 +128,7 @@ describe("getSimpleSchema", () => {
 
 		const actual = getSimpleSchema(Schema);
 		const expected: SimpleTreeSchema = {
+			kind: FieldKind.Required,
 			definitions: new Map([
 				[
 					"test.map",
@@ -131,6 +160,7 @@ describe("getSimpleSchema", () => {
 		const actual = getSimpleSchema(Schema);
 
 		const expected: SimpleTreeSchema = {
+			kind: FieldKind.Required,
 			definitions: new Map([
 				[
 					"test.object",
@@ -177,6 +207,7 @@ describe("getSimpleSchema", () => {
 		const actual = getSimpleSchema(Schema);
 
 		const expected: SimpleTreeSchema = {
+			kind: FieldKind.Required,
 			definitions: new Map([
 				[
 					"test.object",
@@ -212,6 +243,7 @@ describe("getSimpleSchema", () => {
 		const actual = getSimpleSchema(Schema);
 
 		const expected: SimpleTreeSchema = {
+			kind: FieldKind.Required,
 			definitions: new Map([
 				[
 					"test.object",
@@ -257,6 +289,7 @@ describe("getSimpleSchema", () => {
 		const actual = getSimpleSchema(Schema);
 
 		const expected: SimpleTreeSchema = {
+			kind: FieldKind.Required,
 			definitions: new Map([
 				[
 					"test.recursive-object",

packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md

@@ -148,7 +148,7 @@ export function getBranch(tree: ITree): TreeBranch;
 export function getBranch(view: TreeView<ImplicitFieldSchema>): TreeBranch;
 
 // @alpha
-export function getJsonSchema(schema: ImplicitAllowedTypes): JsonTreeSchema;
+export function getJsonSchema(schema: ImplicitFieldSchema): JsonTreeSchema;
 
 // @public
 export interface IConnection {