feat: standardize TypeSpec schema definitions with enums and validation enhancements

[yasun1]

Summary

This PR standardizes the TypeSpec schema definitions to improve type safety and align with OpenAPI validation
requirements.

Changes

Type Safety Improvements

• Added ResourcePhase enum: Defines cluster/nodepool phases (NotReady, Ready, Failed)
• Added ConditionStatus enum: Defines condition status values (True, False, Unknown)
• Updated all models and examples to use enum references instead of string literals

Validation Enhancements

• Error model: Added details array field for field-level validation errors with field path and error message
• Enables more precise error reporting for spec validation failures

OpenAPI Compatibility

• BearerAuth fix: Changed authentication scheme from "Bearer" to lowercase "bearer" to comply with kin-openapi
  library requirements
• Added custom BearerAuth model override in main.tsp

Schema Cleanup

• Removed hardcoded kind field from AdapterStatusList to follow List pattern
• Removed default value from QueryParams.order for consistency

Generated Schemas

• Regenerated both schemas/core/openapi.yaml and schemas/gcp/openapi.yaml with all updates
• Verified schemas are functionally consistent with validation requirements

Impact

• Improved type safety in TypeSpec definitions
• Better validation error reporting for API consumers
• Fixed authentication scheme compatibility issue

Summary by CodeRabbit

• New Features

  • Added bearer token (lowercase "bearer") authentication support
  • Enhanced error responses with field-level validation details

• Refactor

  • Standardized status/condition fields to shared typed enums (ResourcePhase, ConditionStatus)

• API Changes

  • Condition entries now include timestamps (created/updated/transition)
  • Removed redundant "kind" field from status list responses
  • Query ordering no longer defaults to "desc"

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Caution

Review failed

The pull request is closed.

Walkthrough

This PR standardizes status enums and normalizes the HTTP bearer auth scheme across schemas and examples. It adds public enums ResourcePhase (NotReady, Ready, Failed) and ConditionStatus (True, False, Unknown); replaces inline string literals with these types in ClusterStatus, NodePoolStatus, ConditionBase, and ConditionRequest; adds Error.details for field-level validation errors; removes the kind field from AdapterStatusList; adds a BearerAuth security schema using scheme "bearer" (lowercase); and removes the default for QueryParams.order. Example data were updated to use the new enums and revised health messages.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45–60 minutes

• Public API signature changes: ClusterStatus.phase, NodePoolStatus.phase -> ResourcePhase; ConditionBase.status, ConditionRequest.status -> ConditionStatus
• OpenAPI schema cross-references: verify allOf/$ref usages for ResourcePhase and ConditionStatus resolve and preserve validation
• Authentication scheme normalization: confirm BearerAuth with scheme "bearer" integrates with tooling that expects lowercase
• Example and consumer impact: ensure example updates match runtime expectations and downstream clients that consume enum values
• AdapterStatusList change: validate removal of kind does not break consumers relying on that discriminator

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately captures the main objectives of the PR: standardizing schema definitions with enums for type safety and adding validation enhancements for error reporting.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 997f354 and 255d9d0.

📒 Files selected for processing (13)

• main.tsp (1 hunks)
• models-core/cluster/example_cluster.tsp (2 hunks)
• models-core/nodepool/example_nodepool.tsp (2 hunks)
• models-gcp/cluster/example_cluster.tsp (2 hunks)
• models-gcp/nodepool/example_nodepool.tsp (2 hunks)
• models/clusters/model.tsp (1 hunks)
• models/common/model.tsp (3 hunks)
• models/nodepools/model.tsp (1 hunks)
• models/statuses/example_adapter_status.tsp (4 hunks)
• models/statuses/model.tsp (3 hunks)
• schemas/core/openapi.yaml (7 hunks)
• schemas/gcp/openapi.yaml (8 hunks)
• services/compatibility.tsp (1 hunks)

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (6)

models/common/model.tsp (1)

60-66: Consider tightening the Error.details element shape

field and error are both optional; if your validation pipeline always produces an error message (and usually a field path), making at least error required would strengthen the schema and improve client expectations. If you need flexibility for non-field-scoped errors, the current shape is fine.

models/statuses/model.tsp (1)

4-11: Enum-ifying condition status is aligned; consider making Unknown explicit

