Replace "tsdocVersion" with "$schema"

Author: octogonz

tsdoc-config/src/ConfigLoader.ts

@@ -11,6 +11,10 @@ interface IPackageJson {
   tsdocConfig?: string;
 }
 
+/**
+ * Use this class to load the `tsdoc-config.json` file.
+ * @public
+ */
 export class ConfigLoader {
   public static readonly JSON_FILE_NAME: string = 'tsdoc-config.json';
 
@@ -74,6 +78,6 @@ export class ConfigLoader {
       return undefined;
     }
 
-    return TSDocConfigFile.load(rootConfigFilePath);
+    return TSDocConfigFile.loadFromFile(rootConfigFilePath);
   }
 }

tsdoc-config/src/TSDocConfigFile.ts

@@ -25,24 +25,38 @@ interface ITagConfigJson {
 }
 
 interface IConfigJson {
+  $schema: string;
   tsdocVersion: string;
   extends?: string[];
   tagDefinitions: ITagConfigJson[];
 }
 
+/**
+ * Represents an individual `tsdoc-config.json` file.
+ *
+ * @public
+ */
 export class TSDocConfigFile {
-
+  /**
+   * The full path of the file.
+   */
   public readonly filePath: string;
 
-  public readonly tsdocVersion: string;
+  /**
+   * The `$schema` field from the `tsdoc-config.json` file.
+   */
+  public readonly tsdocSchema: string;
 
+  /**
+   * Module paths for other config files that this file extends from.
+   */
   public readonly extends: ReadonlyArray<string>;
 
   public readonly tagDefinitions: ReadonlyArray<TSDocTagDefinition>;
 
   private constructor(filePath: string, configJson: IConfigJson) {
     this.filePath = filePath;
-    this.tsdocVersion = configJson.tsdocVersion;
+    this.tsdocSchema = configJson.$schema;
     this.extends = configJson.extends || [];
     const tagDefinitions: TSDocTagDefinition[] = [];
 
@@ -66,7 +80,16 @@ export class TSDocConfigFile {
     this.tagDefinitions = tagDefinitions;
   }
 
-  public static load(jsonFilePath: string): TSDocConfigFile {
+  /**
+   * Loads the contents of a single JSON input file.
+   *
+   * @remarks
+   *
+   * This method does not process the `extends` field of `tsdoc-config.json`.
+   * For full functionality, including discovery of the file path, use the {@link ConfigLoader}
+   * API instead.
+   */
+  public static loadFromFile(jsonFilePath: string): TSDocConfigFile {
     const fullJsonFilePath: string = path.resolve(jsonFilePath);
 
     const configJsonContent: string = fs.readFileSync(fullJsonFilePath).toString();

tsdoc-config/src/__tests__/ConfigLoader.test.ts

@@ -71,7 +71,7 @@ test('Load p5', () => {
           "tagNameWithUpperCase": "@MYMODIFIERTAG",
         },
       ],
-      "tsdocVersion": "0.12",
+      "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc-config.schema.json",
     }
   `
   );

tsdoc-config/src/__tests__/assets/p1/folder/tsdoc-config.json

@@ -1,3 +1,3 @@
 {
-  "tsdocVersion": "0.12"
+  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc-config.schema.json"
 }

tsdoc-config/src/__tests__/assets/p2/folder/tsdoc-config.json

@@ -1,3 +1,3 @@
 {
-  "tsdocVersion": "0.12"
+  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc-config.schema.json"
 }

tsdoc-config/src/__tests__/assets/p3/folder/tsdoc-config.json

@@ -1,3 +1,3 @@
 {
-  "tsdocVersion": "0.12"
+  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc-config.schema.json"
 }

tsdoc-config/src/__tests__/assets/p4/tsdoc-config.json

@@ -1,3 +1,3 @@
 {
-  "tsdocVersion": "0.12"
+  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc-config.schema.json"
 }

tsdoc-config/src/__tests__/assets/p5/tsdoc-config.json

@@ -1,6 +1,5 @@
 {
-  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/tsdoc-config.schema.json",
-  "tsdocVersion": "0.12",
+  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc-config.schema.json",
   "extends": [],
   "tagDefinitions": [
     {

tsdoc-config/src/index.ts

@@ -1 +1,2 @@
 export { TSDocConfigFile } from './TSDocConfigFile';
+export { ConfigLoader } from './ConfigLoader';

tsdoc-config/src/schemas/tsdoc-config.schema.json

@@ -8,12 +8,6 @@
       "type": "string"
     },
 
-    "tsdocVersion": {
-      "description": "The target version of the TSDoc spec",
-      "type": "string",
-      "pattern": "^[0-9]+\\.[0-9]+$"
-    },
-
     "extends": {
       "description": "Optionally specifies another JSON config files that this file extends from.  This provides a way for standard settings to be shared across multiple projects.",
       "type": "array",
@@ -30,7 +24,7 @@
       }
     }
   },
-  "required": [ "tsdocVersion" ],
+  "required": [ "$schema" ],
   "additionalProperties": false,
 
   "definitions": {