From 5c59c942fcbff1013d8f5c1c7f137fd479731980 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarcza=20L=C3=ADdia?= <100163235+diatrcz@users.noreply.github.com> Date: Fri, 3 Jul 2026 14:09:21 +0200 Subject: [PATCH 01/20] build: add workflow for github pages --- .github/workflows/jekyll-gh-pages.yml | 51 +++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 .github/workflows/jekyll-gh-pages.yml diff --git a/.github/workflows/jekyll-gh-pages.yml b/.github/workflows/jekyll-gh-pages.yml new file mode 100644 index 00000000..67be9b00 --- /dev/null +++ b/.github/workflows/jekyll-gh-pages.yml @@ -0,0 +1,51 @@ +# Sample workflow for building and deploying a Jekyll site to GitHub Pages +name: Deploy Jekyll with GitHub Pages dependencies preinstalled + +on: + # Runs on pushes targeting the default branch + push: + branches: ["main"] + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + # Build job + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Setup Pages + uses: actions/configure-pages@v5 + - name: Build with Jekyll + uses: actions/jekyll-build-pages@v1 + with: + source: ./ + destination: ./_site + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + + # Deployment job + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v5 From e55154562fd9724afd9dad5e38bc926e2e9a97f3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?L=C3=ADdia=20Tarcza?= <100163235+diatrcz@users.noreply.github.com> Date: Fri, 3 Jul 2026 14:18:51 +0200 Subject: [PATCH 02/20] build: add github pages config MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Lídia Tarcza <100163235+diatrcz@users.noreply.github.com> --- docs/_config.yml | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 docs/_config.yml diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 00000000..57720b06 --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,3 @@ +title: IBM OpenAPI Validator +description: A highly configurable linter/validator for OpenAPI documents. +theme: minima From b6cb85f56ed28b864ed3fa19e835dc42014981fc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?L=C3=ADdia=20Tarcza?= <100163235+diatrcz@users.noreply.github.com> Date: Wed, 15 Jul 2026 16:27:48 +0200 Subject: [PATCH 03/20] fix: correct GitHub Pages rendering issues MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Lídia Tarcza <100163235+diatrcz@users.noreply.github.com> --- docs/_config.yml => _config.yml | 0 docs/ibm-cloud-rules.md | 94 ++++++++++++++++++++++++++++++++- 2 files changed, 92 insertions(+), 2 deletions(-) rename docs/_config.yml => _config.yml (100%) diff --git a/docs/_config.yml b/_config.yml similarity index 100% rename from docs/_config.yml rename to _config.yml diff --git a/docs/ibm-cloud-rules.md b/docs/ibm-cloud-rules.md index 049baf85..4c2c0c61 100644 --- a/docs/ibm-cloud-rules.md +++ b/docs/ibm-cloud-rules.md @@ -779,8 +779,7 @@ npm install @ibm-cloud/openapi-ruleset If you would simply like to modify a rule's severity or disable a rule altogether, follow the instructions in this section. -> [!CAUTION] -> Disabling certain rules may lead to false negatives for problems identified by other rules. +> **Caution:** Disabling certain rules may lead to false negatives for problems identified by other rules. > > For example, if you disable the `ibm-schema-type-format` rule, other rules which detect problems > in schemas with specific combinations of `type` and `format` may fail to identify which schemas @@ -900,6 +899,7 @@ This section provides reference documentation about the IBM Cloud Validation Rul in the `@ibm-cloud/openapi-ruleset` package. ### ibm-accept-and-return-models + @@ -959,6 +959,7 @@ requestBody:
Rule id:
### ibm-anchored-patterns + @@ -1013,6 +1014,7 @@ components:
Rule id:
### ibm-api-symmetry + @@ -1120,6 +1122,7 @@ paths: ### ibm-array-attributes +
Rule id:
@@ -1173,6 +1176,7 @@ components: ### ibm-avoid-inline-schemas +
Rule id:
@@ -1299,6 +1303,7 @@ paths: ### ibm-avoid-multiple-types +
Rule id:
@@ -1366,6 +1371,7 @@ components: ### ibm-avoid-property-name-collision +
Rule id:
@@ -1422,6 +1428,7 @@ components: ### ibm-avoid-repeating-path-parameters +
Rule id:
@@ -1491,6 +1498,7 @@ paths: ### ibm-binary-schemas +
Rule id:
@@ -1557,6 +1565,7 @@ paths: ### ibm-collection-array-property +
Rule id:
@@ -1638,6 +1647,7 @@ paths: ### ibm-content-contains-schema +
Rule id:
@@ -1687,6 +1697,7 @@ responses: ### ibm-content-type-is-specific +
Rule id:
@@ -1735,6 +1746,7 @@ requestBody: ### ibm-define-required-properties +
Rule id:
@@ -1800,6 +1812,7 @@ components: ### ibm-discriminator-property +
Rule id:
@@ -1870,6 +1883,7 @@ components: ### ibm-dont-require-merge-patch-properties +
Rule id:
@@ -1950,6 +1964,7 @@ components: ### ibm-enum-casing-convention +
Rule id:
@@ -2025,6 +2040,7 @@ components: ### ibm-error-content-type-is-json +
Rule id:
@@ -2073,6 +2089,7 @@ responses: ### ibm-error-response-schemas +
Rule id:
@@ -2224,6 +2241,7 @@ components: ### ibm-etag-header +
Rule id:
@@ -2333,6 +2351,7 @@ paths: ### ibm-integer-attributes +
Rule id:
@@ -2391,6 +2410,7 @@ components: ### ibm-major-version-in-path +
Rule id:
@@ -2443,6 +2463,7 @@ paths: ### ibm-no-accept-header +
Rule id:
@@ -2508,6 +2529,7 @@ paths: ### ibm-no-ambiguous-paths +
Rule id:
@@ -2575,6 +2597,7 @@ paths: ### ibm-no-array-of-arrays +
Rule id:
@@ -2626,6 +2649,7 @@ requestBody: ### ibm-no-array-responses +
Rule id:
@@ -2696,6 +2720,7 @@ sample response body: ### ibm-no-authorization-header +
Rule id:
@@ -2780,6 +2805,7 @@ paths: ### ibm-no-body-for-delete +
Rule id:
@@ -2841,6 +2867,7 @@ paths: ### ibm-no-circular-refs +
Rule id:
@@ -2909,6 +2936,7 @@ components: ### ibm-no-consecutive-path-parameter-segments +
Rule id:
@@ -2963,6 +2991,7 @@ paths: ### ibm-no-content-type-header +
Rule id:
@@ -3038,6 +3067,7 @@ paths: ### ibm-no-crn-path-parameters +
Rule id:
@@ -3128,6 +3158,7 @@ components: ### ibm-no-default-for-required-parameter +
Rule id:
@@ -3188,6 +3219,7 @@ components: ### ibm-no-duplicate-description-with-ref-sibling +
Rule id:
@@ -3338,6 +3370,7 @@ components: ### ibm-no-if-modified-since-header +
Rule id:
@@ -3422,6 +3455,7 @@ paths: ### ibm-no-if-unmodified-since-header +
Rule id:
@@ -3498,6 +3532,7 @@ paths: ### ibm-no-nullable-properties +
Rule id:
@@ -3627,6 +3662,7 @@ paths: ### ibm-no-operation-requestbody +
Rule id:
@@ -3729,6 +3765,7 @@ paths: ### ibm-no-optional-properties-in-required-body +
Rule id:
@@ -3790,6 +3827,7 @@ paths: ### ibm-no-ref-in-example +
Rule id:
@@ -3850,6 +3888,7 @@ paths: ### ibm-no-required-properties-in-optional-body +
Rule id:
@@ -3909,6 +3948,7 @@ paths: ### ibm-no-space-in-example-name +
Rule id:
@@ -3978,6 +4018,7 @@ paths: ### ibm-no-superfluous-allof +
Rule id:
@@ -4026,6 +4067,7 @@ components: ### ibm-no-unsupported-keywords +
Rule id:
@@ -4096,6 +4138,7 @@ info: ### ibm-openapi-tags-used +
Rule id:
@@ -4157,6 +4200,7 @@ paths: ### ibm-operation-responses +
Rule id:
@@ -4213,6 +4257,7 @@ paths: ### ibm-operation-summary +
Rule id:
@@ -4260,6 +4305,7 @@ paths: ### ibm-operation-summary-length +
Rule id:
@@ -4309,6 +4355,7 @@ paths: ### ibm-operationid-casing-convention +
Rule id:
@@ -4377,6 +4424,7 @@ paths: ### ibm-operationid-naming-convention +
Rule id:
@@ -4467,6 +4515,7 @@ paths: ### ibm-pagination-style +
Rule id:
@@ -4551,6 +4600,7 @@ n/a ### ibm-parameter-casing-convention +
Rule id:
@@ -4677,6 +4727,7 @@ components: ### ibm-parameter-description +
Rule id:
@@ -4737,6 +4788,7 @@ components: ### ibm-parameter-order +
Rule id:
@@ -4818,6 +4870,7 @@ paths: ### ibm-parameter-schema-or-content +
Rule id:
@@ -4863,6 +4916,7 @@ parameters: ### ibm-patch-request-content-type +
Rule id:
@@ -4932,6 +4986,7 @@ paths: ### ibm-path-segment-casing-convention +
Rule id:
@@ -4987,6 +5042,7 @@ paths: ### ibm-pattern-properties +
Rule id:
@@ -5056,6 +5112,7 @@ components: ### ibm-precondition-headers +
Rule id:
@@ -5131,6 +5188,7 @@ paths: ### ibm-prefer-token-pagination +
Rule id:
@@ -5231,6 +5289,7 @@ paths: ### ibm-property-attributes +
Rule id:
@@ -5309,6 +5368,7 @@ components: ### ibm-property-casing-convention +
Rule id:
@@ -5387,6 +5447,7 @@ components: ### ibm-property-consistent-name-and-type +
Rule id:
@@ -5454,6 +5515,7 @@ components: ### ibm-property-description +
Rule id:
@@ -5509,6 +5571,7 @@ components: ### ibm-redirect-response-body +
Rule id:
@@ -5592,6 +5655,7 @@ paths: ### ibm-ref-pattern +
Rule id:
@@ -5674,6 +5738,7 @@ components: ### ibm-request-and-response-content +
Rule id:
@@ -5718,6 +5783,7 @@ responses: ### ibm-requestbody-is-object +
Rule id:
@@ -5766,6 +5832,7 @@ requestBody: ### ibm-requestbody-name +
Rule id:
@@ -5833,6 +5900,7 @@ paths: ### ibm-required-array-properties-in-response +
Rule id:
@@ -5913,6 +5981,7 @@ components: ### ibm-required-enum-properties-in-response +
Rule id:
@@ -6008,6 +6077,7 @@ components: ### ibm-resource-response-consistency +
Rule id:
@@ -6091,6 +6161,7 @@ paths: ### ibm-response-status-codes +
Rule id:
@@ -6214,6 +6285,7 @@ paths: ### ibm-schema-casing-convention +
Rule id:
@@ -6289,6 +6361,7 @@ components: ### ibm-schema-description +
Rule id:
@@ -6339,6 +6412,7 @@ components: ### ibm-schema-keywords +
Rule id:
@@ -6490,6 +6564,7 @@ components: ### ibm-schema-naming-convention +
Rule id:
@@ -6561,6 +6636,7 @@ paths: ### ibm-schema-type +
Rule id:
@@ -6611,6 +6687,7 @@ components: ### ibm-schema-type-format +
Rule id:
@@ -6704,6 +6781,7 @@ components: ### ibm-sdk-operations +
Rule id:
@@ -6739,6 +6817,7 @@ n/a ### ibm-securityscheme-attributes +
Rule id:
@@ -6845,6 +6924,7 @@ components: ### ibm-securityschemes +
Rule id:
@@ -6922,6 +7002,7 @@ components: ### ibm-server-variable-default-value +
Rule id:
@@ -6974,6 +7055,7 @@ servers: ### ibm-string-attributes +
Rule id:
@@ -7046,6 +7128,7 @@ components: ### ibm-success-response-example +
Rule id:
@@ -7107,6 +7190,7 @@ responses: ### ibm-summary-sentence-style +
Rule id:
@@ -7155,6 +7239,7 @@ paths: ### ibm-unevaluated-properties +
Rule id:
@@ -7215,6 +7300,7 @@ components: ### ibm-unique-parameter-request-property-names +
Rule id:
@@ -7332,6 +7418,7 @@ paths: ### ibm-use-date-based-format +
Rule id:
@@ -7392,6 +7479,7 @@ Resource ### ibm-valid-path-segments +
Rule id:
@@ -7445,6 +7533,7 @@ paths: ### ibm-valid-schema-example +
Rule id:
@@ -7492,6 +7581,7 @@ components: ### ibm-well-defined-dictionaries +
Rule id:
From eaf27b99334c89661950aca6a1129588a0254ea2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?L=C3=ADdia=20Tarcza?= <100163235+diatrcz@users.noreply.github.com> Date: Thu, 16 Jul 2026 14:25:54 +0200 Subject: [PATCH 04/20] chore: modify workflow file for testing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Lídia Tarcza <100163235+diatrcz@users.noreply.github.com> --- .github/workflows/jekyll-gh-pages.yml | 51 --------------------------- 1 file changed, 51 deletions(-) delete mode 100644 .github/workflows/jekyll-gh-pages.yml diff --git a/.github/workflows/jekyll-gh-pages.yml b/.github/workflows/jekyll-gh-pages.yml deleted file mode 100644 index 67be9b00..00000000 --- a/.github/workflows/jekyll-gh-pages.yml +++ /dev/null @@ -1,51 +0,0 @@ -# Sample workflow for building and deploying a Jekyll site to GitHub Pages -name: Deploy Jekyll with GitHub Pages dependencies preinstalled - -on: - # Runs on pushes targeting the default branch - push: - branches: ["main"] - - # Allows you to run this workflow manually from the Actions tab - workflow_dispatch: - -# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages -permissions: - contents: read - pages: write - id-token: write - -# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. -# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. -concurrency: - group: "pages" - cancel-in-progress: false - -jobs: - # Build job - build: - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: actions/checkout@v4 - - name: Setup Pages - uses: actions/configure-pages@v5 - - name: Build with Jekyll - uses: actions/jekyll-build-pages@v1 - with: - source: ./ - destination: ./_site - - name: Upload artifact - uses: actions/upload-pages-artifact@v3 - - # Deployment job - deploy: - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - runs-on: ubuntu-latest - needs: build - steps: - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v5 From 7fdbbd97a48408cd126933c4954a54e486a01a5a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?L=C3=ADdia=20Tarcza?= <100163235+diatrcz@users.noreply.github.com> Date: Thu, 16 Jul 2026 14:27:56 +0200 Subject: [PATCH 05/20] chore: modify workflow file for testing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Lídia Tarcza <100163235+diatrcz@users.noreply.github.com> --- .github/workflows/github-pages.yml | 53 ++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 .github/workflows/github-pages.yml diff --git a/.github/workflows/github-pages.yml b/.github/workflows/github-pages.yml new file mode 100644 index 00000000..9c7e1b24 --- /dev/null +++ b/.github/workflows/github-pages.yml @@ -0,0 +1,53 @@ +# Sample workflow for building and deploying a Jekyll site to GitHub Pages +name: Deploy Jekyll with GitHub Pages dependencies preinstalled + +on: + # Runs on pushes targeting the default branch + push: + branches: ["main"] + pull-request: + branches: ["github-pages"] + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + # Build job + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Setup Pages + uses: actions/configure-pages@v5 + - name: Build with Jekyll + uses: actions/jekyll-build-pages@v1 + with: + source: ./ + destination: ./_site + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + + # Deployment job + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v5 From 0cdc8ed7c94ebae7c4ae70fa39a6d37ee84d64ac Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?L=C3=ADdia=20Tarcza?= <100163235+diatrcz@users.noreply.github.com> Date: Thu, 16 Jul 2026 14:29:57 +0200 Subject: [PATCH 06/20] chore: modify workflow file for testing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Lídia Tarcza <100163235+diatrcz@users.noreply.github.com> --- .github/workflows/github-pages.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/github-pages.yml b/.github/workflows/github-pages.yml index 9c7e1b24..7f118bd9 100644 --- a/.github/workflows/github-pages.yml +++ b/.github/workflows/github-pages.yml @@ -6,7 +6,7 @@ on: push: branches: ["main"] pull-request: - branches: ["github-pages"] + branches: ["lt/github-pages"] # Allows you to run this workflow manually from the Actions tab workflow_dispatch: From 528f2b6705f9a32c7d0726266ab1c53adbb05c3d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?L=C3=ADdia=20Tarcza?= <100163235+diatrcz@users.noreply.github.com> Date: Thu, 16 Jul 2026 14:31:37 +0200 Subject: [PATCH 07/20] chore: modify workflow file for testing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Lídia Tarcza <100163235+diatrcz@users.noreply.github.com> --- .github/workflows/github-pages.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/github-pages.yml b/.github/workflows/github-pages.yml index 7f118bd9..a6e19ab5 100644 --- a/.github/workflows/github-pages.yml +++ b/.github/workflows/github-pages.yml @@ -5,7 +5,7 @@ on: # Runs on pushes targeting the default branch push: branches: ["main"] - pull-request: + pull_request: branches: ["lt/github-pages"] # Allows you to run this workflow manually from the Actions tab From b4593bfb69296b6b4b2fb9d53a03c138eaafa7ac Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?L=C3=ADdia=20Tarcza?= <100163235+diatrcz@users.noreply.github.com> Date: Thu, 16 Jul 2026 14:59:51 +0200 Subject: [PATCH 08/20] chore: modify workflow file for testing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Lídia Tarcza <100163235+diatrcz@users.noreply.github.com> --- .github/workflows/github-pages.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/.github/workflows/github-pages.yml b/.github/workflows/github-pages.yml index a6e19ab5..7ba6950a 100644 --- a/.github/workflows/github-pages.yml +++ b/.github/workflows/github-pages.yml @@ -4,8 +4,6 @@ name: Deploy Jekyll with GitHub Pages dependencies preinstalled on: # Runs on pushes targeting the default branch push: - branches: ["main"] - pull_request: branches: ["lt/github-pages"] # Allows you to run this workflow manually from the Actions tab From cf58dfd0238472a14f0f19ad46691b973a36fa8f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?L=C3=ADdia=20Tarcza?= <100163235+diatrcz@users.noreply.github.com> Date: Thu, 16 Jul 2026 16:06:58 +0200 Subject: [PATCH 09/20] chore: fix rendering issues in md files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Lídia Tarcza <100163235+diatrcz@users.noreply.github.com> --- README.md | 2 +- docs/ibm-cloud-rules.md | 7 +++---- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index e5ac7787..cce0f9b0 100644 --- a/README.md +++ b/README.md @@ -986,7 +986,7 @@ Here is an example of JSON output: "entries": [] } }, - "hasResults": true + "hasResults": true, "impactScore": { "categorizedSummary": { "usability": 94, diff --git a/docs/ibm-cloud-rules.md b/docs/ibm-cloud-rules.md index 4c2c0c61..66dbd075 100644 --- a/docs/ibm-cloud-rules.md +++ b/docs/ibm-cloud-rules.md @@ -404,7 +404,7 @@ should probably be required instead of optional. - @@ -517,7 +517,6 @@ or application/merge-patch+json. - @@ -542,7 +541,6 @@ or application/merge-patch+json. - @@ -587,6 +585,7 @@ has non-form content. This rule is disabled by default. + @@ -594,7 +593,7 @@ has non-form content. This rule is disabled by default. - + From 8cfd8bc3c9ca4c59040d049c137c587a7720f204 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?L=C3=ADdia=20Tarcza?= <100163235+diatrcz@users.noreply.github.com> Date: Thu, 16 Jul 2026 16:38:03 +0200 Subject: [PATCH 10/20] chore: fix rendering issues in md files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Lídia Tarcza <100163235+diatrcz@users.noreply.github.com> --- docs/ibm-cloud-rules.md | 174 ++++++++++++++++++++-------------------- 1 file changed, 87 insertions(+), 87 deletions(-) diff --git a/docs/ibm-cloud-rules.md b/docs/ibm-cloud-rules.md index 66dbd075..50ee26b7 100644 --- a/docs/ibm-cloud-rules.md +++ b/docs/ibm-cloud-rules.md @@ -919,7 +919,7 @@ The - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + @@ -4683,7 +4683,7 @@ on query and path parameter names, the configuration object would look like this - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + @@ -6873,7 +6873,7 @@ Valid values for the in property are: - + - + - + - + - + - + - + - + - + - + - + - + @@ -1316,6 +1318,7 @@ ambiguity in an API definition. Therefore, multiple types should be avoided. One exception to this is that the special type "null" is simply ignored by the rule when counting the number of elements in the schema's type field. So, the type value ['string', 'integer'] would cause an error, but the type value ['string', 'null'] would not. +

 @@ -1439,6 +1442,7 @@ components: defining it separately within each of the operations that exist for that path.

