Ignore unknown keyword values that aren't valid against their schema

Unknown keywords aren't checked against a meta-schema, so the values of
VS Code's keywords, and of deprecated in dialects before 2019-09, could
be any JSON value and were used as-is. Accessors now check them against
the keyword's meta-schema and ignore invalid values. Only the accessors
are affected, not the annotations themselves.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: jdesrosiers

language-server/src/evaluation/Annotation.ts

@@ -1,7 +1,43 @@
+import { interpret } from "@hyperjump/json-schema/experimental";
+import * as Instance from "@hyperjump/json-schema/instance/experimental";
 import { JsonSchemaAnnotation } from "./JsonSchemaAnnotation.ts";
 import { VscodeAnnotation } from "./VscodeAnnotation.ts";
 
+import type { Json } from "@hyperjump/json-pointer";
+import type { AST } from "@hyperjump/json-schema/experimental";
+
+// The annotations one schema contributed to an instance location, keyed by
+// keyword URI
+export type AnnotationRecord = Record<string, unknown>;
+
+// Vocabularies add accessors for the annotations of their keywords by
+// extending BaseAnnotation with a mixin. The mixins are composed into the
+// Annotation class below.
+export type Constructor<T> = new (...args: any[]) => T;
+
+export class BaseAnnotation {
+  protected keywords: AnnotationRecord;
+
+  constructor(keywords: AnnotationRecord) {
+    this.keywords = keywords;
+  }
+
+  // Keywords a dialect doesn't define produce annotations as unknown keywords,
+  // which aren't checked against a meta-schema, so their values could be
+  // anything. An accessor that reads an unknown keyword as a keyword it knows
+  // uses this to ignore values that aren't valid against that keyword's schema.
+  // Undefined if the keyword isn't present or its value isn't valid.
+  protected unknownKeyword(keyword: string, schemaUri: string, ast: AST) {
+    const value = this.keywords[`https://json-schema.org/keyword/unknown#${keyword}`] as Json | undefined;
+    if (value !== undefined && !interpret({ schemaUri, ast }, Instance.fromJs(value)).valid) {
+      return;
+    }
+
+    return value;
+  }
+}
+
 // The annotations one schema contributed to an instance location, with the
 // accessors of every vocabulary. A vocabulary's mixin overrides the accessors of
 // the ones it's applied to, so their order matters.
-export class Annotation extends VscodeAnnotation(JsonSchemaAnnotation) {}
+export class Annotation extends VscodeAnnotation(JsonSchemaAnnotation(BaseAnnotation)) {}

language-server/src/evaluation/JsonSchemaAnnotation.ts

@@ -1,13 +1,8 @@
 import * as Pact from "@hyperjump/pact";
+import "@hyperjump/json-schema/draft-2020-12";
+import { compile, getSchema } from "@hyperjump/json-schema/experimental";
 
-// The annotations one schema contributed to an instance location, keyed by
-// keyword URI
-export type AnnotationRecord = Record<string, unknown>;
-
-// Vocabularies add accessors for the annotations of their keywords by
-// extending JsonSchemaAnnotation with a mixin. The mixins are composed into the
-// Annotation class in Annotation.ts.
-export type Constructor<T> = new (...args: any[]) => T;
+import type { BaseAnnotation, Constructor } from "./Annotation.ts";
 
 const FORMAT_KEYWORDS = [
   "https://json-schema.org/keyword/draft-2020-12/format",
@@ -19,15 +14,13 @@ const FORMAT_KEYWORDS = [
   "https://json-schema.org/keyword/draft-04/format"
 ];
 
+const metaSchemaUri = "https://json-schema.org/draft/2020-12/meta/meta-data";
+const schema = await getSchema(metaSchemaUri);
+const { ast } = await compile(schema);
+
 // Accessors for the standard JSON Schema annotations. Some keywords have more
 // than one URI depending on the dialect.
-export class JsonSchemaAnnotation {
-  protected keywords: AnnotationRecord;
-
-  constructor(keywords: AnnotationRecord) {
-    this.keywords = keywords;
-  }
-
+export const JsonSchemaAnnotation = <T extends Constructor<BaseAnnotation>>(Base: T) => class extends Base {
   title(): string | undefined {
     return this.keywords["https://json-schema.org/keyword/title"] as string | undefined;
   }
@@ -36,11 +29,11 @@ export class JsonSchemaAnnotation {
     return this.keywords["https://json-schema.org/keyword/description"] as string | undefined;
   }
 
-  // Dialects before 2019-09 don't have the deprecated keyword, but it's
-  // commonly used with them anyway
+  // The deprecated keyword was added in 2019-09, but it's commonly used with
+  // earlier dialects anyway
   deprecated(): boolean {
     return (this.keywords["https://json-schema.org/keyword/deprecated"]
-      ?? this.keywords["https://json-schema.org/keyword/unknown#deprecated"]) === true;
+      ?? this.unknownKeyword("deprecated", `${metaSchemaUri}#/properties/deprecated`, ast)) === true;
   }
 
   formats(): unknown[] {
@@ -51,4 +44,4 @@ export class JsonSchemaAnnotation {
       Pact.collectArray
     );
   }
-}
+};

