Fix AJV warning, "$ref: keywords ignored in schema" (#392)

Author: joshkel

test/programs/comments-override/schema.json

@@ -32,7 +32,6 @@
         },
         "sub2": {
             "$ref": "#/definitions/MySubObject",
-            "additionalProperties": false,
             "description": "Property-level description"
         }
     },

test/programs/namespace-deep-1/schema.json

@@ -55,7 +55,6 @@
             ],
             "type": "object"
         }
-    },
-    "type": "object"
+    }
 }
 

test/programs/namespace-deep-2/schema.json

@@ -55,7 +55,6 @@
             ],
             "type": "object"
         }
-    },
-    "type": "object"
+    }
 }
 

test/schema.test.ts

@@ -5,16 +5,33 @@ import { resolve } from "path";
 import { versionMajorMinor as typescriptVersionMajorMinor } from "typescript";
 import * as TJS from "../typescript-json-schema";
 
-const ajv = new Ajv();
+let ajvWarnings: string[] = [];
+const ajv = new Ajv({
+    logger: {
+        log: console.log,
+        warn: (message) => {
+            ajvWarnings.push(message);
+        },
+        error: (message) => {
+            throw new Error("AJV error: " + message);
+        },
+    },
+});
 
 const BASE = "test/programs/";
 
+interface AjvTestOptions {
+    skipCompile: boolean;
+    expectedWarnings: string[];
+}
+
 export function assertSchema(
     group: string,
     type: string,
     settings: TJS.PartialArgs = {},
     compilerOptions?: TJS.CompilerOptions,
-    only?: boolean
+    only?: boolean,
+    ajvOptions: Partial<AjvTestOptions> = {}
 ) {
     const run = only ? it.only : it;
 
@@ -37,7 +54,15 @@ export function assertSchema(
         // test against the meta schema
         if (actual !== null) {
             ajv.validateSchema(actual);
+
             assert.equal(ajv.errors, null, "The schema is not valid");
+
+            // Compiling the schema can reveal warnings that validateSchema doesn't.
+            if (!ajvOptions.skipCompile) {
+                ajvWarnings = [];
+                ajv.compile(actual);
+                assert.deepEqual(ajvWarnings, ajvOptions.expectedWarnings || [], "Got unexpected AJV warnings");
+            }
         }
     });
 }
@@ -233,11 +258,20 @@ describe("schema", () => {
 
     describe("annotations", () => {
         assertSchema("annotation-default", "MyObject");
-        assertSchema("annotation-ref", "MyObject");
+        assertSchema("annotation-ref", "MyObject", {}, undefined, undefined, {
+            skipCompile: true
+        });
         assertSchema("annotation-tjs", "MyObject", {
             validationKeywords: ["hide"],
         });
-        assertSchema("annotation-id", "MyObject");
+        assertSchema("annotation-id", "MyObject", {}, undefined, undefined, {
+            expectedWarnings: [
+                "schema id ignored",
+                "schema id ignored",
+                "schema id ignored",
+                "schema id ignored"
+            ]
+        });
         assertSchema("annotation-items", "MyObject");
 
         assertSchema("typeof-keyword", "MyObject", { typeOfKeyword: true });

typescript-json-schema.ts

@@ -360,6 +360,20 @@ const validationKeywords = {
     id: true
 };
 
+/**
+ * Subset of descriptive, non-type keywords that are permitted alongside a $ref.
+ * Prior to JSON Schema draft 2019-09, $ref is a special keyword that doesn't
+ * permit keywords alongside it, and so AJV may raise warnings if it encounters
+ * any type-related keywords; see https://github.com/ajv-validator/ajv/issues/1121
+ */
+const annotationKeywords: { [k in keyof typeof validationKeywords]?: true } = {
+    description: true,
+    default: true,
+    examples: true,
+    // A JSDoc $ref annotation can appear as a $ref.
+    $ref: true
+};
+
 const subDefinitions = {
     items: true,
     additionalProperties: true,
@@ -1262,10 +1276,8 @@ export class JsonSchemaGenerator {
             this.recursiveTypeRef.delete(fullTypeName);
             // If the type was recursive (there is reffedDefinitions) - lets replace it to reference
             if (this.reffedDefinitions[fullTypeName]) {
-                // Here we may want to filter out all type specific fields
-                // and include fields like description etc
                 const annotations = Object.entries(returnedDefinition).reduce((acc, [key, value]) => {
-                    if (validationKeywords[key] && typeof value !== undefined) {
+                    if (annotationKeywords[key] && typeof value !== undefined) {
                         acc[key] = value;
                     }
                     return acc;