This rule checks for situations in which a path parameter is defined identically within multiple operations under a given path, and returns a warning to alert the user that the path parameter should be defined on the path object instead. +

 @@ -1581,12 +1585,14 @@ with an array property named "things" (which is presumably defined as an array o "list"-type operation (with or without support for pagination) to make sure that the operation's response schema defines an array property whose name matches the last path segment within the operation's path string, which should also match the plural form of the resource type. +

For the purposes of this rule, an operation is considered to be a "list"-type operation if it is a "get" request and one of the following are also true:

  1. the operation's operationId starts with "list" (e.g. "list_things")
  2. the operation's path string does not end with a path parameter reference, but there is a companion path string that does end with a path parameter reference (e.g. "/v1/things" vs "/v1/things/{thing_id}"). +

 @@ -1707,6 +1713,7 @@ responses: @@ -1894,6 +1901,7 @@ components: with application/merge-patch+json requestBody content should not define any required properties or specify a non-zero value for the minProperties field.

This rule verifies that "merge-patch" operations adhere to this requirement. +

 @@ -1990,6 +1998,7 @@ that is the appropriate configuration to be used by Spectral's casing()1] to enforce the desired case convention for enum values.

The default configuration object provided in the rule definition is: +

 {
   type: 'snake'
@@ -2000,6 +2009,7 @@ to enforce the desired case convention for enum values.
 custom ruleset and modify the configuration such that the value of the type field 
 specifies the desired case convention.
 For example, to enforce camel case for enum values, the configuration object would look like this:
+

 
 {
   type: 'camel'
@@ -2108,6 +2118,7 @@ as described in the API Handbook.
 
  • If present, the target property must contain a valid
 error target model
 as described in the API Handbook.
    • 
+
    @@ -2257,6 +2268,7 @@ to provide a value for the If-Match or If-None-Match h (sometimes referred to as an "etag value"), then the API should provide a way for the user to obtain the etag value. And the standard way for a service to provide an etag value to the user is by returning it as the ETag response header within the GET operation's response. +

     @@ -2660,6 +2672,7 @@ requestBody: The recommendation is to instead use an object with a property that contains the array. This will allow you to expand the definition of the response body (e.g. add new properties) in a compatible way in the future if needed. + @@ -2712,7 +2725,6 @@ paths: sample response body: {"things": [ {"name": "thing-1"}, {"name": "thing-2"} ]} -
    Rule id:
    ibm-no-superfluous-allof warnWarns about schemas that contain only a single-element allOf, which are unnecessary./td> +Warns about schemas that contain only a single-element allOf, which are unnecessary. oas3
    oas3
    ibm-property-casing-convention error Schema property names should follow a specific case convention. oas3
    ibm-ref-pattern warn Ensures that $ref values follow the correct patterns. Operations that create or update a resource should return the same schema as the "GET" request for the resource. oas3
    ibm-response-status-codes warn Performs multiple checks on the status codes used in operation responses.
    ibm-schema-casing-conventionwarmwarn Schema names should follow a specific case convention. oas3
    oas3
    Non-compliant example:Non-compliant example: 
     requestBody:
@@ -981,7 +981,7 @@ since an un-anchored regular expression might match on only part of the string i
    		oas3
    Non-compliant example:Non-compliant example: 
     components:
@@ -1038,7 +1038,7 @@ Note: the rule will report additional details about each violation of the graph
    		oas3
    Non-compliant example:Non-compliant example: 
     components:
@@ -1141,7 +1141,7 @@ paths:
    		oas3
    Non-compliant example:Non-compliant example: 
     components:
@@ -1201,7 +1201,7 @@ and nested schemas (e.g. a schema property, an array items schema,
    		oas3
    Non-compliant example:Non-compliant example: 
     components:
@@ -1327,7 +1327,7 @@ would cause an error, but the type value ['string', 'null'] would n
    		oas3_1
    Non-compliant example:Non-compliant example: 
     components:
@@ -1390,7 +1390,7 @@ components:
    		oas3
    Non-compliant example:Non-compliant example: 
     components:
@@ -1450,7 +1450,7 @@ and returns a warning to alert the user that the path parameter should be define
    		oas3
    Non-compliant example:Non-compliant example: 
     paths:
@@ -1523,7 +1523,7 @@ Specifically, the rule will check to make sure a binary schema is NOT used in th
    		oas3
    Non-compliant example:Non-compliant example: 
     paths:
@@ -1599,7 +1599,7 @@ companion path string that does end with a path parameter reference (e.g. "/v1/t
    		oas3
    Non-compliant example:Non-compliant example: 
     paths:
@@ -1666,7 +1666,7 @@ paths:
    		oas3
    Non-compliant example:Non-compliant example: 
     responses:
@@ -1718,7 +1718,7 @@ unless the API actually supports all content types.
    		oas3
    Non-compliant example:Non-compliant example: 
     requestBody:
@@ -1772,7 +1772,7 @@ The property could be defined in any of the following ways:
    		oas3
    Non-compliant example:Non-compliant example: 
     components:
@@ -1839,7 +1839,7 @@ This includes the following validations:
    		oas3
    Non-compliant example:Non-compliant example: 
     components:
@@ -1905,7 +1905,7 @@ define any required properties or specify a non-zero value for the minProp
    		oas3
    Non-compliant example:Non-compliant example: 
     paths:
@@ -2008,7 +2008,7 @@ For example, to enforce camel case for enum values, the configuration object wou
    Non-compliant example:Non-compliant example: 
     components:
@@ -2061,7 +2061,7 @@ This rule should be ignored when the API actually returns an error response that
    		oas3
    Non-compliant example:Non-compliant example: 
     responses:
@@ -2120,7 +2120,7 @@ as described in the API Handbook.
    		oas3
    Non-compliant example:Non-compliant example: 
     paths:
@@ -2268,7 +2268,7 @@ within the GET operation's response.
    		oas3
    Non-compliant example:Non-compliant example: 
     paths:
@@ -2372,7 +2372,7 @@ is specified as int32 or int64.
    		oas3
    Non-compliant example:Non-compliant example: 
     components:
@@ -2431,7 +2431,7 @@ The API major version can appear in either the server URL or in each path entry.
    		oas3
    Non-compliant example:Non-compliant example: 
     openapi: 3.0.1
@@ -2615,7 +2615,7 @@ paths:
    		oas3
    Non-compliant example:Non-compliant example: 
     requestBody:
@@ -2670,7 +2670,7 @@ in the future if needed.
    		oas3
    Non-compliant example:Non-compliant example: 
     paths:
@@ -2748,7 +2748,7 @@ together with other documentation provided for the service.
    		oas3
    Non-compliant example:Non-compliant example: 
     paths:
@@ -2825,7 +2825,7 @@ paths:
    		oas3
    Non-compliant example:Non-compliant example: 
     paths:
@@ -2893,7 +2893,7 @@ Any reference to either "Foo" or "Bar" will be a circular reference.
    		oas3
    Non-compliant example:Non-compliant example: 
     components:
@@ -2957,7 +2957,7 @@ For example, the path /v1/foos/{foo_id}/{bar_id} is invalid and sho
    		oas3
    Non-compliant example:Non-compliant example: 
     paths:
@@ -3011,7 +3011,7 @@ Note that the Content-Type header parameter is managed automaticall
    		oas3
    Non-compliant example:Non-compliant example: 
     paths:
@@ -3114,7 +3114,7 @@ are true for a particular parameter, then a warning is raised for that parameter
    		oas3
    Non-compliant example:Non-compliant example: 
     components:
@@ -3176,7 +3176,7 @@ components:
    		oas3
    Non-compliant example:Non-compliant example: 
     components:
@@ -3320,7 +3320,7 @@ components:
    		oas3
    Non-compliant example:Non-compliant example: 
     components:
@@ -3555,7 +3555,7 @@ This rule ensures that nullable properties are not defined elsewhere.
    		oas3
    Non-compliant example:Non-compliant example: 
     components:
@@ -3708,7 +3708,7 @@ For example, to enforce the rule for DELETE, HEAD and OPTIONS operations, the co
    Non-compliant example:Non-compliant example: 
     paths:
@@ -3789,7 +3789,7 @@ This rule is deprecated.  Please use the ibm-no-required-properties-in-opt
    		oas3
    Non-compliant example:Non-compliant example: 
     paths:
@@ -3845,7 +3845,7 @@ paths:
    		oas3
    Non-compliant example:Non-compliant example: 
     paths:
@@ -3910,7 +3910,7 @@ request body to be required.
    		oas3
    Non-compliant example:Non-compliant example: 
     paths:
@@ -3966,7 +3966,7 @@ paths:
    		oas3
    Non-compliant example:Non-compliant example: 
     paths:
@@ -4036,7 +4036,7 @@ paths:
    		oas3
    Non-compliant example:Non-compliant example: 
     components:
@@ -4088,7 +4088,7 @@ by IBM's SDK-related tooling - specifically the jsonSchemaDialect a
    		oas3_1
    Non-compliant example:Non-compliant example: 
     openapi: 3.1.0
@@ -4156,7 +4156,7 @@ info:
    		oas3
    Non-compliant example:Non-compliant example: 
     tags:
@@ -4219,7 +4219,7 @@ paths:
    		oas3_1
    Non-compliant example:Non-compliant example: 
     paths:
@@ -4276,7 +4276,7 @@ paths:
    		oas3
    Non-compliant example:Non-compliant example: 
     paths:
@@ -4325,7 +4325,7 @@ per guidance in the oas3
    Non-compliant example:Non-compliant example: n/a
    Non-compliant example:Non-compliant example: 
     components:
@@ -4745,7 +4745,7 @@ components:
    		oas3
    Non-compliant example:Non-compliant example: 
     components:
@@ -4808,7 +4808,7 @@ listed first, then any optional parameters.
    		oas3
    Non-compliant example:Non-compliant example: 
     paths:
@@ -4888,7 +4888,7 @@ paths:
    		oas3
    Non-compliant example:Non-compliant example: 
     parameters:
@@ -4938,7 +4938,7 @@ recommends that PATCH operations contain request bodies that support only conten
    		oas3
    Non-compliant example:Non-compliant example: 
     paths:
@@ -5020,7 +5020,7 @@ For example, to enforce camel case for path segments, the configuration object w
    Non-compliant example:Non-compliant example: 
     paths:
@@ -5066,7 +5066,7 @@ within a schema:
    		oas3_1
    Non-compliant example:Non-compliant example: 
     components:
@@ -5132,7 +5132,7 @@ For more details, please see the API Handbook section on
    		oas3
    Non-compliant example:Non-compliant example: 
     paths:
@@ -5206,7 +5206,7 @@ paths:
    		oas3
    Non-compliant example:Non-compliant example: 
     paths:
@@ -5332,7 +5332,7 @@ paths:
    		oas3
    Non-compliant example:Non-compliant example: 
     components:
@@ -5411,7 +5411,7 @@ For example, to enforce camel case for property names, the configuration object
    Non-compliant example:Non-compliant example: 
     components:
@@ -5469,7 +5469,7 @@ throughout the API definition.
    		oas3
    Non-compliant example:Non-compliant example: 
     components:
@@ -5533,7 +5533,7 @@ components:
    		oas3
    Non-compliant example:Non-compliant example: 
     components:
@@ -5631,7 +5631,7 @@ paths:
    Non-compliant example:Non-compliant example: 
     paths:
@@ -5695,7 +5695,7 @@ proper locations within the API definition's componentsfield.
    		oas3
    Non-compliant example:Non-compliant example: 
     components:
@@ -5756,7 +5756,7 @@ components:
    		oas3
    Non-compliant example:Non-compliant example: 
     responses:
@@ -5801,7 +5801,7 @@ responses:
    		oas3
    Non-compliant example:Non-compliant example: 
     requestBody:
@@ -5861,7 +5861,7 @@ that the x-codegen-request-body-name extension is set on the operat
    		oas3
    Non-compliant example:Non-compliant example: 
     paths:
@@ -5923,7 +5923,7 @@ and not optional.
    		oas3
    Non-compliant example:Non-compliant example: 
     paths:
@@ -6004,7 +6004,7 @@ and not optional.
    		oas3
    Non-compliant example:Non-compliant example: 
     paths:
@@ -6095,7 +6095,7 @@ components:
    		oas3
    Non-compliant example:Non-compliant example: 
     paths:
@@ -6233,7 +6233,7 @@ it is a synchronous or asynchronous operation.
    		oas3
    Non-compliant example:Non-compliant example: 
     paths:
@@ -6331,7 +6331,7 @@ For example, to disallow capitalized acronymns for schema names, the configurati
    Non-compliant example:Non-compliant example: 
     components:
@@ -6379,7 +6379,7 @@ components:
    		oas3
    Non-compliant example:Non-compliant example: 
     components:
@@ -6527,7 +6527,7 @@ configuration field, like this:
    Non-compliant example:Non-compliant example: 
     components:
@@ -6586,7 +6586,7 @@ The rule checks the names of collection schemas, resource collection element sch
    		oas3
    Non-compliant example:Non-compliant example: 
     paths:
@@ -6658,7 +6658,7 @@ Schemas and schema properties should have a non-empty type field.
    		oas3
    Non-compliant example:Non-compliant example: 
     components:
@@ -6733,7 +6733,7 @@ The following table defines the valid combinations:
    		oas3
    Non-compliant example:Non-compliant example: 
     components:
@@ -6801,7 +6801,7 @@ extension, using t
    		oas3
    Non-compliant example:Non-compliant example: n/a oas3
    Non-compliant example:Non-compliant example: 
     components:
@@ -6961,7 +6961,7 @@ scopes, then its scopes array MUST be empty.
    		oas3
    Non-compliant example:Non-compliant example: 
     paths:
@@ -7020,7 +7020,7 @@ components:
    		oas3
    Non-compliant example:Non-compliant example: 
     servers:
@@ -7088,7 +7088,7 @@ only for string schemas.
    		oas3
    Non-compliant example:Non-compliant example: 
     components:
@@ -7148,7 +7148,7 @@ within each response content field entry, in order to aid in the ge
    		oas3
    Non-compliant example:Non-compliant example: 
     responses:
@@ -7209,7 +7209,7 @@ not have a trailing period.
    		 oas3
    Non-compliant example:Non-compliant example: 
     paths:
@@ -7259,7 +7259,7 @@ is set on a schema, then it is set to the value false (i.e. disable
    		oas3_1
    Non-compliant example:Non-compliant example: 
     components:
@@ -7338,7 +7338,7 @@ the parameter or request body schema property to avoid the collision.
    		oas3
    Non-compliant example:Non-compliant example: 
     paths:
@@ -7441,7 +7441,7 @@ the example value provided for a schema or property.
    		oas3
    Non-compliant example:Non-compliant example: 
     Resource
@@ -7501,7 +7501,7 @@ For example, the path /v1/foos/_{foo_id}_ is invalid and should pro
    		oas3
    Non-compliant example:Non-compliant example: 
     paths:
@@ -7553,7 +7553,7 @@ is a valid instance of that schema. Note that this rule is an alternative to `oa
    		oas3
    Non-compliant example:Non-compliant example: 
     components:
@@ -7605,7 +7605,7 @@ components:
    		oas3
    Non-compliant example:Non-compliant example: 
     components:

From 670833e3da0ece0955109dfa9bd1087db1fe3a2f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?L=C3=ADdia=20Tarcza?=
 <100163235+diatrcz@users.noreply.github.com>
Date: Mon, 20 Jul 2026 16:59:35 +0200
Subject: [PATCH 11/20] docs: fix html formatting in markdown files
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Lídia Tarcza <100163235+diatrcz@users.noreply.github.com>
---
 .github/workflows/github-pages.yml |  2 +-
 docs/ibm-cloud-rules.md            | 62 ++++++++++++++++++++++++++++--
 2 files changed, 59 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/github-pages.yml b/.github/workflows/github-pages.yml
index 7ba6950a..ef8896c1 100644
--- a/.github/workflows/github-pages.yml
+++ b/.github/workflows/github-pages.yml
@@ -1,5 +1,5 @@
 # Sample workflow for building and deploying a Jekyll site to GitHub Pages
-name: Deploy Jekyll with GitHub Pages dependencies preinstalled
+name: deploy github pages
 
 on:
   # Runs on pushes targeting the default branch
diff --git a/docs/ibm-cloud-rules.md b/docs/ibm-cloud-rules.md
index 50ee26b7..6fae78da 100644
--- a/docs/ibm-cloud-rules.md
+++ b/docs/ibm-cloud-rules.md
@@ -1188,8 +1188,10 @@ the SDK generator typically needs to refactor these inline schemas in order to c
 computed by the SDK generator are unlikely to be optimal from a readability standpoint.
 
    Specifically, this rule warns about the use of inline object schemas within request bodies, responses,
 and nested schemas (e.g. a schema property, an array items schema, an additionalProperties schema, etc.).
+
    
 
    More information about this can be found in the
 API Handbook.
+
    The use of */* as a mimetype within a content field should be avoided unless the API actually supports all content types.

    If the API in fact supports all content types, this warning should be ignored. +
    Severity:
    @@ -2734,9 +2746,11 @@ The security object can be defined at an operation level (which wou that operation) or at a global level within the API definition (which would apply to all operations).

    Within generated SDKs, the Authorization header will be managed automatically by the built-in authenticator support. +

    Non-SDK users (those using curl, for example) can infer the use of the Authorization header from the security object in the API definition together with other documentation provided for the service. +

    @@ -2814,6 +2828,7 @@ paths: Description: This rule checks each DELETE operation and will return a warning if the operation contains a requestBody.

    This rule has been deprecated and is now disabled in the IBM Cloud Validation Ruleset. Please use the ibm-no-operation-requestbody rule instead. +

    @@ -3083,6 +3098,7 @@ will perform the following checks:
  • The parameter's schema is defined with a pattern field that starts with either "crn" or "^crn" (e.g. 'crn:[-0-9A-Fa-f]+')
  • The parameter's example field contains a CRN-like value (e.g. "crn:0afd-0138-2636")
  • The parameter's examples field contains an entry containing a CRN-like value, as in this example: +
    components: @@ -3259,6 +3275,7 @@ the first and next page of results, respectively.

    Starting with OpenAPI 3.0, one can no longer use this pattern. If a schema definition contains the $ref attribute, then no other attributes are allowed to be defined alongsize it. So to work around this restriction, API authors typically use the "ref sibling" allOf pattern. The above example might look like this: +

     components:
   schemas:
@@ -3290,6 +3307,7 @@ second allOf list element.  Both are considered to be examples of the "ref sibli
 
    This rule specifically looks for instances of this pattern where the overridden description is the same as the
 description defined within the referenced schema, thus making the use of the "ref sibling" pattern unnecessary.
 Here is an example of this:
+
    
 
     components:
   schemas:
@@ -3393,6 +3411,7 @@ Operations should support If-Match and If-None-Match h
 
 Non-compliant example:
 
+
    
 
     paths:
   '/v1/things/{thing_id}':
@@ -3478,6 +3497,7 @@ Operations should support If-Match and If-None-Match h
 
 Non-compliant example:
 
+
    
 
     paths:
   '/v1/things/{thing_id}':
@@ -3690,6 +3710,7 @@ This rule ensures that these operations do not define a requestBody
 This rule supports a configuration that specifies the set of HTTP methods that are checked
 for a requestBody.
 
    The default configuration object provided with the rule is:
+
    
 
     {
   httpMethods: ['delete', 'get', 'head', 'options']
@@ -3700,6 +3721,7 @@ for a requestBody.
 custom ruleset and modify the configuration such that the value of the httpMethods field 
 specifies the desired set of HTTP methods to be checked.
 For example, to enforce the rule for DELETE, HEAD and OPTIONS operations, the configuration object would look like this:
+
    
 
     {
   httpMethods: ['delete', 'head', 'options']
@@ -4046,7 +4068,7 @@ components:
         foo_ref:
           allOf:
             - $ref: '#/components/schemas/Foo'
-<
    
+
    
 
 
 
@@ -4380,6 +4402,7 @@ that is the appropriate configuration to be used by Spectral's casing()1]
 to enforce the desired case convention for operationId values.
 
    The default configuration object provided in the rule definition is:
+
    
 
     {
   type: 'snake'
@@ -4390,6 +4413,7 @@ to enforce the desired case convention for operationId values.
 custom ruleset and modify the configuration such that the value of the type field 
 specifies the desired case convention.
 For example, to enforce camel case for operation ids, the configuration object would look like this:
+
    
 
     {
   type: 'camel'
@@ -4437,12 +4461,14 @@ when deciding on an operationId for the POST /v1/things operation.
 Likewise, for the GET /v1/things/{thing_id} operation, we might prefer
 get_thing over retrieve_thing for the operationId.
 
    This rule will analyze the operations, looking for operationId values that are not using the recommended verbs. Furthermore it can also validate the complete name of the operation id by comparing it to the path segments.
+
    
 
 
 
 Configuration:
 This rule can be configured to validate the complete name of the operation id, or only the verb it begins with.
 
    The default configuration object provided in the rule definition is:
+
    
 
     {
   strict: true
@@ -4451,6 +4477,7 @@ Likewise, for the GET /v1/things/{thing_id} operation, we might pre
 
    To switch off the complete name validation and only validate the verbs the operation ids begin with, you'll need to
 replace this rule with a new rule within your
 custom ruleset and modify the configuration such that the value of the strict field to false
+
    
 
     {
   strict: false
@@ -4533,9 +4560,11 @@ paths:
 
  • The operation defines either the offset query parameter or a page-token type
 query parameter whose name is one of the following: start(preferred), 
 token, cursor, page, or page_token.
    • 
+
    
 
 
    If an operation is recognized as a paginated list-type operation, then the following checks are
 performed:
+
    
 
 
    To disable the case convention checks for a particular parameter type, simply remove
 the entry for that parameter type from the configuration object.  
+
    
 
    If you want to use a different configuration for this rule other than the default configuration
 mentioned above, you'll need to
 replace this rule with a new rule within your
 custom ruleset and modify the configuration appropriately for your needs.
 For example, to disable the case convention checks on header parameter names, while enforcing camel-case conventions
 on query and path parameter names, the configuration object would look like this:
+
    
 
     {
   query: {
@@ -4927,6 +4959,7 @@ parameters:
 recommends that PATCH operations contain request bodies that support only content types
 application/json-patch+json and application/merge-patch+json.
 
    This rule verifies that each PATCH operation complies with this recommendation.
+
    
 
 
 
@@ -5012,6 +5045,7 @@ to enforce a different case convention if desired.
 custom ruleset and modify the configuration such that the value of the type field 
 specifies the desired case convention.
 For example, to enforce camel case for path segments, the configuration object would look like this:
+
    
 
     {
   type: 'camel'
@@ -5393,6 +5427,7 @@ that is the appropriate configuration to be used by Spectral's casing()1]
 to enforce the desired case convention for property names.
 
    The default configuration object provided in the rule definition is:
+
    
 
     {
   type: 'snake'
@@ -5403,6 +5438,7 @@ to enforce the desired case convention for property names.
 custom ruleset and modify the configuration such that the value of the type field 
 specifies the desired case convention.
 For example, to enforce camel case for property names, the configuration object would look like this:
+
    
 
     {
   type: 'camel'
@@ -5587,6 +5623,7 @@ components:
 
    References:
 
    
 
 
@@ -5599,7 +5636,7 @@ components:
 oas3
 
 
-Compliant example:
+Compliant example:
 
 
     paths:
@@ -5676,6 +5713,7 @@ the type of object it references.  For example, a reference to a schema should f
 
  • #/components/responses/<name>
    • 
 
  • #/components/schemas/<name>
    • 
 
  • #/components/securitySchemes/<name>
    • 
+
    
 
 The validator uses the $ref property's location within the API definition
 to determine the type of object being referenced.  For example, if the
@@ -5850,6 +5888,7 @@ way to infer a logical name for the operation's body parameter.
 that the x-codegen-request-body-name extension is set on the operation.
 

    
 This rule is disabled by default. Enable it in your Spectral config file to utilize this validation.
+
    
 
 
 
@@ -6191,6 +6230,7 @@ or a 202 - Accepted status code.
    • operationId starts with "create" or the operation is a POST request and there is another path present in the API that is similar to the path of the "create" operation, but with a trailing path parameter reference. For example, "process_things" would be considered a "create"-type operation: +

       paths:
     '/v1/things':
@@ -6221,6 +6261,7 @@ it is a synchronous or asynchronous operation.
 
  • IBM Cloud API Handbook: Fundamentals/Status Codes
    • 
 
  • IBM Cloud API Handbook: Fundamentals/Methods
    • 
 
  • RFC7231 - Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content
    • 
+
    
 
 
 
@@ -6313,6 +6354,7 @@ that is the appropriate configuration to be used by Spectral's pattern()1]
 to enforce the desired case convention for schema name values.
 
    The default configuration object provided in the rule definition is:
+
    
 
     {
   match: '/^[A-Z]+[a-z0-9]+([A-Z]+[a-z0-9]*)*$/'
@@ -6323,6 +6365,7 @@ to enforce the desired case convention for schema name values.
 custom ruleset and modify the configuration such that the value of the match field 
 specifies the desired case convention.
 For example, to disallow capitalized acronymns for schema names, the configuration object would look like this:
+
    
 
     {
   match: '/^[A-Z][a-z0-9]+([A-Z][a-z0-9]+)*$/'
@@ -6437,6 +6480,7 @@ in an OpenAPI 3.1.x document. The allowable keywords are configurable (see the <
 This rule supports a configuration object that specifies the set of keywords that are allowed within a schema
 or schema property.
 
    The default configuration object provided with the rule is:
+
    
 
     {
   keywordAllowList: [
@@ -6485,6 +6529,7 @@ contains the desired set of keywords to be checked.
 For example, to configure the rule so that uniqueItems and unevaluatedProperties are disallowed, 
 modify the configuration to remove these keywords from the keywordAllowList
 configuration field, like this:
+
    
 
     {
   keywordAllowList: [
@@ -6834,6 +6879,7 @@ with the constraints outlined in the 
 
      
 
    1. the operation's operationId starts with "list" (e.g. "list_things")
 
    2. the operation's path string does not end with a path parameter reference, but there is a
 companion path string that does end with a path parameter reference (e.g. "/v1/things" vs "/v1/things/{thing_id}").
-
      
 
    
 
 
@@ -2108,6 +2108,7 @@ responses:
 Description:
 This rule implements the guidance related to error response schemas found in the     API Handbook.
 
    Specifically, the following checks are performed against each schema associated with an error response:
+
    
 
      
 
    • The error response schema should form a valid
 error container model as
@@ -2118,7 +2119,6 @@ as described in the API Handbook.
      • 
 
    • If present, the target property must contain a valid
 error target model
 as described in the API Handbook.
      • 
-
      
 
    
 
 
@@ -4552,15 +4552,15 @@ paths:
 This rule verifies that list-type operations implement pagination correctly per the guidelines in the 
 API Handbook.
 
    An operation is recognized as a paginated list-type operation if all of the following are true:
+
    
 
      
 
    • The path doesn't end in a path segment that is a path parameter reference
 (e.g. /v1/things vs /v1/things/{thing_id}).
      • 
 
    • The operation is a get.
      • 
 
    • The operation's response schema is an object containing an array property.
      • 
 
    • The operation defines either the offset query parameter or a page-token type
-query parameter whose name is one of the following: start(preferred), 
+query parameter whose name is one of the following: start(preferred),
 token, cursor, page, or page_token.
      • 
-
      
 
    
 
    If an operation is recognized as a paginated list-type operation, then the following checks are
 performed:
@@ -5621,9 +5621,9 @@ components:
 
  • For a 30x response the code field must contain one of the following values for redirect code and nothing else: forwarded, resolved, moved, remote_region, remote_account, version_mismatch.
    • 
 
 
    References:
+
    
 
 
 
@@ -5703,6 +5703,7 @@ paths:
 the type of object it references.  For example, a reference to a schema should follow the pattern 
 #/components/schemas/<schema-name>.
 
    Here is the full set of valid patterns for $ref values:
+
    
 
      
 
    • #/components/callbacks/<name>
      • 
 
    • #/components/examples/<name>
      • 
@@ -5713,7 +5714,6 @@ the type of object it references.  For example, a reference to a schema should f
 
    • #/components/responses/<name>
      • 
 
    • #/components/schemas/<name>
      • 
 
    • #/components/securitySchemes/<name>
      • 
-
      
 
    
 The validator uses the $ref property's location within the API definition
 to determine the type of object being referenced.  For example, if the
@@ -6256,12 +6256,12 @@ with a trailing path parameter reference that would give us a hint that "handle_
 success (2xx) status codes. This is because an operation should be unambiguous in terms of whether or not
 it is a synchronous or asynchronous operation.
 
-
    References: 
+
    References:
+
    
 
 
 
@@ -6872,6 +6872,7 @@ n/a
 Performs a series of validations on the content within security schemes to ensure they comply
 with the constraints outlined in the OpenAPI Specification.
 
    Specifically, the rule will perform these checks:
+
    
 
      
 
    1. Each security scheme must specify the type property. Valid values for the type property are:
 
    
 
 
@@ -7114,14 +7113,14 @@ servers:
 fields in order to clearly define the set of valid values for the property.
 [1].
 
    Note that these checks are bypassed for the following scenarios:
+
    
 
      
 
    • All checks are bypassed for string schemas that contain an enum field.
      • 
-
    • The check for the pattern field is bypassed if format is set to 
+
    • The check for the pattern field is bypassed if format is set to
 binary, byte, date, date-time, or url.
      • 
 
    • The check for the minLength field is bypassed if format is set to
 date, identifier, or url.
      • 
 
    • The check for the maxLength field is bypassed if format is set to date.
      • 
-
      
 
    
 
    This rule also checks non-string schema properties to make sure they do not define the
 pattern, minLength and maxLength fields since these fields are applicable

From 30b19c02b5f970107500398b4c68a7c1895cf446 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?L=C3=ADdia=20Tarcza?=
 <100163235+diatrcz@users.noreply.github.com>
Date: Tue, 21 Jul 2026 10:08:39 +0200
Subject: [PATCH 13/20] docs: fix html formatting in markdown files
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Lídia Tarcza <100163235+diatrcz@users.noreply.github.com>
---
 docs/ibm-cloud-rules.md | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/docs/ibm-cloud-rules.md b/docs/ibm-cloud-rules.md
index 851fd1a7..cb9af4c6 100644
--- a/docs/ibm-cloud-rules.md
+++ b/docs/ibm-cloud-rules.md
@@ -3098,9 +3098,7 @@ will perform the following checks:
 
  • The parameter's schema is defined with a pattern field that starts with either "crn" or "^crn" (e.g. 'crn:[-0-9A-Fa-f]+')
    • 
 
  • The parameter's example field contains a CRN-like value (e.g. "crn:0afd-0138-2636")
    • 
 
  • The parameter's examples field contains an entry containing a CRN-like value, as in this example:
-
    
 
    -
    
 components:
   parameters:
     ThingIdParam:
@@ -3113,13 +3111,16 @@ components:
       examples:
         crn_example:
           value: 'crn:0afd-0138-2636'
+
    • 
 
 
  • The parameter schema's example field contains a CRN-like value (e.g. "crn:0afd-0138-2636")
    • 
 
  • The parameter's description field contains either "CRN" or "Cloud Resource Name"
    • 
 
  • The parameter schema's description field contains either "CRN" or "Cloud Resource Name"
    • 
 
 These checks are logically OR'd together, so that if any one or more of these checks
-are true for a particular parameter, then a warning is raised for that parameter. 
+are true for a particular parameter, then a warning is raised for that parameter.
+
    
+
 
 
 Severity:
@@ -3399,6 +3400,8 @@ components:
 recommends against the use of the If-Modified-Since and If-Unmodified-Since header parameters.
 Operations should support If-Match and If-None-Match headers instead.
 
    This rule warns about operations that support the If-Modified-Since header parameter.
+
    
+
 
 
 Severity:
@@ -3411,7 +3414,6 @@ Operations should support If-Match and If-None-Match h
 
 Non-compliant example:
 
-
    
 
     paths:
   '/v1/things/{thing_id}':
@@ -3485,6 +3487,8 @@ paths:
 recommends against the use of the If-Modified-Since and If-Unmodified-Since header parameters.
 Operations should support If-Match and If-None-Match headers instead.
 
    This rule warns about operations that support the If-Unmodified-Since header parameter.
+
    
+
 
 
 Severity:
@@ -3497,7 +3501,6 @@ Operations should support If-Match and If-None-Match h
 
 Non-compliant example:
 
-
    
 
     paths:
   '/v1/things/{thing_id}':
@@ -5090,6 +5093,7 @@ within a schema:
 
  • The patternProperties and additionalProperties fields are mutually exclusive within a particular schema.
 
  • The patternProperties field must contain a regular expression anchored by ^ and $.
 
+
 
 
 Severity:
@@ -6119,7 +6123,7 @@ components:
 
-
+
@@ -7299,6 +7303,7 @@ paths:
 

From 631898c21439f9dfcb6b6cb04dfbef0ff4d7a696 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?L=C3=ADdia=20Tarcza?=
 <100163235+diatrcz@users.noreply.github.com>
Date: Tue, 21 Jul 2026 10:15:16 +0200
Subject: [PATCH 14/20] docs: fix html formatting in markdown files
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Lídia Tarcza <100163235+diatrcz@users.noreply.github.com>
---
 docs/ibm-cloud-rules.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/ibm-cloud-rules.md b/docs/ibm-cloud-rules.md
index cb9af4c6..afc08800 100644
--- a/docs/ibm-cloud-rules.md
+++ b/docs/ibm-cloud-rules.md
@@ -1591,8 +1591,10 @@ if it is a "get" request and one of the following are also true:
 
      
 
    1. the operation's operationId starts with "list" (e.g. "list_things")
+
      2. 
 
    2. the operation's path string does not end with a path parameter reference, but there is a
 companion path string that does end with a path parameter reference (e.g. "/v1/things" vs "/v1/things/{thing_id}").
+
      3. 
 
    
@@ -2558,12 +2560,16 @@ In general, two paths are ambiguous if the following are true:
 
  • one or the other of the path segments is parameterized (e.g. 'foo' vs '{foo_id}')
  • both of the path segments are parameterized (e.g. '{foo_id}' vs '{id}')
    • 
+
 Here are examples of paths that are ambiguous despite being unique:
 
      
 
    • /v1/things/{thing_id}, /v1/things/{id}
+
      • 
 
    • /v1/things/{thing_id}, /v1/things/other_things
+
      • 
 
    • /{version}/things, /v1/{things}
+
      • 
 
    
 Each of the pairs of path strings above would be considered ambiguous.
 

From e7c2f3583ee6c8256460344877ffc9d2579bab41 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?L=C3=ADdia=20Tarcza?=
 <100163235+diatrcz@users.noreply.github.com>
Date: Tue, 21 Jul 2026 11:55:21 +0200
Subject: [PATCH 15/20] docs: fix html formatting in markdown files
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Lídia Tarcza <100163235+diatrcz@users.noreply.github.com>
---
 docs/ibm-cloud-rules.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/docs/ibm-cloud-rules.md b/docs/ibm-cloud-rules.md
index afc08800..bb5367ad 100644
--- a/docs/ibm-cloud-rules.md
+++ b/docs/ibm-cloud-rules.md
@@ -5096,8 +5096,11 @@ paths:
 within a schema:
 
      
 
    • The patternProperties field must be an object with exactly one entry.
+
      • 
 
    • The patternProperties and additionalProperties fields are mutually exclusive within a particular schema.
+
      • 
 
    • The patternProperties field must contain a regular expression anchored by ^ and $.
+
      • 
 
    

From 9fc5fa5c78a847ba630e8531e2233af2ac142037 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?L=C3=ADdia=20Tarcza?=
 <100163235+diatrcz@users.noreply.github.com>
Date: Tue, 21 Jul 2026 12:01:55 +0200
Subject: [PATCH 16/20] docs: fix html formatting in markdown files
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Lídia Tarcza <100163235+diatrcz@users.noreply.github.com>
---
 docs/ibm-cloud-rules.md | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/docs/ibm-cloud-rules.md b/docs/ibm-cloud-rules.md
index bb5367ad..578d5cf5 100644
--- a/docs/ibm-cloud-rules.md
+++ b/docs/ibm-cloud-rules.md
@@ -6262,9 +6262,8 @@ but "handle_things" would not:
         operationId: handle_things
         ...
 
-The difference being that with the "handle_things" operation, there is no corresponding path
-with a trailing path parameter reference that would give us a hint that "handle_things" is a create-type operation.
-
+
  • The difference being that with the "handle_things" operation, there is no corresponding path
+with a trailing path parameter reference that would give us a hint that "handle_things" is a create-type operation.
  • An operation that returns a 202 - Accepted status code should not return any other
 success (2xx) status codes. This is because an operation should be unambiguous in terms of whether or not
 it is a synchronous or asynchronous operation.
    • 

From ece2553ddcd285434d0715b5c29425270a1875ea Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?L=C3=ADdia=20Tarcza?=
 <100163235+diatrcz@users.noreply.github.com>
Date: Tue, 21 Jul 2026 13:43:09 +0200
Subject: [PATCH 17/20] docs: fix html formatting in markdown files
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Lídia Tarcza <100163235+diatrcz@users.noreply.github.com>
---
 _config.yml | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/_config.yml b/_config.yml
index 57720b06..206705ca 100644
--- a/_config.yml
+++ b/_config.yml
@@ -1,3 +1,16 @@
 title: IBM OpenAPI Validator
 description: A highly configurable linter/validator for OpenAPI documents.
 theme: minima
+
+exclude:
+  - README.md
+  - CHANGELOG.md
+  - CONTRIBUTING.md
+  - Migration-Guide.md
+  - docs/automated-quality-screening.md
+  - docs/openapi-ruleset-utilities.md
+  - packages/
+  - node_modules/
+  - scripts/
+  - coverage/
+  - test-local/

From 29458003b1bc3e7f2e95fc7759a171793ec1564b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?L=C3=ADdia=20Tarcza?=
 <100163235+diatrcz@users.noreply.github.com>
Date: Tue, 21 Jul 2026 13:43:26 +0200
Subject: [PATCH 18/20] docs: fix html formatting in markdown files
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Lídia Tarcza <100163235+diatrcz@users.noreply.github.com>
---
 _sass/custom.scss | 27 +++++++++++++++++++++++++++
 assets/main.scss  |  6 ++++++
 2 files changed, 33 insertions(+)
 create mode 100644 _sass/custom.scss
 create mode 100644 assets/main.scss

diff --git a/_sass/custom.scss b/_sass/custom.scss
new file mode 100644
index 00000000..1a0e2b33
--- /dev/null
+++ b/_sass/custom.scss
@@ -0,0 +1,27 @@
+// Fix table layout so they never cause horizontal page scroll.
+// Tables are constrained to the wrapper width; pre blocks inside
+// cells scroll only within the cell (vertically wrapping the content).
+
+.post-content {
+  table {
+    table-layout: fixed;
+    width: 100%;
+    word-wrap: break-word;
+    overflow-wrap: break-word;
+
+    td, th {
+      word-wrap: break-word;
+      overflow-wrap: break-word;
+    }
+
+    // pre / code blocks inside table cells: scroll horizontally within
+    // the cell only, never overflow the page.
+    td pre, th pre {
+      overflow-x: auto;
+      max-width: 100%;
+      white-space: pre;
+      word-wrap: normal;
+      overflow-wrap: normal;
+    }
+  }
+}
diff --git a/assets/main.scss b/assets/main.scss
new file mode 100644
index 00000000..456bc665
--- /dev/null
+++ b/assets/main.scss
@@ -0,0 +1,6 @@
+---
+# Only the main Sass file needs front matter (the dashes are enough)
+---
+
+@import "minima";
+@import "custom";

From 96132a67eb9538ba7007f45c976917662b2c01fc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?L=C3=ADdia=20Tarcza?=
 <100163235+diatrcz@users.noreply.github.com>
Date: Tue, 21 Jul 2026 13:52:30 +0200
Subject: [PATCH 19/20] docs: fix html formatting in markdown files
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Lídia Tarcza <100163235+diatrcz@users.noreply.github.com>
---
 index.html | 13 +++++++++++++
 1 file changed, 13 insertions(+)
 create mode 100644 index.html

diff --git a/index.html b/index.html
new file mode 100644
index 00000000..b544e2ac
--- /dev/null
+++ b/index.html
@@ -0,0 +1,13 @@
+---
+---
+
+
+
+  
+  
+  IBM OpenAPI Validator
+
+
+  
    Redirecting to IBM Cloud Validation Ruleset…
    
+
+

From bbeb12a0a521ae22135b499d2f75f601039f0845 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?L=C3=ADdia=20Tarcza?=
 <100163235+diatrcz@users.noreply.github.com>
Date: Tue, 21 Jul 2026 13:57:44 +0200
Subject: [PATCH 20/20] build: revert workflow file to main
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Lídia Tarcza <100163235+diatrcz@users.noreply.github.com>
---
 .github/workflows/github-pages.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/github-pages.yml b/.github/workflows/github-pages.yml
index ef8896c1..130e153b 100644
--- a/.github/workflows/github-pages.yml
+++ b/.github/workflows/github-pages.yml
@@ -4,7 +4,7 @@ name: deploy github pages
 on:
   # Runs on pushes targeting the default branch
   push:
-    branches: ["lt/github-pages"]
+    branches: ["main"]
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
@@ -19,7 +19,7 @@ permissions:
 # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
 concurrency:
   group: "pages"
-  cancel-in-progress: false
+  cancel-in-progress: true
 
 jobs:
   # Build job

    
 
    
 Rule id:ibm-requestbody-nameibm-resource-response-consistency
 
    
 
    
 Description:This rule ensures that unevaluatedProperties is not enabled within a schema.
 It checks to make sure that if the unevaluatedProperties field
 is set on a schema, then it is set to the value false (i.e. disabled).
+
 
    
 
    
 Severity: