feat: Add docfx JSON Schema files and related tests

schemas/filterconfig.schema.json

@@ -0,0 +1,97 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/dotnet/docfx/main/schemas/filterconfig.schema.json",
+  "title": "JSON Schema for docfx TOC file.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "apiRules": {
+      "type": "array",
+      "description": "Include/exclude rules using uid.",
+      "items": {
+        "$ref": "#/$defs/configFilterRuleItemUnion"
+      }
+    },
+    "attributeRules": {
+      "type": "array",
+      "description": "Include/exclude rules using attribute.",
+      "items": {
+        "$ref": "#/$defs/configFilterRuleItemUnion"
+      }
+    }
+  },
+  "$defs": {
+    "configFilterRuleItemUnion": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "include": {
+          "type": "object",
+          "properties": {
+            "uidRegex": {
+              "type": "string"
+            },
+            "kind": {
+              "$ref": "#/$defs/extendedSymbolKind"
+            },
+            "attribute": {
+              "$ref": "#/$defs/attributeFilterInfo"
+            }
+          }
+        },
+        "exclude": {
+          "type": "object",
+          "properties": {
+            "uidRegex": {
+              "type": "string"
+            },
+            "kind": {
+              "$ref": "#/$defs/extendedSymbolKind"
+            },
+            "attribute": {
+              "$ref": "#/$defs/attributeFilterInfo"
+            }
+          }
+        }
+      }
+    },
+    "extendedSymbolKind": {
+      "enum": [
+        "assembly",
+        "namespace",
+        "class",
+        "struct",
+        "enum",
+        "interface",
+        "delegate",
+        "type",
+        "event",
+        "field",
+        "method",
+        "property",
+        "member"
+      ]
+    },
+    "attributeFilterInfo": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "uid": {
+          "type": "string"
+        },
+        "ctorArguments": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "ctorNamedArguments": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

schemas/toc.schema.json

@@ -0,0 +1,105 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/dotnet/docfx/main/schemas/toc.schema.json",
+  "title": "JSON Schema for docfx TOC file.",
+  "anyOf": [
+    {
+      "$ref": "#/$defs/tocItem"
+    },
+    {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/tocItem"
+      }
+    }
+  ],
+  "$defs": {
+    "tocItem": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "uid": {
+          "type": "string",
+          "description": "The uid of the article. Can be used instead of href."
+        },
+        "name": {
+          "type": "string",
+          "description": ""
+        },
+        "displayName": {
+          "type": "string",
+          "description": "An optional display name for the TOC node. When not specified, uses the title metadata or the first Heading 1 element from the referenced article as the display name."
+        },
+        "href": {
+          "type": "string",
+          "description": "The path the TOC node leads to. Optional because a node can exist just to parent other nodes."
+        },
+        "originalHref": {
+          "type": "string",
+          "description": ""
+        },
+        "tocHref": {
+          "type": "string",
+          "description": ""
+        },
+        "originalTocHref": {
+          "type": "string",
+          "description": ""
+        },
+        "topicHref": {
+          "type": "string",
+          "description": "Specify the topic href of the TOC Item. It is useful when href is linking to a folder or TOC file or tocHref is used."
+        },
+        "originalTopicHref": {
+          "type": "string",
+          "description": ""
+        },
+        "includedFrom": {
+          "type": "string",
+          "description": ""
+        },
+        "homepage": {
+          "type": "string",
+          "description": "(Deprecated)",
+          "deprecated": true
+        },
+        "originalHomepage": {
+          "type": "string",
+          "description": "(Deprecated).",
+          "deprecated": true
+        },
+        "homepageUid": {
+          "type": "string",
+          "description": "(Deprecated).",
+          "deprecated": true
+        },
+        "topicUid": {
+          "type": "string",
+          "description": "Specify the uid of the referenced file. If the value is set, it overwrites the value of topicHref."
+        },
+        "order": {
+          "type": "integer",
+          "default": 0,
+          "description": "Specify the order of toc item, TOCs with a smaller order value are picked first."
+        },
+        "items": {
+          "type": "array",
+          "description": "List of TOC items.",
+          "items": {
+            "$ref": "#/$defs/tocItem"
+          }
+        },
+        "expanded": {
+          "type": "boolean",
+          "default": false,
+          "description": "If set to true, Child items are displayed as expanded."
+        },
+        "dropdown": {
+          "type": "boolean",
+          "default": false,
+          "description": "If set to true, Child items are displayed as dropdown on top navigation bar."
+        }
+      }
+    }
+  }
+}

