HYPERFLEET-1083 - feat: add Channel and Version TypeSpec models

rafabene · rafabene · commit 1d0afcf30557 · 2026-05-18T16:15:39.000-03:00
Define Channel and Version resources in the API spec with full CRUD
services, following the spec-as-JSONB pattern. Channels organize OCP
release versions; Versions are nested under their parent Channel.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.15] - 2026-05-18
+
+### Added
+
+- Channel resource model with `ChannelSpec` (`is_default`, `enabled_regex`) and full CRUD service at `/channels` (HYPERFLEET-1083)
+- Version resource model with `VersionSpec` (`raw_version`, `enabled`, `default`, `release_image`, `end_of_life_time`) and full CRUD service nested at `/channels/{channel_id}/versions` (HYPERFLEET-1083)
+- `owner_references` on Version pointing to parent Channel
+- Examples for both Channel and Version resources (create, patch, response)
+
 ## [1.0.14] - 2026-05-15
 
 ### Removed
@@ -138,7 +147,8 @@ First official stable release of the HyperFleet API specification.
 - Interactive API documentation
 
 <!-- Links -->
-[Unreleased]: https://github.com/openshift-hyperfleet/hyperfleet-api-spec/compare/v1.0.14...HEAD
+[Unreleased]: https://github.com/openshift-hyperfleet/hyperfleet-api-spec/compare/v1.0.15...HEAD
+[1.0.15]: https://github.com/openshift-hyperfleet/hyperfleet-api-spec/compare/v1.0.14...v1.0.15
 [1.0.14]: https://github.com/openshift-hyperfleet/hyperfleet-api-spec/compare/v1.0.13...v1.0.14
 [1.0.13]: https://github.com/openshift-hyperfleet/hyperfleet-api-spec/compare/v1.0.12...v1.0.13
 [1.0.12]: https://github.com/openshift-hyperfleet/hyperfleet-api-spec/compare/v1.0.11...v1.0.12
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -212,6 +212,15 @@ Before submitting changes:
 - [ ] Changes committed including schema updates
 - [ ] PR description references related issue
 
+## Node.js Version
+
+CI uses **Node.js 20** (see `.github/workflows/ci.yml`). The `api-spec-converter` (Swagger 2.0 generation) is incompatible with Node.js 25+. If local Swagger builds fail, use Node 20 or build via Docker:
+
+```bash
+docker run --rm -v "$(pwd):/app" -w /app node:20-slim bash -c \
+  "npm install && ./build-schema.sh core --swagger && ./build-schema.sh gcp --swagger"
+```
+
 ## Build System Details
 
 **The build-schema.sh script:**
diff --git a/aliases-core.tsp b/aliases-core.tsp
@@ -6,4 +6,12 @@ import "./models-core/nodepool/model.tsp";
 import "./models-core/nodepool/example_nodepool.tsp";
 import "./models-core/nodepool/example_post.tsp";
 import "./models-core/nodepool/example_patch.tsp";
+import "./models-core/channel/model.tsp";
+import "./models-core/channel/example_channel.tsp";
+import "./models-core/channel/example_post.tsp";
+import "./models-core/channel/example_patch.tsp";
+import "./models-core/version/model.tsp";
+import "./models-core/version/example_version.tsp";
+import "./models-core/version/example_post.tsp";
+import "./models-core/version/example_patch.tsp";
 import "./services/statuses-internal.tsp";
diff --git a/aliases-gcp.tsp b/aliases-gcp.tsp
@@ -6,3 +6,11 @@ import "./models-gcp/nodepool/model.tsp";
 import "./models-gcp/nodepool/example_nodepool.tsp";
 import "./models-gcp/nodepool/example_post.tsp";
 import "./models-gcp/nodepool/example_patch.tsp";