language-server/src/evaluation/JsonValueSet.test.ts

@@ -1,7 +1,7 @@
 import { describe, test, expect } from "vitest";
 import { JsonValueSet } from "./JsonValueSet.ts";
 
-import type { AnnotationRecord } from "./JsonSchemaAnnotation.ts";
+import type { AnnotationRecord } from "./Annotation.ts";
 
 const a: AnnotationRecord = { a: true };
 const b: AnnotationRecord = { b: true };

language-server/src/evaluation/JsonValueSet.ts

@@ -1,4 +1,4 @@
-import type { AnnotationRecord } from "./JsonSchemaAnnotation.ts";
+import type { AnnotationRecord } from "./Annotation.ts";
 
 export type JsonSchemaType = "string" | "number" | "integer" | "boolean" | "null" | "array" | "object";
 

language-server/src/evaluation/LspEvaluationPlugin.ts

@@ -9,7 +9,7 @@ import { Annotation } from "./Annotation.ts";
 import type { EvaluationPlugin, Keyword, Node, ValidationContext } from "@hyperjump/json-schema/experimental";
 import type { JsonNode } from "@hyperjump/json-schema/instance/experimental";
 import type { JsonSchemaType, TypeEntry, ValueEntry } from "./JsonValueSet.ts";
-import type { AnnotationRecord } from "./JsonSchemaAnnotation.ts";
+import type { AnnotationRecord } from "./Annotation.ts";
 import type { SchemaEvaluation } from "../services/JsonSchema.ts";
 
 // A location annotation applies no matter what the value at the location is.

language-server/src/evaluation/VscodeAnnotation.ts

@@ -1,4 +1,7 @@
-import type { Constructor, JsonSchemaAnnotation } from "./JsonSchemaAnnotation.ts";
+import "../vocabularies/vscode.ts";
+import { compile, getSchema } from "@hyperjump/json-schema/experimental";
+
+import type { BaseAnnotation, Constructor } from "./Annotation.ts";
 
 // Accessors for the annotations of VS Code's custom keywords. The keywords are
 // defined in vocabularies/vscode.ts.
@@ -11,13 +14,23 @@ export type DefaultSnippet = {
   bodyText?: string;
 };
 
+const metaSchemaUri = "https://microsoft.com/meta/vscode";
+const schema = await getSchema(metaSchemaUri);
+const { ast } = await compile(schema);
+
+// The accessors this mixin extends
+type Extended = BaseAnnotation & {
+  description(): string | undefined;
+  deprecated(): boolean;
+};
+
 // Schemas that don't use the vocabulary still produce annotations for its
 // keywords as unknown keywords.