Using ConditionStatus instead of raw string unions is a nice improvement. For readability and future‑proofing, you might optionally declare Unknown: "Unknown" as well so all members have explicit string values, mirroring the previous wire contract.

schemas/core/openapi.yaml (2)

612-625: Clarify the purpose of the BearerAuth object schema.

This BearerAuth object schema is separate from the securitySchemes.BearerAuth at line 1198. Consider adding a description to clarify its purpose (e.g., for validation, documentation, or internal use), as having both a schema and a security scheme with the same name could cause confusion for API consumers.

---

863-874: Consider making field and error required within detail items.

The details array items have both field and error as optional properties. For better API consistency and client usability, consider making them required — an error detail without specifying which field failed or what the error message is provides limited value.

         details:
           type: array
           items:
             type: object
+            required:
+              - field
+              - error
             properties:
               field:
                 type: string
                 description: Field path that failed validation
               error:
                 type: string
                 description: Validation error message for this field
           description: Field-level validation errors (optional)

schemas/gcp/openapi.yaml (2)

646-659: Same observation as core schema: clarify BearerAuth object purpose.

This BearerAuth object schema mirrors the one in schemas/core/openapi.yaml. Same suggestion applies — consider adding a description to distinguish it from the security scheme.

---

941-952: Same recommendation: consider requiring field and error in detail items.

For consistency with the core schema recommendation, consider making field and error required within each error detail item.

         details:
           type: array
           items:
             type: object
+            required:
+              - field
+              - error
             properties:
               field:
                 type: string
                 description: Field path that failed validation
               error:
                 type: string
                 description: Validation error message for this field
           description: Field-level validation errors (optional)

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 454a38d and 997f354.

📒 Files selected for processing (13)

• main.tsp (1 hunks)
• models-core/cluster/example_cluster.tsp (2 hunks)
• models-core/nodepool/example_nodepool.tsp (2 hunks)
• models-gcp/cluster/example_cluster.tsp (2 hunks)
• models-gcp/nodepool/example_nodepool.tsp (2 hunks)
• models/clusters/model.tsp (1 hunks)
• models/common/model.tsp (3 hunks)
• models/nodepools/model.tsp (1 hunks)
• models/statuses/example_adapter_status.tsp (4 hunks)
• models/statuses/model.tsp (3 hunks)
• schemas/core/openapi.yaml (9 hunks)
• schemas/gcp/openapi.yaml (10 hunks)
• services/compatibility.tsp (1 hunks)

🔇 Additional comments (24)

models/common/model.tsp (2)

13-20: Centralizing ResourcePhase as an enum looks good

The enum cleanly captures the three lifecycle phases and removes scattered string literals; this should make downstream status models and examples safer and more consistent.

---

114-114: Double‑check behavior changes from removing the order default

Dropping the OrderDirection.desc default means generated clients and documentation will no longer advertise/supply a default sort order. If the backend still assumes desc when order is omitted, that’s OK, but please confirm consumers aren’t relying on the explicit default in the schema.

models/statuses/model.tsp (1)

25-25: Shared ConditionStatus type for condition/status requests looks consistent

Wiring both ConditionBase.status and ConditionRequest.status through the same ConditionStatus enum keeps adapters, status computation, and schemas in sync and reduces the chance of drift between request and stored status values.

Also applies to: 84-84

models-core/cluster/example_cluster.tsp (1)

15-15: Examples now correctly use the new enums

Using ResourcePhase.Ready for phase and ConditionStatus.True for condition statuses keeps this example in lockstep with the updated model typings and OpenAPI enums.

Also applies to: 22-22, 32-32

models-core/nodepool/example_nodepool.tsp (1)

21-21: Enum usage in nodepool example matches the updated status models

ResourcePhase.Ready and ConditionStatus.True are correctly referenced here, so the example will validate against the new NodePoolStatus and ConditionStatus definitions.

Also applies to: 28-28, 38-38

services/compatibility.tsp (1)

20-20: Explicitly targeting HyperFleet.BearerAuth is appropriate; confirm all callers are migrated

Qualifying @useAuth with HyperFleet.BearerAuth correctly ties this operation to your custom lowercase‑bearer scheme instead of the library’s default. Please also confirm that any other operations meant to use the same scheme have been updated to reference HyperFleet.BearerAuth so security is consistent across the API surface and matches the regenerated OpenAPI.

models-gcp/cluster/example_cluster.tsp (1)

