Add version validation and uplift for unevaluatedProperties in seal-schema (#1)

Add version validation and uplift for unevaluatedProperties
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: bartoszm <1446124+bartoszm@users.noreply.github.com>

Author: Copilot

README.md

@@ -140,12 +140,20 @@ oas-utils seal-schema <input.yaml> -o output.yaml
 oas-utils seal-schema <input.yaml> -o output.yaml --use-unevaluated-properties
 # Use additionalProperties: false instead
 oas-utils seal-schema <input.yaml> -o output.yaml --use-additional-properties
+# Automatically upgrade OpenAPI 3.0.x to 3.1.0 or JSON Schema to draft 2020-12
+oas-utils seal-schema <input.yaml> -o output.yaml --uplift
 ```
 
 Options:
 - -o, --output: write result to this file (defaults to stdout).
 - --use-unevaluated-properties: use `unevaluatedProperties: false` (default, better for JSON Schema 2019-09+).
 - --use-additional-properties: use `additionalProperties: false` instead.
+- --uplift: automatically upgrade OpenAPI version to 3.1.0 or JSON Schema to draft 2020-12 to support `unevaluatedProperties`.
+
+**Note**: `unevaluatedProperties` is only supported in OpenAPI 3.1+ or JSON Schema 2019-09+. If your document uses an earlier version and you want to use `unevaluatedProperties`, either:
+- Use the `--uplift` option to automatically upgrade the version
+- Manually upgrade your document to a compatible version
+- Use `--use-additional-properties` instead
 
 Example transformation:
 - Original `Animal` schema (object-like, referenced in `allOf` by `Cat`)
@@ -193,6 +201,7 @@ decorators:
   # Seal object schemas
   oas-utils/seal-schema:
     useUnevaluatedProperties: true
+    uplift: false  # Set to true to automatically upgrade OpenAPI/JSON Schema version
 ```
 
 3) Run bundling with Redocly CLI and the decorators will apply the transformations. With `aggressive: true`, unused non-schema components (responses, headers, requestBodies, etc.) are removed as well.
@@ -216,7 +225,7 @@ const result = cleanupDiscriminatorMappings(doc);
 console.log(`Removed ${result.mappingsRemoved} invalid mappings from ${result.schemasChecked} schemas`);
 
 // Seal object schemas
