API-30 FetchingData.FetchingResources (#55)

* Initial Setup

* Feat: Adding New Spectral Ruleset
This commit introduces a new set of Spectral rules specifically tailored for validating JSON:API v1.0 Fetching Data - Fetching Resources within an OpenAPI Document. Key highlights include:

- Creation of Spectral rules to ensure compliance with JSON:API v1.0 standards, focusing on Fetching Resources specifications.
- Validating that a server MUST supprt fetching resource data for every URL that is provided to a strict format.

These additions significantly improve our capability to automatically validate and ensure the consistency of API responses with the JSON:API v1.0 standard.

* Enhance: refactored valid OpenAPI Template
This document serves as a standardized template for verifying positive test scenarios in ruleset development. To ensure that the document can be tested against multiple rulesets, the design and endpoints were refactored. This document is now closer to adhering to JSON:API v1.0 specifications. Covered sections include:
- ContentNegotiation.ClientResponsibilities
- ContentNegotiation.ServerResponsibilities
- DocumentStructure
- DocumentStructure.TopLevel
- DocumentStructure.ResourceObjects
- DocumentStructure.ResourceObjects.Attributes
- DocumentStructure.Links
- DocumentStructure.MetaInformation
- DocumentStructure.MemberNames
- FetchingData.FetchingResources
- FetchingData.Sorting
- FetchingData.Pagination
- FetchingData.Filtering
- Errors.ProcessingErrors
- Errors.ErrorObjects

* Feat: Test Case Completion
This commit marks the completion of detailed test cases for all of the JSON:API v1.0 Fetching Data - Fetching Resources ruleset.

These updates significantly improve the robustness and relaibility of the JSON:API v1.0 specifications for Fetching Resources validation process.

* Feat: Passing/Failing OpenAPI Documents for Spectral CLI Testing
- These two files provides a way to test all the created rules for both positive and negative scenarios.
- Created a failing-rules.yaml which generates a way to trigger all the rules to display the error message
- Updated the passing-rules.yaml to adhere to the specifications of JSON:API v1.0 for Fetching Resources.

cliTest/passing-rules.yaml

@@ -1,12 +1,14 @@
 # This OpenAPI Document provides a way of testing rulesets using Spectrals CLI Command. Covered rulesets include:
 #   - `jsonapi-errors-error-object.js`
 #   - `jsonapi-document-structure-resource-objects.js`
+#   - `jsonapi-fetching-data-fetching-resources.js`
 #   - `jsonapi-document-structure-resource-attributes.js`
 #   - `jsonapi-document-structure-resource-identification.js`
 #
 # Usage (From Repo Root Location):
 #   - spectral lint cliTest/passing-rules.yaml --ruleset rules/jsonapi-errors-error-object.js --verbose
 #   - spectral lint cliTest/passing-rules.yaml --ruleset rules/jsonapi-document-structure-resource-objects.js --verbose
+#   - spectral lint cliTest/passing-rules.yaml --ruleset rules/jsonapi-fetching-data-fetching-resources.js --verbose
 #   - spectral lint cliTest/passing-rules.yaml --ruleset rules/jsonapi-document-structure-resource-attributes.js --verbose
 #   - spectral lint cliTest/passing-rules.yaml --ruleset rules/jsonapi-document-structure-resource-identification.js --verbose
 #
@@ -29,6 +31,7 @@ info:
       - DocumentStructure.Links
       - DocumentStructure.MetaInformation
       - DocumentStructure.MemberNames
+      - FetchingData.FetchingResources
       - FetchingData.Sorting
       - FetchingData.Pagination
       - FetchingData.Filtering
@@ -97,6 +100,12 @@ paths:
                             role:
                               type: string
                               description: Role of the user in the system
+                        links:
+                          type: object
+                          properties:
+                            self:
+                              type: string
+                              format: uri
                         relationships:
                           type: object
                           properties:
@@ -112,6 +121,9 @@ paths:
                   links:
                     type: object
                     properties:
+                      self:
+                        type: string
+                        format: uri
                       first:
                         type: string
                         format: uri
@@ -390,6 +402,12 @@ paths:
                           role:
                             type: string
                             description: Role of the user in the system
+                      links:
+                        type: object
+                        properties:
+                          self:
+                            type: string
+                            format: uri
                       relationships:
                         type: object
                         properties:
@@ -629,6 +647,12 @@ paths:
                           role:
                             type: string
                             description: Role of the user in the system
+                      links:
+                        type: object
+                        properties:
+                          self:
+                            type: string
+                            format: uri
                       relationships:
                         type: object
                         properties:
@@ -907,6 +931,12 @@ paths:
                           role:
                             type: string
                             description: Role of the user in the system
+                      links:
+                        type: object
+                        properties:
+                          self:
+                            type: string
+                            format: uri
                       relationships:
                         type: object
                         properties:

rules/jsonapi-fetching-data-fetching-resources.js

@@ -0,0 +1,82 @@
+// Fetching Data - Fetching Resources - https://jsonapi.org/format/1.0/#fetching-resources
+
+// All rules in the file MUST have corresponding tests
+
+import { truthy } from '@stoplight/spectral-functions';
+
+export default {
+  documentationUrl: 'https://jsonapi.org/format/1.0/#fetching-resources',
+  rules: {
+
+    /**
+     * Ensure top-level resposnes include a `self` link in a `links` object
+     */
+    'fetching-data-fetching-resources-top-level-links': {
+      description: 'Ensure top-level resposnes include a `self` link in a `links` object',
+      message: `{{path}} - {{description}}`,
+      severity: 'error',
+      given: "$.paths.*.*.responses.*.content['application/vnd.api+json'].schema.properties.links.properties",
+      then: {
+        field: 'self',
+        function: truthy
+      }
+    },
+
+    /**
+     * Checks for the presence of a `self` link in each resource object within a single responses
+     */
+    'fetching-data-fetching-resources-single-level-self-link': {
+      description: 'Ensure single resource object responses include a `self` link in a `links` object',
+      message: `{{path}} - {{description}}`,
+      severity: 'error',
+      given: "$.paths.*.*.responses.*.content['application/vnd.api+json'].schema.properties.data.properties.links.properties",
+      then: {
+        field: 'self',
+        function: truthy
+      }
+    },
+
+    /**
+     * Ensures that relationship objects within each resource in responses has a `related` link
+     */
+    'fetching-data-fetching-resources-single-relationship-level-related-link': {
+      description: 'Ensure relationship objects in responses include a `related` link',
+      message: `{{path}} - {{description}}`,
+      severity: 'error',
+      given: "$.paths.*.*.responses.*.content['application/vnd.api+json'].schema.properties.data.properties.relationships.properties.*.properties",
+      then: {
+        field: 'related',
+        function: truthy
+      }
+    },
+
+    /**
+     * Checks for the presence of a `self` link in each resource object within array responses
+     */
+    'fetching-data-fetching-resources-array-level-self-link': {
+      description: 'Ensure single resource object responses include a `self` link in a `links` object',
+      message: `{{path}} - {{description}}`,
+      severity: 'error',
+      given: "$.paths.*.*.responses.*.content['application/vnd.api+json'].schema.properties.data.items.properties.links.properties",
+      then: {
+        field: 'self',
+        function: truthy
+      }
+    },
+
+    /**
+     * Ensures that relationship objects within each resource in array responses has a `related` link
+     */
+    'fetching-data-fetching-resources-array-relationship-level-related-link': {
+      description: 'Ensure relationship objects in each resource in array resposnes include a `related` link',
+      message: `{{path}} - {{description}}`,
+      severity: 'error',
+      given: "$.paths.*.*.responses.*.content['application/vnd.api+json'].schema.properties.data.items.properties.relationships.properties.*.properties",
+      then: {
+        field: 'related',
+        function: truthy
+      }
+    }
+
+  }
+};

rules/jsonapi-fetching-data-ruleset.yaml

@@ -0,0 +1,8 @@
+# Fetching Data
+# https://jsonapi.org/format/1.0/#fetching
+
+# *-ruleset.yaml files generally SHOULD NOT contain any testable rules.
+# all rules in this file MUST have corresponding tests.
+
+extends:
+  - jsonapi-fetching-data-fetching-resources.js

rules/jsonapi-ruleset.yaml

@@ -6,3 +6,4 @@ extends:
   - jsonapi-content-negotiation-ruleset.yaml
   - jsonapi-document-structure-ruleset.yaml
   - jsonapi-errors-ruleset.yaml
+  - jsonapi-fetching-data-ruleset.yaml