37-37: GCP cluster example correctly adopts ResourcePhase and ConditionStatus

Using ResourcePhase.Ready and ConditionStatus.True here keeps the GCP example in sync with the shared core status abstractions and regenerated OpenAPI schemas.

Also applies to: 44-44, 54-54

main.tsp (1)

26-30: Custom BearerAuth override is shaped correctly; validate emitter output

Defining HyperFleet.BearerAuth with type: AuthType.http and scheme: "bearer" matches the expected custom HTTP auth scheme shape and should give kin-openapi the lowercase scheme it needs. Please confirm:

• AuthType resolves from the HTTP library in this file (via using Http;), and
• The generated OpenAPI components.securitySchemes now emit scheme: bearer everywhere you expect.

models/nodepools/model.tsp (1)

30-30: Using ResourcePhase for NodePoolStatus.phase improves consistency

Switching phase to the shared ResourcePhase enum de‑duplicates the phase definition and keeps nodepool and cluster statuses aligned. Just make sure any persistence/serialization logic still expects the same underlying values when reading/writing this column.

models/clusters/model.tsp (1)

37-37: Good use of shared enum type for phase.

Using ResourcePhase instead of inline string literals improves type safety and ensures consistency across ClusterStatus and NodePoolStatus definitions.

models/statuses/example_adapter_status.tsp (3)

10-10: Consistent enum usage across all example adapter statuses.

All occurrences of status: "True" are correctly replaced with ConditionStatus.True. The updated Health condition messages ("All adapter operations completed successfully") are more generic and appropriate for a reusable example.

Also applies to: 17-17, 24-27

---

57-57: Consistent with the first example object.

The exampleAdapterStatusCreateRequest correctly mirrors the enum usage pattern.

Also applies to: 63-63, 69-71

---

104-104: List example correctly updated.

The exampleAdapterStatusList items use ConditionStatus.True consistently.

Also applies to: 123-123

schemas/core/openapi.yaml (7)

756-761: Correct use of allOf for enum reference with description.

Using allOf with $ref to ResourcePhase while preserving the field description is the idiomatic OpenAPI 3.0 pattern for this use case.

---

839-845: ConditionStatus enum follows Kubernetes conventions.

The quoted string values 'True', 'False', and Unknown correctly match the Kubernetes condition status convention.

---

1190-1196: ResourcePhase enum properly defined.

The enum values NotReady, Ready, and Failed with the description provide clear semantics for resource lifecycle phases.

---

806-808: Consistent enum references for condition status fields.

Both ConditionBase.status and ConditionRequest.status correctly reference the shared ConditionStatus enum.

Also applies to: 831-831

---

1197-1200: Correct: lowercase bearer for OpenAPI validator compatibility.

The change to lowercase bearer aligns with kin-openapi requirements. While RFC 7235 treats scheme names as case-insensitive, using lowercase ensures broader compatibility with OpenAPI tooling.

---

469-470: Example messages updated consistently.

The Health condition messages in examples are now more generic and align with the TypeSpec example updates.

Also applies to: 557-558

---

1110-1115: Consistent with ClusterStatus.phase pattern.

NodePoolStatus.phase correctly uses the same allOf pattern to reference ResourcePhase.

schemas/gcp/openapi.yaml (3)

829-830: ConditionStatus and ResourcePhase references correctly applied.

All status/phase fields properly reference the shared enum types, consistent with the core schema.

Also applies to: 879-880, 904-904, 912-918

---

1315-1316: GCP schema changes are consistent with core schema.

The ResourcePhase enum, NodePoolStatus.phase reference, and lowercase bearer security scheme are all correctly synchronized with schemas/core/openapi.yaml.

Also applies to: 1414-1420, 1437-1440

---

480-481: Example message updates consistent with core schema.

Health condition messages updated to match the core schema and TypeSpec examples.

Also applies to: 568-569

models-gcp/nodepool/example_nodepool.tsp (1)

43-43: Ensure ResourcePhase and ConditionStatus enums are accessible through imports.

The changes correctly use ResourcePhase.Ready and ConditionStatus.True enums instead of string literals. Verify that both ResourcePhase and ConditionStatus are properly exported from their respective definition modules and accessible through the import chain from models/nodepools/model.tsp.

Applies to lines: 43, 50, 60

[rh-amarin]

/lgtm