+import "./models-core/channel/model.tsp";
+import "./models-core/channel/example_channel.tsp";
+import "./models-core/channel/example_post.tsp";
+import "./models-core/channel/example_patch.tsp";
+import "./models-core/version/model.tsp";
+import "./models-core/version/example_version.tsp";
+import "./models-core/version/example_post.tsp";
+import "./models-core/version/example_patch.tsp";
diff --git a/aliases.tsp b/aliases.tsp
@@ -1 +1 @@
-aliases-gcp.tsp
+aliases-core.tsp
diff --git a/main.tsp b/main.tsp
@@ -5,6 +5,8 @@ import "@typespec/openapi3";
 import "./services/clusters.tsp";
 import "./services/statuses.tsp";
 import "./services/nodepools.tsp";
+import "./services/channels.tsp";
+import "./services/versions.tsp";
 // Provider-specific security is imported via aliases.tsp
 import "./aliases.tsp";
 
@@ -21,7 +23,7 @@ using OpenAPI;
  */
 @service(#{ title: "HyperFleet API" })
 @info(#{
-  version: "1.0.14",
+  version: "1.0.15",
   contact: #{
     name: "HyperFleet Team",
     url: "https://github.com/openshift-hyperfleet",
diff --git a/models-core/channel/example_channel.tsp b/models-core/channel/example_channel.tsp
@@ -0,0 +1,39 @@
+import "./model.tsp";
+import "../../models/channels/model.tsp";
+import "../../models/common/model.tsp";
+
+const exampleChannel: Channel = #{
+  kind: "Channel",
+  id: "019466a2-1234-7abc-9def-0123456789ab",
+  href: "https://api.hyperfleet.com/v1/channels/019466a2-1234-7abc-9def-0123456789ab",
+  name: "stable",
+  labels: #{ tier: "production" },
+  spec: #{
+    is_default: true,
+    enabled_regex: "^4\\.\\d+\\.\\d+$",
+  },
+  generation: 1,
+  created_time: "2021-01-01T00:00:00Z",
+  updated_time: "2021-01-01T10:02:00Z",
+  created_by: "user-123@example.com",
+  updated_by: "user-123@example.com",
+};
+
+const exampleDeletedChannel: Channel = #{
+  kind: "Channel",
+  id: "019466a2-1234-7abc-9def-0123456789ab",
+  href: "https://api.hyperfleet.com/v1/channels/019466a2-1234-7abc-9def-0123456789ab",
+  name: "stable",
+  labels: #{ tier: "production" },
+  spec: #{
+    is_default: true,
+    enabled_regex: "^4\\.\\d+\\.\\d+$",
+  },
+  generation: 2,
+  created_time: "2021-01-01T00:00:00Z",
+  updated_time: "2021-01-01T10:02:00Z",
+  deleted_time: "2021-01-01T10:05:00Z",
+  created_by: "user-123@example.com",
+  updated_by: "user-123@example.com",
+  deleted_by: "user-123@example.com",
+};
diff --git a/models-core/channel/example_patch.tsp b/models-core/channel/example_patch.tsp
@@ -0,0 +1,10 @@
+import "./model.tsp";
+import "../../models/channels/model.tsp";
+
+const exampleChannelPatchRequest: ChannelPatchRequest = #{
+  spec: #{
+    is_default: false,
+    enabled_regex: "^4\\.17\\.\\d+$",
+  },
+  labels: #{ tier: "staging" },
+};
diff --git a/models-core/channel/example_post.tsp b/models-core/channel/example_post.tsp
@@ -0,0 +1,12 @@
+import "./model.tsp";
+import "../../models/channels/model.tsp";
+
+const exampleChannelCreateRequest: ChannelCreateRequest = #{
+  kind: "Channel",
+  name: "stable",
+  labels: #{ tier: "production" },
+  spec: #{
+    is_default: true,
+    enabled_regex: "^4\\.\\d+\\.\\d+$",
+  },
+};
diff --git a/models-core/channel/model.tsp b/models-core/channel/model.tsp
@@ -0,0 +1,7 @@
+model ChannelSpec {
+  /** Whether this is the default channel */
+  is_default: boolean;
+
+  /** Regex pattern for matching enabled versions */
+  enabled_regex: string;
+}
diff --git a/models-core/version/example_patch.tsp b/models-core/version/example_patch.tsp
@@ -0,0 +1,12 @@
+import "./model.tsp";
+import "../../models/versions/model.tsp";
+
+const exampleVersionPatchRequest: VersionPatchRequest = #{
+  spec: #{
+    raw_version: "4.17.12",
+    enabled: false,
+    default: false,
+    release_image: "quay.io/openshift-release-dev/ocp-release:4.17.12-multi",
+  },
+  labels: #{ deprecated: "true" },
+};
diff --git a/models-core/version/example_post.tsp b/models-core/version/example_post.tsp
@@ -0,0 +1,14 @@
+import "./model.tsp";
+import "../../models/versions/model.tsp";
+
+const exampleVersionCreateRequest: VersionCreateRequest = #{
+  kind: "Version",
+  name: "4.17.12",
+  labels: #{},
+  spec: #{
+    raw_version: "4.17.12",
+    enabled: true,
+    default: true,
+    release_image: "quay.io/openshift-release-dev/ocp-release:4.17.12-multi",
+  },
+};
diff --git a/models-core/version/example_version.tsp b/models-core/version/example_version.tsp
@@ -0,0 +1,53 @@
+import "./model.tsp";
+import "../../models/versions/model.tsp";
+import "../../models/common/model.tsp";
+
+const exampleVersion: Version = #{
+  kind: "Version",
+  id: "019466a3-5678-7abc-9def-0123456789ab",
+  href: "https://api.hyperfleet.com/v1/channels/019466a2-1234-7abc-9def-0123456789ab/versions/019466a3-5678-7abc-9def-0123456789ab",
+  name: "4.17.12",
+  labels: #{},
+  spec: #{
+    raw_version: "4.17.12",
+    enabled: true,
+    default: true,
+    release_image: "quay.io/openshift-release-dev/ocp-release:4.17.12-multi",
+  },
+  generation: 1,
+  owner_references: #{
+    id: "019466a2-1234-7abc-9def-0123456789ab",
+    kind: "Channel",
+    href: "https://api.hyperfleet.com/v1/channels/019466a2-1234-7abc-9def-0123456789ab",
+  },
+  created_time: "2021-01-01T00:00:00Z",
+  updated_time: "2021-01-01T10:02:00Z",
+  created_by: "user-123@example.com",
+  updated_by: "user-123@example.com",
+};
+
+const exampleDeletedVersion: Version = #{
+  kind: "Version",
+  id: "019466a3-5678-7abc-9def-0123456789ab",
+  href: "https://api.hyperfleet.com/v1/channels/019466a2-1234-7abc-9def-0123456789ab/versions/019466a3-5678-7abc-9def-0123456789ab",
+  name: "4.17.12",
+  labels: #{},
+  spec: #{
+    raw_version: "4.17.12",
+    enabled: true,
+    default: true,
+    release_image: "quay.io/openshift-release-dev/ocp-release:4.17.12-multi",
+  },
+  generation: 2,
+  owner_references: #{
+    id: "019466a2-1234-7abc-9def-0123456789ab",
+    kind: "Channel",
+    href: "https://api.hyperfleet.com/v1/channels/019466a2-1234-7abc-9def-0123456789ab",
+  },
+  created_time: "2021-01-01T00:00:00Z",
+  updated_time: "2021-01-01T10:02:00Z",
+  deleted_time: "2021-01-01T10:05:00Z",
+  created_by: "user-123@example.com",
+  updated_by: "user-123@example.com",
+  deleted_by: "user-123@example.com",
+};
diff --git a/models-core/version/model.tsp b/models-core/version/model.tsp
@@ -0,0 +1,20 @@
+import "@typespec/http";
+
+using Http;
+
+model VersionSpec {
+  /** Raw version string (e.g., "4.17.12") */
+  raw_version: string;
+
+  /** Whether this version is enabled for provisioning */
+  enabled: boolean;
+
+  /** Whether this is the default version for its channel */
+  default: boolean;
+
+  /** Container image reference for the release */
+  release_image: string;
+
+  /** When this version reaches end of life */
+  @format("date-time") end_of_life_time?: string;
+}
diff --git a/models/channels/model.tsp b/models/channels/model.tsp
@@ -0,0 +1,48 @@
+import "@typespec/openapi";
+import "../common/model.tsp";
+import "../../aliases.tsp";
+
+using OpenAPI;
+
+model ChannelBase {
+  ...APIResource;
+
+  /**
+   * Channel name (unique)
+   */
+  @minLength(3)
+  @maxLength(53)
+  @pattern("^[a-z0-9]([-a-z0-9]*[a-z0-9])?$")
+  name: string;
+
+  spec: ChannelSpec;
+}
+
+@example(exampleChannel)
+model Channel {
+  ...ChannelBase;
+  ...APIMetadata;
+
+  /**
+   * Generation field is updated on customer updates, reflecting the version of the "intent" of the customer
+   */
+  @minValue(1)
+  generation: int32;
+}
+
+@example(exampleChannelCreateRequest)
+model ChannelCreateRequest {
+  ...ChannelBase;
+}
+
+@extension("minProperties", 1)
+@extension("additionalProperties", false)
+@example(exampleChannelPatchRequest)
+model ChannelPatchRequest {
+  spec?: ChannelSpec;
+  labels?: Record<string>;
+}
+
+model ChannelList {
+  ...List<Channel>;
+}
diff --git a/models/common/model.tsp b/models/common/model.tsp
@@ -10,6 +10,8 @@ alias KindCluster = "Cluster";
 alias KindClusterStatus = "ClusterStatus";
 alias KindNodePoolStatus = "NodePoolStatus";
 alias KindNodePool = "NodePool";
