Merge branch 'v3.2-dev' into fix/missing-ref-schema-media-and-parameter

Signed-off-by: Vincent Biret <[email protected]>

Author: baywet

package-lock.json

@@ -20,17 +20,17 @@
     "validate-markdown": "npx markdownlint-cli2 --config spec.markdownlint.yaml src/oas.md && npx markdownlint-cli2 *.md"
   },
   "dependencies": {
-    "cheerio": "^1.0.0-rc.5",
+    "cheerio": "^1.1.0",
     "highlight.js": "^11.11.1",
     "markdown-it": "^14.1.0",
     "respec": "35.4.0",
     "yargs": "^18.0.0"
   },
   "devDependencies": {
-    "@hyperjump/json-schema": "^1.14.1",
+    "@hyperjump/json-schema": "^1.15.1",
     "c8": "^10.1.3",
     "markdownlint-cli2": "^0.18.1",
-    "vitest": "^3.2.1",
+    "vitest": "^3.2.3",
     "yaml": "^2.8.0"
   },
   "keywords": [

package.json

@@ -2,20 +2,13 @@ import { readdir, readFile } from "node:fs/promises";
 import YAML from "yaml";
 import { join } from "node:path";
 import { argv } from "node:process";
-import "@hyperjump/json-schema/draft-2020-12";
+import { validate } from "@hyperjump/json-schema/draft-2020-12";
 import "@hyperjump/json-schema/draft-04";
-import {
-  compile,
-  getSchema,
-  interpret,
-  Validation,
-  BASIC,
-} from "@hyperjump/json-schema/experimental";
-import * as Instance from "@hyperjump/json-schema/instance/experimental";
+import { BASIC } from "@hyperjump/json-schema/experimental";
 
 /**
- * @import { AST } from "@hyperjump/json-schema/experimental"
- * @import { Json } from "@hyperjump/json-schema"
+ * @import { EvaluationPlugin } from "@hyperjump/json-schema/experimental"
+ * @import { Json } from "@hyperjump/json-pointer"
  */
 
 import contentTypeParser from "content-type";
@@ -36,6 +29,41 @@ addMediaTypePlugin("application/schema+yaml", {
   fileMatcher: (path) => path.endsWith(".yaml"),
 });
 
+/** @implements EvaluationPlugin */
+class TestCoveragePlugin {
+  constructor() {
+    /** @type Set<string> */
+    this.visitedLocations = new Set();
+  }
+
+  beforeSchema(_schemaUri, _instance, context) {
+    if (this.allLocations) {
+      return;
+    }
+
+    /** @type Set<string> */
+    this.allLocations = [];
+
+    for (const schemaLocation in context.ast) {
+      if (schemaLocation === "metaData") {
+        continue;
+      }
+
+      if (Array.isArray(context.ast[schemaLocation])) {
+        for (const keyword of context.ast[schemaLocation]) {
+          if (Array.isArray(keyword)) {
+            this.allLocations.push(keyword[1]);
+          }
+        }
+      }
+    }
+  }
+
+  beforeKeyword([, schemaUri]) {
+    this.visitedLocations.add(schemaUri);
+  }
+}
+
 /** @type (testDirectory: string) => AsyncGenerator<[string,Json]> */
 const tests = async function* (testDirectory) {
   for (const file of await readdir(testDirectory, {
@@ -53,70 +81,43 @@ const tests = async function* (testDirectory) {
   }
 };
 
-/** @type (testDirectory: string) => Promise<void> */
-const runTests = async (testDirectory) => {
-  for await (const [name, test] of tests(testDirectory)) {
-    const instance = Instance.fromJs(test);
+/**
+ * @typedef {{
+ *   allLocations: string[];
+ *   visitedLocations: Set<string>;
+ * }} Coverage
+ */
 
-    const result = interpret(compiled, instance, BASIC);
+/** @type (schemaUri: string, testDirectory: string) => Promise<Coverage> */
+const runTests = async (schemaUri, testDirectory) => {
+  const testCoveragePlugin = new TestCoveragePlugin();
+  const validateOpenApi = await validate(schemaUri);
+
+  for await (const [name, test] of tests(testDirectory)) {
+    const result = validateOpenApi(test, {
+      outputFormat: BASIC,
+      plugins: [testCoveragePlugin],
+    });
 
     if (!result.valid) {
       console.log("Failed:", name, result.errors);
     }
   }
-};
-
-/** @type (ast: AST) => string[] */
-const keywordLocations = (ast) => {
-  /** @type string[] */
-  const locations = [];
-  for (const schemaLocation in ast) {
-    if (schemaLocation === "metaData") {
-      continue;
-    }
-
-    if (Array.isArray(ast[schemaLocation])) {
-      for (const keyword of ast[schemaLocation]) {
-        if (Array.isArray(keyword)) {
-          locations.push(keyword[1]);
-        }
-      }
-    }
-  }
 
-  return locations;
+  return {
+    allLocations: testCoveragePlugin.allLocations ?? new Set(),
+    visitedLocations: testCoveragePlugin.visitedLocations
+  };
 };
 
 ///////////////////////////////////////////////////////////////////////////////
 
-const schema = await getSchema(argv[2]);
-const compiled = await compile(schema);
-
-/** @type Set<string> */
-const visitedLocations = new Set();
-const baseInterpret = Validation.interpret;
-Validation.interpret = (url, instance, context) => {
-  if (Array.isArray(context.ast[url])) {
-    for (const keywordNode of context.ast[url]) {
-      if (Array.isArray(keywordNode)) {
-        visitedLocations.add(keywordNode[1]);
-      }
-    }
-  }
-  return baseInterpret(url, instance, context);
-};
-
-await runTests(argv[3]);
-Validation.interpret = baseInterpret;
-
-// console.log("Covered:", visitedLocations);
-
-const allKeywords = keywordLocations(compiled.ast);
-const notCovered = allKeywords.filter(
+const { allLocations, visitedLocations } = await runTests(argv[2], argv[3]);
+const notCovered = allLocations.filter(
   (location) => !visitedLocations.has(location),
 );
 if (notCovered.length > 0) {
-  console.log("NOT Covered:", notCovered.length, "of", allKeywords.length);
+  console.log("NOT Covered:", notCovered.length, "of", allLocations.length);
   const maxNotCovered = 20;
   const firstNotCovered = notCovered.slice(0, maxNotCovered);
   if (notCovered.length > maxNotCovered) firstNotCovered.push("...");
@@ -127,6 +128,10 @@ console.log(
   "Covered:",
   visitedLocations.size,
   "of",
-  allKeywords.length,
-  "(" + Math.floor((visitedLocations.size / allKeywords.length) * 100) + "%)",
+  allLocations.length,
+  "(" + Math.floor((visitedLocations.size / allLocations.length) * 100) + "%)",
 );
+
+if (visitedLocations.size != allLocations.length) {
+  process.exitCode = 1;
+}

scripts/schema-test-coverage.mjs

@@ -6,8 +6,13 @@
 
 [[ ! -e src/schemas ]] && exit 0
 
+branch=$(git branch --show-current)
+
 echo
 echo "Schema Test Coverage"
 echo
 
 node scripts/schema-test-coverage.mjs src/schemas/validation/schema.yaml tests/schema/pass
+rc=$?
+
+[[ "$branch" == "dev" ]] || exit $rc

scripts/schema-test-coverage.sh

@@ -108,7 +108,7 @@ The fourth repeats `application/geo+json`-structured values, while the last repe
 
 Implementations MUST support mapping sequential media types into the JSON Schema data model by treating them as if the values were in an array in the same order.
 
-See [Complete vs Streaming Content](#complete-vs-streaming-content) for more information on handling sequential media type in a streaming context, including special considerations for `text/event-stream` content.
+See [Complete vs Streaming Content](#complete-vs-streaming-content) for more information on handling sequential media types in a streaming context, including special considerations for `text/event-stream` content.
 
 #### Media Type Registry
 
@@ -2424,7 +2424,9 @@ This object MAY be extended with [Specification Extensions](#specification-exten
 For simpler scenarios, a [`schema`](#header-schema) and [`style`](#header-style) can describe the structure and syntax of the header.
 When `example` or `examples` are provided in conjunction with the `schema` field, the example MUST follow the prescribed serialization strategy for the header.
 
-Serializing with `schema` is NOT RECOMMENDED for headers with parameters (name=value pairs following a `;`) in their values, or where values might have non-URL-safe characters; see [Appendix D](#appendix-d-serializing-headers-and-cookies) for details.
+Serializing headers with `schema` can be problematic due to the URI percent-encoding that is automatically applied, which would percent-encode characters such as `;` that are used to separate primary header values from their parameters.
+The `allowReserved` field can disable most but not all of this behavior.
+See [Appendix D](#appendix-d-serializing-headers-and-cookies) for details and further guidance.
 
 When `example` or `examples` are provided in conjunction with the `schema` field, the example SHOULD match the specified schema and follow the prescribed serialization strategy for the header.
 The `example` and `examples` fields are mutually exclusive, and if either is present it SHALL _override_ any `example` in the schema.
@@ -2433,6 +2435,7 @@ The `example` and `examples` fields are mutually exclusive, and if either is pre
 | ---- | :----: | ---- |
 | <a name="header-style"></a>style | `string` | Describes how the header value will be serialized. The default (and only legal value for headers) is `"simple"`. |
 | <a name="header-explode"></a>explode | `boolean` | When this is true, header values of type `array` or `object` generate a single header whose value is a comma-separated list of the array items or key-value pairs of the map, see [Style Examples](#style-examples). For other data types this field has no effect. The default value is `false`. |
+| <a name="header-allow-reserved"></a>allowReserved | `boolean` | When this is true, header values are serialized using reserved expansion, as defined by [RFC6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3), which allows [RFC3986's reserved character set](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2), as well as percent-encoded triples, to pass through unchanged, while still percent-encoding all other disallowed characters (including `%` outside of percent-encoded triples). See [Appendix D: Serializing Headers and Cookies](#appendix-d-serializing-headers-and-cookies) for guidance on header encoding and escaping. The default value is `false`. |
 | <a name="header-schema"></a>schema | [Schema Object](#schema-object) | The schema defining the type used for the header. |
 | <a name="header-example"></a>example | Any | Example of the header's potential value; see [Working With Examples](#working-with-examples). |
 | <a name="header-examples"></a>examples | Map[ `string`, [Example Object](#example-object) \| [Reference Object](#reference-object)] | Examples of the header's potential value; see [Working With Examples](#working-with-examples). |

src/oas.md

@@ -728,6 +728,9 @@ $defs:
           explode:
             default: false
             type: boolean
+          allowReserved:
+            default: false
+            type: boolean
         $ref: '#/$defs/examples'
     $ref: '#/$defs/specification-extensions'
     unevaluatedProperties: false

src/schemas/validation/schema.yaml

@@ -1,5 +1,6 @@
 # including External Documentation Object Example
 openapi: 3.2.0
+$self: https://example.com/openapi
 info:
   title: Example Pet Store App
   summary: A pet store manager.

tests/schema/pass/info-object-example.yaml

@@ -51,4 +51,18 @@ paths:
                 lat:
                   type: number
                 long:
-                  type: number
+                  type: number
+  /user:
+    parameters:
+      - in: querystring
+        name: json
+        content:
+          application/json:
+            schema:
+              # Allow an arbitrary JSON object to keep
+              # the example simple
+              type: object
+            example: {
+              "numbers": [1, 2],
+              "flag": null
+            }

tests/schema/pass/parameter-object-examples.yaml

@@ -5,6 +5,7 @@ info:
 components:
   responses:
     complex-object-array:
+      summary: Complex object array
       description: A complex object array response
       content:
         application/json: