feat: update to openapi 3.1 and fix errors

.github/matcher-actionlint.json

@@ -0,0 +1,17 @@
+{
+  "problemMatcher": [
+    {
+      "owner": "actionlint",
+      "pattern": [
+        {
+          "regexp": "^(?:\\x1b\\[\\d+m)?(.+?)(?:\\x1b\\[\\d+m)*:(?:\\x1b\\[\\d+m)*(\\d+)(?:\\x1b\\[\\d+m)*:(?:\\x1b\\[\\d+m)*(\\d+)(?:\\x1b\\[\\d+m)*: (?:\\x1b\\[\\d+m)*(.+?)(?:\\x1b\\[\\d+m)* \\[(.+?)\\]$",
+          "file": 1,
+          "line": 2,
+          "column": 3,
+          "message": 4,
+          "code": 5
+        }
+      ]
+    }
+  ]
+}

.github/workflows/lint-tools.yml

@@ -0,0 +1,63 @@
+name: Lint
+on:
+  pull_request:
+
+jobs:
+  actionlint:
+    name: Actionlint
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Actionlint
+        env:
+          version: "1.7.7"
+        run:
+          curl -Ls "https://github.com/rhysd/actionlint/releases/download/v${{ env.version
+          }}/actionlint_${{ env.version }}_linux_amd64.tar.gz" | sudo tar -x -z -C /usr/local/bin
+          actionlint
+      - run: |
+          echo "::add-matcher::.github/matcher-actionlint.json"
+          actionlint -color
+
+  prettier:
+    name: Prettier
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - run: npx prettier --check .
+
+  vacuum:
+    name: Vacuum
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Vacuum
+        env:
+          version: 0.17.8
+        run:
+          curl -Ls "https://github.com/daveshanley/vacuum/releases/download/v${{ env.version
+          }}/vacuum_${{ env.version }}_linux_x86_64.tar.gz" | sudo tar -x -z -C /usr/local/bin
+          vacuum
+      - run: vacuum lint -d -e -b ./topsort-api-v2.yml
+
+  yamllint:
+    name: YAMLLint
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uvx yamllint -f github topsort-api-*.yml
+
+  redocly:
+    name: Redocly
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - run: npx @redocly/cli lint --format github-actions topsort-api-*.yml
+
+  typos:
+    name: Check for language typos
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: crate-ci/typos@v1.35.2

.prettierrc.json

@@ -0,0 +1,4 @@
+{
+  "printWidth": 100,
+  "proseWrap": "always"
+}

.yamllint.yaml

@@ -0,0 +1,5 @@
+extends: default
+
+rules:
+  document-start: disable
+  line-length: disable

README.md

@@ -1,7 +1,29 @@
 # Topsort OpenAPI
 
-Topsort uses the [OpenAPI 3.0.1](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md) specification to [document our APIs](https://docs.topsort.com) and we recommend our clients to use these specifications to generate supported client libraries and server scaffolding. This would provide a consistent and robust developer experience across languages.
+Topsort uses the [OpenAPI 3.1.0][openapi] specification to [document our APIs][docs] and we
+recommend our clients to use these specifications to generate supported client libraries and server
+scaffolding. This would provide a consistent and robust developer experience across languages.
+
+You can additionally consume the entire Topsort OpenAPI spec available [here][openapi-ts].
+
+## Validating the file
+
+- Use [prettier][prettier] to format the documents: `bunx prettier -w`
+- Use [yamllint][yamllint] to validate the documents: `uvx yamllint *.yml`
+- Use [vacuum][vacuum] to validate the openapi standard: `vacuum *.yml`
+- Use [redocly][redocly] to further validate the openapi standard: `bunx @redocly/cli lint *.yml`
+- Use [typos][typos] to fix language typos: `typos .`
 
 ## Using the OpenAPI generator
 
-You can find examples on the official [OpenAPI Generator docs](https://openapi-generator.tech/docs/usage#examples).
+You can find examples on the official
+[OpenAPI Generator docs](https://openapi-generator.tech/docs/usage#examples).
+
+[openapi]: https://spec.openapis.org/oas/v3.1.0.html
+[docs]: https://docs.topsort.com
+[openapi-ts]: https://docs.topsort.com/openapi.json
+[prettier]: https://prettier.io/
+[yamllint]: https://github.com/adrienverge/yamllint
+[vacuum]: https://quobix.com/vacuum/start/
+[redocly]: https://redocly.com/docs/cli/installation
+[typos]: https://github.com/crate-ci/typos