-export const VscodeAnnotation = <T extends Constructor<JsonSchemaAnnotation>>(Base: T) => class extends Base {
+export const VscodeAnnotation = <T extends Constructor<Extended>>(Base: T) => class extends Base {
   // Prefers markdownDescription over the standard description keyword
   override description(): string | undefined {
     return (this.keywords["https://microsoft.com/keyword/markdownDescription"]
-      ?? this.keywords["https://json-schema.org/keyword/unknown#markdownDescription"]
+      ?? this.unknownKeyword("markdownDescription", `${metaSchemaUri}#/properties/markdownDescription`, ast)
       ?? super.description()) as string | undefined;
   }
 
@@ -31,20 +44,20 @@ export const VscodeAnnotation = <T extends Constructor<JsonSchemaAnnotation>>(Ba
   // An empty message is the same as no message
   deprecationMessage(): string | undefined {
     const message = this.keywords["https://microsoft.com/keyword/deprecationMessage"]
-      ?? this.keywords["https://json-schema.org/keyword/unknown#deprecationMessage"];
+      ?? this.unknownKeyword("deprecationMessage", `${metaSchemaUri}#/properties/deprecationMessage`, ast);
     return (message || undefined) as string | undefined;
   }
 
   // An empty message is the same as no message
   markdownDeprecationMessage(): string | undefined {
     const message = this.keywords["https://microsoft.com/keyword/markdownDeprecationMessage"]
-      ?? this.keywords["https://json-schema.org/keyword/unknown#markdownDeprecationMessage"];
+      ?? this.unknownKeyword("markdownDeprecationMessage", `${metaSchemaUri}#/properties/markdownDeprecationMessage`, ast);
     return (message || undefined) as string | undefined;
   }
 
   defaultSnippets(): DefaultSnippet[] {
     return (this.keywords["https://microsoft.com/keyword/defaultSnippets"]
-      ?? this.keywords["https://json-schema.org/keyword/unknown#defaultSnippets"]
+      ?? this.unknownKeyword("defaultSnippets", `${metaSchemaUri}#/properties/defaultSnippets`, ast)
       ?? []) as DefaultSnippet[];
   }
 };

language-server/src/features/Hover.test.ts

@@ -569,6 +569,42 @@ The **full name** of the [person](https://example.com).
 
 ---
 
+_hyperjump-json-language-server_`
+      }
+    });
+  });
+
+  test("should use description when markdownDescription isn't a string", async () => {
+    fixtureSchemaUri = await client.writeDocument("schema.json", `{
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "type": "object",
+      "properties": {
+        "name": {
+          "description": "Plain text description",
+          "markdownDescription": { "en": "The **markdown** description" },
+          "type": "string"
+        }
+      }
+    }`);
+
+    await client.writeDocument("instance.json", `{
+      "$schema": "${fixtureSchemaUri}",
+      "name": "Alice"
+    }`);
+    const uri = await client.openDocument("instance.json");
+
+    const result = await client.sendRequest(HoverRequest.type, {
+      textDocument: { uri },
+      position: { line: 2, character: 10 }
+    });
+
+    expect(result).toEqual({
+      contents: {
+        kind: "markdown",
+        value: `Plain text description
+
+---
+
 _hyperjump-json-language-server_`
       }
     });

language-server/src/features/completions/DefaultSnippetsCompletionsProvider.test.ts

@@ -2,6 +2,8 @@ import { describe, test, expect, beforeEach, afterEach } from "vitest";
 import { CompletionItemKind, CompletionRequest, InsertTextFormat } from "vscode-languageserver";
 import { TestClient } from "../../test/TestClient.ts";
 
+import type { CompletionItem } from "vscode-languageserver";
+
 describe("Value Completions", () => {
   let client: TestClient;
 
@@ -286,6 +288,36 @@ describe("Value Completions", () => {
     expect(completions).toContainEqual(expect.objectContaining({ label: "FromSecond" }));
   });
 
+  test("invalid defaultSnippets are ignored without affecting valid ones", async () => {
+    const fixtureSchemaUri = await client.writeDocument("schema.json", `{
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "type": "object",
+      "properties": {
+        "value": {
+          "allOf": [
+            { "defaultSnippets": 5 },
+            { "defaultSnippets": [null, { "label": "Invalid", "bodyText": "\\"invalid\\"" }] },
+            { "defaultSnippets": [{ "label": "Valid", "bodyText": "\\"valid\\"" }] }
+          ]
+        }
+      }
+    }`);
+
+    await client.writeDocument("instance.json", `{
+      "$schema": "${fixtureSchemaUri}",
+      "value":
+    }`);
+    const uri = await client.openDocument("instance.json");
+
+    const completions = await client.sendRequest(CompletionRequest.type, {
+      textDocument: { uri },
+      position: { line: 2, character: 14 }
+    });
+
+    const snippets = (completions as CompletionItem[]).filter((completion) => completion.kind === CompletionItemKind.Snippet);
+    expect(snippets).toEqual([expect.objectContaining({ label: "Valid" })]);
+  });
+
   test("defaultSnippets are offered for an incomplete location whose schema references itself", async () => {
     const fixtureSchemaUri = await client.writeDocument("schema.json", `{
       "$schema": "https://json-schema.org/draft/2020-12/schema",

language-server/src/features/diagnostics/DeprecatedDiagnosticsProvider.test.ts

@@ -376,6 +376,50 @@ describe("Deprecated Diagnostics", () => {
     ]);
   });
 
+  test("a deprecationMessage that isn't a string is ignored", async () => {
+    fixtureSchemaUri = await client.writeDocument("schema.json", `{
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "deprecationMessage": { "en": "Use fullName instead." }
+        }
+      }
+    }`);
+
+    await client.writeDocument("instance.json", `{
+      "$schema": "${fixtureSchemaUri}",
+      "name": "Alice"
+    }`);
+    const diagnostics = client.getDiagnostics("instance.json");
+    await client.openDocument("instance.json");
+
+    await expect(diagnostics).resolves.toHaveLength(0);
+  });
+
+  test("a deprecated keyword that isn't a boolean is ignored in dialects that don't have it", async () => {
+    fixtureSchemaUri = await client.writeDocument("schema.json", `{
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "deprecated": "Use fullName instead."
+        }
+      }
+    }`);
+
+    await client.writeDocument("instance.json", `{
+      "$schema": "${fixtureSchemaUri}",
+      "name": "Alice"
+    }`);
+    const diagnostics = client.getDiagnostics("instance.json");
+    await client.openDocument("instance.json");
+
+    await expect(diagnostics).resolves.toHaveLength(0);
+  });
+
   test("no diagnostics when nothing is deprecated", async () => {
     fixtureSchemaUri = await client.writeDocument("schema.json", `{
       "$schema": "https://json-schema.org/draft/2020-12/schema",