Linter workflow

.github/workflows/lint.yml

@@ -0,0 +1,27 @@
+name: Validate Spec
+
+on:
+  push:
+    branches: ['**']
+    paths:
+      - 'spec/**'
+      - 'tools/linter/**'
+  pull_request:
+    branches: ['**']
+    paths:
+      - 'spec/**'
+      - 'tools/linter/**'
+
+jobs:
+  lint-spec:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: tools
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 20.10.0
+      - run: npm install
+      - run: npm run lint -- ../spec

spec/namespaces/cat.yaml

@@ -43,6 +43,8 @@ paths:
       x-operation-group: cat.aliases
       x-version-added: '1.0'
       description: Shows information about currently configured aliases to indices including filter and routing infos.
+      externalDocs:
+        url: https://opensearch.org/docs/latest/api-reference/cat/cat-aliases/
       parameters:
         - $ref: '#/components/parameters/cat.aliases::path.name'
         - $ref: '#/components/parameters/cat.aliases::query.format'
@@ -82,6 +84,8 @@ paths:
       x-operation-group: cat.allocation
       x-version-added: '1.0'
       description: Provides a snapshot of how many shards are allocated to each data node and how much disk space they are using.
+      externalDocs:
+        url: https://opensearch.org/docs/latest/api-reference/cat/cat-allocation/
       parameters:
         - $ref: '#/components/parameters/cat.allocation::path.node_id'
         - $ref: '#/components/parameters/cat.allocation::query.format'
@@ -139,6 +143,8 @@ paths:
       x-operation-group: cat.count
       x-version-added: '1.0'
       description: Provides quick access to the document count of the entire cluster, or individual indices.
+      externalDocs:
+        url: https://opensearch.org/docs/latest/api-reference/cat/cat-count/
       parameters:
         - $ref: '#/components/parameters/cat.count::path.index'
         - $ref: '#/components/parameters/cat.count::query.format'
@@ -174,6 +180,8 @@ paths:
       x-operation-group: cat.fielddata
       x-version-added: '1.0'
       description: Shows how much heap memory is currently being used by fielddata on every data node in the cluster.
+      externalDocs:
+        url: https://opensearch.org/docs/latest/api-reference/cat/cat-field-data/
       parameters:
         - $ref: '#/components/parameters/cat.fielddata::path.fields'
         - $ref: '#/components/parameters/cat.fielddata::query.format'
@@ -237,6 +245,8 @@ paths:
       x-operation-group: cat.indices
       x-version-added: '1.0'
       description: 'Returns information about indices: number of primaries and replicas, document counts, disk size, ...'
+      externalDocs:
+        url: https://opensearch.org/docs/latest/api-reference/cat/cat-indices/
       parameters:
         - $ref: '#/components/parameters/cat.indices::path.index'
         - $ref: '#/components/parameters/cat.indices::query.format'
@@ -429,6 +439,8 @@ paths:
       x-operation-group: cat.recovery
       x-version-added: '1.0'
       description: Returns information about index shard recoveries, both on-going completed.
+      externalDocs:
+        url: https://opensearch.org/docs/latest/api-reference/cat/cat-plugins/
       parameters:
         - $ref: '#/components/parameters/cat.recovery::path.index'
         - $ref: '#/components/parameters/cat.recovery::query.format'
@@ -499,6 +511,8 @@ paths:
       x-operation-group: cat.segment_replication
       x-version-added: 2.6.0
       description: Returns information about both on-going and latest completed Segment Replication events.
+      externalDocs:
+        url: https://opensearch.org/docs/latest/api-reference/cat/cat-segment-replication/
       parameters:
         - $ref: '#/components/parameters/cat.segment_replication::path.index'
         - $ref: '#/components/parameters/cat.segment_replication::query.format'
@@ -547,6 +561,8 @@ paths:
       x-operation-group: cat.segments
       x-version-added: '1.0'
       description: Provides low-level information about the segments in the shards of an index.
+      externalDocs:
+        url: https://opensearch.org/docs/latest/api-reference/cat/cat-segments/
       parameters:
         - $ref: '#/components/parameters/cat.segments::path.index'
         - $ref: '#/components/parameters/cat.segments::query.format'
@@ -588,6 +604,8 @@ paths:
       x-operation-group: cat.shards
       x-version-added: '1.0'
       description: Provides a detailed view of shard allocation on nodes.
+      externalDocs:
+        url: https://opensearch.org/docs/latest/api-reference/cat/cat-shards/
       parameters:
         - $ref: '#/components/parameters/cat.shards::path.index'
         - $ref: '#/components/parameters/cat.shards::query.format'
