fix(rulesets): allow external references in OAS 3.1 paths

Fix schema validation error where path items with  were incorrectly
flagged as having unevaluated properties. Changed paths pattern properties
to use path-item-or-reference instead of path-item to properly support
external references in OpenAPI 3.1 specifications.

Fixes issue where documents like:
paths:
  /greetings:
    $ref: 'greetings.yaml'

Would generate: "~1greetings" property must not have unevaluated properties.

- Update OAS 3.1 schema to use path-item-or-reference for paths
- Add test case for external references validation
- Add test harness scenario for CLI integration testing

Author: fluz

packages/rulesets/src/oas/__tests__/oas3-schema.test.ts

@@ -580,4 +580,33 @@ testRule('oas3-schema', [
     },
     errors: [],
   },
+  {
+    name: 'oas3.1: document with external references',
+    document: {
+      openapi: '3.1.0',
+      info: {
+        title: 'Example API',
+        version: '1.0.0',
+        description: 'Example API description',
+      },
+      paths: {
+        '/greetings': {
+          $ref: 'greetings.yaml',
+        },
+      },
+      tags: [
+        {
+          name: 'User',
+          description: 'Info about users',
+        },
+      ],
+      servers: [
+        {
+          url: 'https://example-url.com',
+          description: 'Example server',
+        },
+      ],
+    },
+    errors: [], // No errors expected
+  },
 ]);

packages/rulesets/src/oas/schemas/oas/v3.1/index.json

@@ -276,7 +276,7 @@
       "type": "object",
       "patternProperties": {
         "^/": {
-          "$ref": "#/$defs/path-item"
+          "$ref": "#/$defs/path-item-or-reference"
         }
       },
       "$ref": "#/$defs/specification-extensions",

test-harness/scenarios/oas3.1/external-references.scenario

@@ -0,0 +1,40 @@
+====test====
+OAS 3.1 - External References Validation
+====document====
+openapi: 3.1.0
+info:
+  title: Example API
+  version: 1.0.0
+  description: Example API description
+paths:
+  /greetings:
+    $ref: "{asset:greetings.yaml}"
+tags:
+  - name: User
+    description: Info about users
+servers:
+  - url: https://example-url.com
+    description: Example server
+====asset:greetings.yaml====
+get:
+  description: Get a greeting
+  operationId: getGreeting
+  responses:
+    "200":
+      description: OK
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              message:
+                type: string
+                example: Hello there!
+====asset:ruleset.yaml====
+extends: [[spectral:oas, off]]
+rules:
+  oas3-schema: error
+====command====
+{bin} lint {document} --ruleset {asset:ruleset.yaml} --resolve
+====expected-stdout====
+No results with a severity of 'error' found!