-sealSchema(doc, { useUnevaluatedProperties: true });
+sealSchema(doc, { useUnevaluatedProperties: true, uplift: true });
 ```
 
 ## Notes

package-lock.json

@@ -153,15 +153,20 @@ program
     "Use additionalProperties: false instead of unevaluatedProperties: false",
     false
   )
+  .option(
+    "--uplift",
+    "Automatically upgrade OpenAPI/JSON Schema version to support unevaluatedProperties",
+    false
+  )
   .action(
     async (
       input: string | undefined,
-      opts: { output?: string; useUnevaluatedProperties?: boolean; useAdditionalProperties?: boolean }
+      opts: { output?: string; useUnevaluatedProperties?: boolean; useAdditionalProperties?: boolean; uplift?: boolean }
     ) => {
       try {
         const useUnevaluated = !opts.useAdditionalProperties;
         await runSealSchema(
-          { output: opts.output, useUnevaluatedProperties: useUnevaluated },
+          { output: opts.output, useUnevaluatedProperties: useUnevaluated, uplift: opts.uplift },
           format,
           () => reader(input)
         );

src/cli.ts

@@ -211,14 +211,15 @@ export async function runAllOfToOneOf(
  * @param reader - Function to read input
  */
 export async function runSealSchema(
-  opts: { output?: string; useUnevaluatedProperties?: boolean },
+  opts: { output?: string; useUnevaluatedProperties?: boolean; uplift?: boolean },
   format: (doc: any, target?: string) => string,
   reader: () => Promise<string>
 ) {
   const doc = parseYamlOrJson(await reader());
 
   const sopts: SealSchemaOptions = {
     useUnevaluatedProperties: opts.useUnevaluatedProperties !== false,
+    uplift: opts.uplift,
   };
 
   const result = sealSchema(doc, sopts);

src/lib/cliActions.ts

@@ -110,3 +110,142 @@ export function getAncestors(childName: string, schemas: Record<string, any>): S
 
   return ancestors;
 }
+
+/**
+ * Extracts the OpenAPI version from a document.
+ * 
+ * @param doc - The OpenAPI document
+ * @returns The OpenAPI version string (e.g., "3.0.0", "3.1.0") or undefined
+ */
+export function getOpenApiVersion(doc: any): string | undefined {
+  if (!doc || typeof doc !== "object") return undefined;
+  if (typeof doc.openapi === "string") return doc.openapi;
+  return undefined;
+}
+
+/**
+ * Extracts the JSON Schema version from a document or schema.
+ * 
+ * @param doc - The JSON Schema document
+ * @returns The JSON Schema version URI or undefined
+ */
+export function getJsonSchemaVersion(doc: any): string | undefined {
+  if (!doc || typeof doc !== "object") return undefined;
+  if (typeof doc.$schema === "string") return doc.$schema;
+  return undefined;
+}
+
+/**
+ * Checks if a JSON Schema version supports unevaluatedProperties.
+ * unevaluatedProperties is supported in draft 2019-09 and later.
+ * 
+ * @param schemaVersion - The $schema URI (e.g., "http://json-schema.org/draft-07/schema#")
+ * @returns true if unevaluatedProperties is supported
+ */
+export function supportsUnevaluatedProperties(schemaVersion: string): boolean {
+  if (!schemaVersion) return false;
+  
+  // Check for 2019-09, 2020-12, or later drafts
+  if (schemaVersion.includes("2019-09") || 
+      schemaVersion.includes("2020-12") ||
+      schemaVersion.includes("/next/")) {
+    return true;
+  }
+  
+  // Draft-07 and earlier don't support unevaluatedProperties
+  // We explicitly return false for these versions
+  return false;
+}
+
+/**
+ * Checks if an OpenAPI version supports unevaluatedProperties.
+ * unevaluatedProperties is supported in OpenAPI 3.1 and later.
+ * 
+ * @param oasVersion - The OpenAPI version (e.g., "3.0.0", "3.1.0")
+ * @returns true if unevaluatedProperties is supported
+ */
+export function oasSupportsUnevaluatedProperties(oasVersion: string): boolean {
+  if (!oasVersion) return false;
+  
+  // Parse version
+  const versionMatch = oasVersion.match(/^(\d+)\.(\d+)/);
+  if (!versionMatch) return false;
+  
+  const major = parseInt(versionMatch[1], 10);
+  const minor = parseInt(versionMatch[2], 10);
+  
+  // OpenAPI 3.1+ supports unevaluatedProperties (uses JSON Schema 2020-12)
+  if (major === 3 && minor >= 1) return true;
+  if (major > 3) return true;
+  
+  return false;
+}
+
+/**
+ * Checks if a document (OpenAPI or JSON Schema) supports unevaluatedProperties.
+ * 
+ * @param doc - The document to check
+ * @returns true if unevaluatedProperties is supported
+ */
+export function documentSupportsUnevaluatedProperties(doc: any): boolean {
+  if (!doc || typeof doc !== "object") return false;
+  
+  // Check for OpenAPI version
+  const oasVersion = getOpenApiVersion(doc);
+  if (oasVersion) {
+    return oasSupportsUnevaluatedProperties(oasVersion);
+  }
+  
+  // Check for JSON Schema version
+  const schemaVersion = getJsonSchemaVersion(doc);
+  if (schemaVersion) {
+    return supportsUnevaluatedProperties(schemaVersion);
+  }
+  
+  // If no version specified, assume it doesn't support unevaluatedProperties
+  return false;
+}
+
+/**
+ * Upgrades the OpenAPI version to 3.1.0 to support unevaluatedProperties.
+ * 
+ * @param doc - The OpenAPI document to upgrade
+ * @returns The upgraded document
+ */
+export function upgradeToOas31(doc: any): any {
+  if (!doc || typeof doc !== "object") return doc;
+  
+  // Only upgrade if it's OpenAPI 3.0.x
+  const currentVersion = getOpenApiVersion(doc);
+  if (!currentVersion || !currentVersion.match(/^3\.0\./)) {
+    return doc;
+  }
+  
+  // Upgrade to 3.1.0
+  doc.openapi = "3.1.0";
+  
+  return doc;
+}
+
+/**
+ * Upgrades the JSON Schema version to draft 2019-09 to support unevaluatedProperties.
+ * Only upgrades if the current version is earlier than 2019-09.
+ * 
+ * @param doc - The JSON Schema document to upgrade
+ * @returns The upgraded document
+ */
+export function upgradeJsonSchemaToDraft201909(doc: any): any {
+  if (!doc || typeof doc !== "object") return doc;
+  
+  const currentVersion = getJsonSchemaVersion(doc);
+  
+  // If already supports unevaluatedProperties (2019-09 or later), keep as is
+  if (currentVersion && supportsUnevaluatedProperties(currentVersion)) {
+    return doc;
+  }
+  
+  // Set $schema to draft 2019-09
+  doc.$schema = "https://json-schema.org/draft/2019-09/schema";
+  
+  return doc;
+}

src/lib/oasUtils.ts

@@ -1,8 +1,17 @@
-import { refToName } from "./oasUtils.js";
+import { 
+  refToName, 
+  documentSupportsUnevaluatedProperties,
+  getOpenApiVersion,
+  getJsonSchemaVersion,
+  upgradeToOas31,
+  upgradeJsonSchemaToDraft201909
+} from "./oasUtils.js";
 
 export interface SealSchemaOptions {
   /** If true, use unevaluatedProperties: false instead of additionalProperties: false (default: true) */
   useUnevaluatedProperties?: boolean;
+  /** If true, automatically upgrade OpenAPI/JSON Schema version to support unevaluatedProperties (default: false) */
+  uplift?: boolean;
 }
 
 /**
@@ -29,6 +38,53 @@ export function sealSchema(doc: any, opts: SealSchemaOptions = {}): any {
 
   // Check if this is a standalone JSON Schema (not an OpenAPI document)
   const isStandalone = isStandaloneJsonSchema(doc);
+
+  // Check if using unevaluatedProperties and validate version compatibility
+  if (useUnevaluated) {
+    const oasVersion = getOpenApiVersion(doc);
+    const schemaVersion = getJsonSchemaVersion(doc);
+    
+    // Only validate if there's an explicit version specified
+    const hasExplicitVersion = oasVersion || schemaVersion;
+    
+    if (hasExplicitVersion) {
+      const isCompatible = documentSupportsUnevaluatedProperties(doc);
+      
+      if (!isCompatible) {
+        if (opts.uplift) {
+          // Automatically upgrade the version
+          if (oasVersion) {
+            upgradeToOas31(doc);
+            console.warn(
+              `[SEAL-SCHEMA] Upgraded OpenAPI version from ${oasVersion} to 3.1.0 to support unevaluatedProperties.`
+            );
+          } else if (schemaVersion) {
+            upgradeJsonSchemaToDraft201909(doc);
+            console.warn(
+              `[SEAL-SCHEMA] Upgraded JSON Schema to draft 2019-09 to support unevaluatedProperties.`
+            );
+          }
+        } else {
+          // Error if uplift is not enabled
+          const versionInfo = oasVersion 
+            ? `OpenAPI ${oasVersion}` 
+            : `JSON Schema ${schemaVersion}`;
+          
+          throw new Error(
+            `unevaluatedProperties is only supported in OpenAPI 3.1+ or JSON Schema 2019-09+. ` +
+            `Current document uses ${versionInfo}. ` +
+            `Use --uplift option to automatically upgrade the version, or use --use-additional-properties instead.`
+          );
+        }
+      }
+    } else if (opts.uplift && isStandalone) {
+      // If no version and it's a standalone schema, set it when uplift is enabled
+      upgradeJsonSchemaToDraft201909(doc);
+      console.warn(
+        `[SEAL-SCHEMA] Set JSON Schema version to draft 2019-09 to support unevaluatedProperties.`
+      );
+    }
+  }
 
   let schemas: Record<string, any> | undefined;
   let wrappedName: string = "";

src/lib/sealSchema.ts

@@ -6,6 +6,7 @@ export default function SealSchemaDecorator(opts: any) {
       leave(target: any) {
         sealSchema(target, {
           useUnevaluatedProperties: opts?.useUnevaluatedProperties !== false,
+          uplift: opts?.uplift === true,
         });
       },
     },