feat: URN-like Domain Reference Standards (#46)

Introduction of URN-Like references using the "ref" keyword for inner domain references: "sps:book:et89e-di087-lkjer2", along with linting rules.

rulesets/src/.spectral.yml

@@ -3,6 +3,7 @@ extends:
   - specification.ruleset.yml
   - authentication.ruleset.yml
   - errors.ruleset.yml
+  - naming.ruleset.yml
   - request-response.ruleset.yml
   - serialization.ruleset.yml
   - url-structure.ruleset.yml 

rulesets/src/naming.ruleset.yml

@@ -1,5 +1,67 @@
 rules:   
 
+  # domain references (URN-like values)
+  sps-ref-property-name:
+    description: Property with the name 'ref' MUST be of type 'sps-ref' following URN-like reference formats.
+    severity: error
+    formats: [oas3]
+    given: '$..[?((@property=== "ref" || @property === "Ref") && @.$ref == null && @.allOf == null && @.oneOf == null)]'
+    then:
+      - field: "format"
+        function: truthy
+      - field: "format"
+        function: pattern
+        functionOptions:
+          match: 'sps-ref'
+
+  sps-ref-schema:
+    description: Properties following 'sps-ref' format MUST use the standardized schema - maxLength (255), minLength(7), pattern (includes 'sps'), type (string).
+    message: '{{property}} is not provided or not following required schema values.'
+    severity: error
+    formats: [oas3]
+    given: '$..[?(@property=== "format" && @ == "sps-ref")]^'
+    then:
+      - function: schema
+        functionOptions:  
+          schema:
+            type: object
+            required:
+              - maxLength
+              - minLength
+              - type
+              - pattern
+            properties:
+              maxLength:
+                type: integer
+                minimum: 255
+                maximum: 255
+              minLength:
+                type: integer
+                minimum: 7
+                maximum: 7
+              type:
+                type: string
+              pattern:
+                type: string
+      - field: pattern
+        function: pattern
+        functionOptions:
+          match: 'sps'
+      - field: type
+        function: pattern
+        functionOptions:
+          match: '^string$'
+
+  sps-ref-in-url:
+    description: Parameters for sps-ref formatted URN-like references SHOULD NOT be used in query or path parameters.
+    severity: warn
+    formats: [oas3]
+    given: '$..[?((@.name == "ref" || @.name == "Ref") && (@.in=="query" || @.in=="path"))]'
+    then:
+      field: name
+      function: falsy
+
+  # fingerprint property usage and naming
   sps-fingerprint-naming:
     description: Rather than property names refering to the implementation for 'hash' or 'hashkey', you MUST use the property name 'fingerprint'.
     message: '{{property}} is not using property name fingerprint.'
@@ -20,7 +82,3 @@ rules:
       function: pattern
       functionOptions:
         match: '^string$'
-
-
-
-

rulesets/test/naming/sps-ref-in-url.test.js

@@ -0,0 +1,60 @@
+const { SpectralTestHarness } = require("../harness/spectral-test-harness.js");
+
+describe("sps-ref-in-url", () => {
+    let spectral = null;
+    const ruleName = "sps-ref-in-url";
+    const ruleset = "src/naming.ruleset.yml";
+
+    beforeEach(async () => {
+        spectral = new SpectralTestHarness(ruleset);
+    });
+
+    test("no errors for regular query parameters", async () => {
+        const spec = `
+        openapi: 3.1.0
+        paths:
+            /v1/users/{id}:
+                get:
+                    summary: hello
+                    parameters:
+                    - name: filterThing
+                      in: query
+                    - name: id
+                      in: path
+        `;
+
+        await spectral.validateSuccess(spec, ruleName);
+    });
+
+    test("warnings for ref in query parameter", async () => {
+        const spec = `
+        openapi: 3.1.0
+        paths:
+            /v1/users/{id}:
+                get:
+                    summary: hello
+                    parameters:
+                    - name: ref
+                      in: query
+                    - name: id
+                      in: path
+        `;
+        await spectral.validateFailure(spec, ruleName, "Warning");
+    });
+
+    test("warnings for ref in path parameter", async () => {
+        const spec = `
+        openapi: 3.1.0
+        paths:
+            /v1/users/{ref}:
+                get:
+                    summary: hello
+                    parameters:
+                    - name: other
+                      in: query
+                    - name: ref
+                      in: path
+        `;
+        await spectral.validateFailure(spec, ruleName, "Warning");
+    });
+});

rulesets/test/naming/sps-ref-property-name.test.js

@@ -0,0 +1,65 @@
+const { SpectralTestHarness } = require("../harness/spectral-test-harness.js");
+
+describe("sps-ref-property-name", () => {
+    let spectral = null;
+    const ruleName = "sps-ref-property-name";
+    const ruleset = "src/naming.ruleset.yml";
+
+    beforeEach(async () => {
+        spectral = new SpectralTestHarness(ruleset);
+    });
+
+    test("Ref property successful with proper format", async () => {
+        const spec = `
+        openapi: 3.0.1
+        paths: {}
+        components:
+            schemas:
+                MySchema:
+                    type: object
+                    properties:
+                        ref:
+                            type: string
+                            format: sps-ref
+                        value:
+                            type: string
+        `;
+
+        await spectral.validateSuccess(spec, ruleName);
+    });
+
+    test("Ref property fails without proper format", async () => {
+        const spec = `
+        openapi: 3.0.1
+        paths: {}
+        components:
+            schemas:
+                MySchema:
+                    type: object
+                    properties:
+                        ref:
+                            type: string
+                        value:
+                            type: string
+        `;
+        await spectral.validateFailure(spec, ruleName, "Error");
+    });
+
+    test("Ref property fails with wrong format", async () => {
+        const spec = `
+        openapi: 3.0.1
+        paths: {}
+        components:
+            schemas:
+                MySchema:
+                    type: object
+                    properties:
+                        ref:
+                            type: string
+                            format: uuid
+                        value:
+                            type: string
+        `;
+        await spectral.validateFailure(spec, ruleName, "Error");
+    });
+});