feat(rulesets): improve OAS 3.1 external references validation

- Update OAS 3.1 schema to better support external references
- Add external references test scenario in test-harness
- Update Arazzo schema validators to use improved OAS 3.1 schema
- Enhance OAS 3 schema test coverage

Fixes issues with external reference validation in OpenAPI 3.1 documents.

Author: fluz

packages/rulesets/src/arazzo/schemas/validators.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/__tests__/oas3-schema.test.ts

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

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

@@ -0,0 +1,40 @@
+====test====
+OAS 3.1 - External Ref Validation 
+====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
+====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}
+====stdout====
+No results with a severity of 'error' found!