+alias KindChannel = "Channel";
+alias KindVersion = "Version";
 
 model ID {
     /** Resource identifier */
@@ -145,7 +147,7 @@ enum OrderDirection {
 
 model SearchParams {
     /** Filter results using TSL (Tree Search Language) query syntax.
-     * Examples: `status.conditions.Reconciled='True'`, `name in ('c1','c2')`, `labels.region='us-east'` */
+     * Examples: `name in ('c1','c2')`, `labels.region='us-east'` */
     @query
     search?: string;
 }
diff --git a/models/versions/model.tsp b/models/versions/model.tsp
@@ -0,0 +1,49 @@
+import "@typespec/openapi";
+import "../common/model.tsp";
+import "../../aliases.tsp";
+
+using OpenAPI;
+
+model VersionBase {
+  ...APIResource;
+
+  /**
+   * Version name (unique within a channel, e.g., "4.17.12")
+   */
+  @minLength(1)
+  @maxLength(63)
+  name: string;
+
+  spec: VersionSpec;
+}
+
+@example(exampleVersion)
+model Version {
+  ...VersionBase;
+  ...APIMetadata;
+
+  /**
+   * Generation field is updated on customer updates, reflecting the version of the "intent" of the customer
+   */
+  @minValue(1)
+  generation: int32;
+
+  owner_references: ObjectReference;
+}
+
+@example(exampleVersionCreateRequest)
+model VersionCreateRequest {
+  ...VersionBase;
+}
+
+@extension("minProperties", 1)
+@extension("additionalProperties", false)
+@example(exampleVersionPatchRequest)
+model VersionPatchRequest {
+  spec?: VersionSpec;
+  labels?: Record<string>;
+}
+
+model VersionList {
+  ...List<Version>;
+}
diff --git a/schemas/core/openapi.yaml b/schemas/core/openapi.yaml
diff --git a/schemas/core/swagger.yaml b/schemas/core/swagger.yaml
diff --git a/schemas/gcp/openapi.yaml b/schemas/gcp/openapi.yaml
diff --git a/schemas/gcp/swagger.yaml b/schemas/gcp/swagger.yaml
diff --git a/services/channels.tsp b/services/channels.tsp
diff --git a/services/versions.tsp b/services/versions.tsp