@@ -630,6 +648,8 @@ paths:
       x-operation-group: cat.snapshots
       x-version-added: '1.0'
       description: Returns all snapshots in a specific repository.
+      externalDocs:
+        url: https://opensearch.org/docs/latest/api-reference/cat/cat-snapshots/
       parameters:
         - $ref: '#/components/parameters/cat.snapshots::path.repository'
         - $ref: '#/components/parameters/cat.snapshots::query.format'
@@ -692,6 +712,8 @@ paths:
       x-operation-group: cat.templates
       x-version-added: '1.0'
       description: Returns information about existing templates.
+      externalDocs:
+        url: https://opensearch.org/docs/latest/api-reference/cat/cat-templates/
       parameters:
         - $ref: '#/components/parameters/cat.templates::path.name'
         - $ref: '#/components/parameters/cat.templates::query.format'
@@ -736,6 +758,8 @@ paths:
       description: |-
         Returns cluster-wide thread pool statistics per node.
         By default the active, queue and rejected statistics are returned for all thread pools.
+      externalDocs:
+        url: https://opensearch.org/docs/latest/api-reference/cat/cat-thread-pool/
       parameters:
         - $ref: '#/components/parameters/cat.thread_pool::path.thread_pool_patterns'
         - $ref: '#/components/parameters/cat.thread_pool::query.format'

spec/namespaces/cluster.yaml

@@ -25,6 +25,8 @@ paths:
       x-operation-group: cluster.allocation_explain
       x-version-added: '1.0'
       description: Provides explanations for shard allocations in the cluster.
+      externalDocs:
+        url: https://opensearch.org/docs/latest/api-reference/cluster-api/cluster-allocation/
       parameters:
         - $ref: '#/components/parameters/cluster.allocation_explain::query.include_yes_decisions'
         - $ref: '#/components/parameters/cluster.allocation_explain::query.include_disk_info'
@@ -102,6 +104,8 @@ paths:
       x-operation-group: cluster.health
       x-version-added: '1.0'
       description: Returns basic information about the health of the cluster.
+      externalDocs:
+        url: https://opensearch.org/docs/latest/api-reference/cluster-api/cluster-health/
       parameters:
         - $ref: '#/components/parameters/cluster.health::path.index'
         - $ref: '#/components/parameters/cluster.health::query.expand_wildcards'
@@ -255,6 +259,8 @@ paths:
       x-operation-group: cluster.state
       x-version-added: '1.0'
       description: Returns a comprehensive information about the state of the cluster.
+      externalDocs:
+        url: https://opensearch.org/docs/latest
       parameters:
         - $ref: '#/components/parameters/cluster.state::path.metric'
         - $ref: '#/components/parameters/cluster.state::query.local'
@@ -275,6 +281,8 @@ paths:
       x-operation-group: cluster.state
       x-version-added: '1.0'
       description: Returns a comprehensive information about the state of the cluster.
+      externalDocs:
+        url: https://opensearch.org/docs/latest
       parameters:
         - $ref: '#/components/parameters/cluster.state::path.index'
         - $ref: '#/components/parameters/cluster.state::path.metric'
@@ -310,6 +318,8 @@ paths:
       x-operation-group: cluster.stats
       x-version-added: '1.0'
       description: Returns high-level overview of cluster statistics.
+      externalDocs:
+        url: https://opensearch.org/docs/latest/api-reference/cluster-api/cluster-stats/
       parameters:
         - $ref: '#/components/parameters/cluster.stats::path.node_id'
         - $ref: '#/components/parameters/cluster.stats::query.flat_settings'
@@ -380,6 +390,8 @@ paths:
       x-operation-group: cluster.get_component_template
       x-version-added: '1.0'
       description: Returns one or more component templates.
+      externalDocs:
+        url: https://opensearch.org/docs/latest
       parameters:
         - $ref: '#/components/parameters/cluster.get_component_template::path.name'
         - $ref: '#/components/parameters/cluster.get_component_template::query.master_timeout'
@@ -408,6 +420,8 @@ paths:
       x-operation-group: cluster.put_component_template
       x-version-added: '1.0'
       description: Creates or updates a component template.
+      externalDocs:
+        url: https://opensearch.org/docs/latest/im-plugin/index-templates/#use-component-templates-to-create-an-index-template
       parameters:
         - $ref: '#/components/parameters/cluster.put_component_template::path.name'
         - $ref: '#/components/parameters/cluster.put_component_template::query.create'