schemas/xrefmap.schema.json

@@ -0,0 +1,87 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/dotnet/docfx/main/schemas/xrefmap.schema.json",
+  "title": "JSON Schema for docfx xrefmap file.",
+  "type": "object",
+  "additionalProperties": true,
+  "properties": {
+    "sorted": {
+      "type": "boolean",
+      "default": false,
+      "description": "Indicate references are sorted by uid or not."
+    },
+    "hrefUpdated": {
+      "type": "boolean",
+      "default": false,
+      "description": "Indicate href links are updated or not."
+    },
+    "baseUrl": {
+      "type": "string",
+      "format": "uri",
+      "description": "Base url. It's used when href is specified as relative url."
+    },
+    "redirections": {
+      "type": "array",
+      "description": "List of XRefMapRedirection items.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "uidPrefix": {
+            "type": "string",
+            "description": "Prefix of the UID to redirect."
+          },
+          "href": {
+            "type": "string",
+            "format": "uri-reference",
+            "description": "URL to redirect."
+          }
+        }
+      }
+    },
+    "references": {
+      "type": "array",
+      "description": "List of XRefSpec items.",
+      "items": {
+        "$ref": "#/$defs/xrefSpec"
+      }
+    }
+  },
+  "$defs": {
+    "xrefSpec": {
+      "type": "object",
+      "description": "",
+      "additionalProperties": true,
+      "properties": {
+        "uid": {
+          "type": "string",
+          "description": "UID to a conceptual topic or API reference."
+        },
+        "name": {
+          "type": "string",
+          "description": "Title of the topic."
+        },
+        "href": {
+          "type": "string",
+          "description": "URL to the topic, which is an absolute url or relative path to current file (xrefmap.yml)"
+        },
+        "fullName": {
+          "type": "string",
+          "description": "The fully qualified name of API. For example, for String class, its name is String and fully qualified name is System.String. This property is not used in link title resolve for now but reserved for future use."
+        },
+        "nameWithType": {
+          "type": "string",
+          "description": "Display name of type."
+        },
+        "commentId": {
+          "type": "string",
+          "description": "The id of API comment."
+        },
+        "isSpec": {
+          "type": "string",
+          "description": ""
+        }
+      }
+    }
+  }
+}

src/Docfx.Common/FileMappingItem.cs

@@ -19,21 +19,21 @@ public class FileMappingItem
     public string Name { get; set; }
 
     /// <summary>
-    /// The file glob pattern collection, with path relative to property `src`/`cwd` is value is set
+    /// The file glob pattern collection, with path relative to property `src` is value is set
     /// </summary>
     [JsonProperty("files")]
     [JsonPropertyName("files")]
     public FileItems Files { get; set; }
 
     /// <summary>
-    /// The file glob pattern collection for files that should be excluded, with path relative to property `src`/`cwd` is value is set
+    /// The file glob pattern collection for files that should be excluded, with path relative to property `src` is value is set
     /// </summary>
     [JsonProperty("exclude")]
     [JsonPropertyName("exclude")]
     public FileItems Exclude { get; set; }
 
     /// <summary>
-    /// `src` defines the root folder for the source files, it has the same meaning as `cwd`
+    /// `src` defines the root folder for the source files.
     /// </summary>
     [JsonProperty("src")]
     [JsonPropertyName("src")]

src/Docfx.DataContracts.Common/Constants.cs

@@ -114,6 +114,14 @@ public static class TableOfContents
         public const string YamlTocFileName = "toc.yml";
     }
 
+    public static class JsonSchemas
+    {
+        public const string Docfx = "schemas/docfx.schema.json";
+        public const string Toc = "schemas/toc.schema.json";
+        public const string XrefMap = "schemas/xrefmap.schema.json";
+        public const string FilterConfig = "schemas/filterconfig.schema.json";
+    }
+
     public static class EnvironmentVariables
     {
 #pragma warning disable format

test/docfx.Tests/Api.verified.cs

@@ -2383,6 +2383,13 @@ public static class ExtensionMemberPrefix
             public const string Source = "source.";
             public const string Spec = "spec.";
         }
+        public static class JsonSchemas
+        {
+            public const string Docfx = "schemas/docfx.schema.json";
+            public const string FilterConfig = "schemas/filterconfig.schema.json";
+            public const string Toc = "schemas/toc.schema.json";
+            public const string XrefMap = "schemas/xrefmap.schema.json";
+        }
         public static class MetadataName
         {
             public const string Version = "version";