HYPERFLEET-452 - feat: implement RFC 9457 Problem Details error model

main.tsp

@@ -20,7 +20,7 @@ using OpenAPI;
  *
  */
 @service(#{ title: "HyperFleet API" })
-@info(#{ version: "1.0.2", contact: #{ name: "HyperFleet Team" }, license: #{ name: "Apache 2.0" ,url: "https://www.apache.org/licenses/LICENSE-2.0"} })
+@info(#{ version: "1.0.3", contact: #{ name: "HyperFleet Team" }, license: #{ name: "Apache 2.0" ,url: "https://www.apache.org/licenses/LICENSE-2.0"} })
 @server("https://hyperfleet.redhat.com", "Production")
 @route("/api/hyperfleet/v1")
 namespace HyperFleet;

models/common/model.tsp

@@ -43,32 +43,88 @@ model ObjectReference2<Kind> {
     href: string;
 }
 
+/**
+ * Validation constraint types for field-level errors
+ */
+enum ValidationConstraint {
+    required: "required",
+    min: "min",
+    max: "max",
+    min_length: "min_length",
+    max_length: "max_length",
+    pattern_match: "pattern",
+    enum_value: "enum",
+    format_check: "format",
+    unique: "unique",
+}
+
+/**
+ * Field-level validation error detail (RFC 9457 extension)
+ */
+model ValidationError {
+    /** JSON path to the field that failed validation */
+    @example("spec.name")
+    field: string;
+
+    /** The invalid value that was provided (if safe to include) */
+    value?: unknown;
+
+    /** The validation constraint that was violated */
+    constraint?: ValidationConstraint;
+
+    /** Human-readable error message for this field */
+    @example("Cluster name is required")
+    message: string;
+}
+
+/**
+ * RFC 9457 Problem Details error format with HyperFleet extensions
+ */
 @defaultResponse
 model Error {
-    id?: string;
+    @header contentType: "application/problem+json";
+    /** URI reference identifying the problem type */
+    @format("uri")
+    @example("https://api.hyperfleet.io/errors/validation-error")
+    type: string;
+
+    /** Short human-readable summary of the problem */
+    @example("Validation Failed")
+    title: string;
+
+    /** HTTP status code */
+    @example(400)
+    status: int32;
+
+    /** Human-readable explanation specific to this occurrence */
+    @example("The cluster name field is required")
+    detail?: string;
+
+    /** URI reference for this specific occurrence */
+    @format("uri")
+    @example("/api/hyperfleet/v1/clusters")
+    instance?: string;
+
+    /** Machine-readable error code in HYPERFLEET-CAT-NUM format */
+    @example("HYPERFLEET-VAL-001")
+    code?: string;
 
-    /** Resource kind */
-    kind?: string;
+    /** RFC3339 timestamp of when the error occurred */
+    @format("date-time")
+    @example("2024-01-15T10:30:00Z")
+    timestamp?: string;
 
-    /** Resource URI */
-    href?: string;
+    /** Distributed trace ID for correlation */
+    @example("abc123def456")
+    trace_id?: string;
 
-    code?: string;
-    reason?: string;
-    operation_id?: string;
-
-    /** Field-level validation errors (optional) */
-    details?: {
-        /** Field path that failed validation */
-        field?: string;
-        /** Validation error message for this field */
-        error?: string;
-    }[];
+    /** Field-level validation errors (for validation failures) */
+    errors?: ValidationError[];
 }
 
-model ErrorResponse<Kind, ErrorCode> {
-    kind: Kind;
+model ErrorResponse<ErrorCode> {
     @statusCode statusCode: ErrorCode;
+    @header contentType: "application/problem+json";
     @body error: Error;
 }
 

schemas/core/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.0
 info:
   title: HyperFleet API
-  version: 1.0.2
+  version: 1.0.3
   contact:
     name: HyperFleet Team
   license:
@@ -37,7 +37,7 @@ paths:
         default:
           description: An unexpected error response.
           content:
-            application/json:
+            application/problem+json:
               schema:
                 $ref: '#/components/schemas/Error'
       security:
@@ -64,7 +64,7 @@ paths:
         default:
           description: An unexpected error response.
           content:
-            application/json:
+            application/problem+json:
               schema:
                 $ref: '#/components/schemas/Error'
       requestBody:
@@ -98,7 +98,7 @@ paths:
         default:
           description: An unexpected error response.
           content:
-            application/json:
+            application/problem+json:
               schema:
                 $ref: '#/components/schemas/Error'
       security:
@@ -132,7 +132,7 @@ paths:
         default:
           description: An unexpected error response.
           content:
-            application/json:
+            application/problem+json:
               schema:
                 $ref: '#/components/schemas/Error'
       security:
@@ -160,7 +160,7 @@ paths:
         default:
           description: An unexpected error response.
           content:
-            application/json:
+            application/problem+json:
               schema:
                 $ref: '#/components/schemas/Error'
       requestBody:
@@ -201,7 +201,7 @@ paths:
         default:
           description: An unexpected error response.
           content:
-            application/json:
+            application/problem+json:
               schema:
                 $ref: '#/components/schemas/Error'
       security:
@@ -280,7 +280,7 @@ paths:
         default:
           description: An unexpected error response.
           content:
-            application/json:
+            application/problem+json:
               schema:
                 $ref: '#/components/schemas/Error'
   /api/hyperfleet/v1/clusters/{cluster_id}/statuses:
@@ -373,7 +373,7 @@ paths:
         default:
           description: An unexpected error response.
           content:
-            application/json:
+            application/problem+json:
               schema:
                 $ref: '#/components/schemas/Error'
       security:
@@ -916,33 +916,53 @@ components:
       description: Status value for conditions
     Error:
       type: object
+      required:
+        - type
+        - title
+        - status
       properties:
-        id:
+        type:
           type: string
-        kind:
+          format: uri
+          description: URI reference identifying the problem type
+          example: https://api.hyperfleet.io/errors/validation-error
+        title:
           type: string
-          description: Resource kind
-        href:
+          description: Short human-readable summary of the problem
+          example: Validation Failed
+        status:
+          type: integer
+          format: int32
+          description: HTTP status code
+          example: 400
+        detail:
           type: string
-          description: Resource URI
+          description: Human-readable explanation specific to this occurrence
+          example: The cluster name field is required
+        instance:
+          type: string
+          format: uri
+          description: URI reference for this specific occurrence
+          example: /api/hyperfleet/v1/clusters
         code:
           type: string
-        reason:
+          description: Machine-readable error code in HYPERFLEET-CAT-NUM format
+          example: HYPERFLEET-VAL-001
+        timestamp:
           type: string
-        operation_id:
+          format: date-time
+          description: RFC3339 timestamp of when the error occurred
+          example: '2024-01-15T10:30:00Z'
+        trace_id:
           type: string
-        details:
+          description: Distributed trace ID for correlation
+          example: abc123def456
+        errors:
           type: array
           items:
-            type: object
-            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)
+            $ref: '#/components/schemas/ValidationError'
+          description: Field-level validation errors (for validation failures)
+      description: RFC 9457 Problem Details error format with HyperFleet extensions
     NodePool:
       type: object
       required:
@@ -1269,6 +1289,40 @@ components:
         - Ready
         - Failed
       description: Phase of a resource (Cluster or NodePool)
+    ValidationConstraint:
+      type: string
+      enum:
+        - required
+        - min
+        - max
+        - min_length
+        - max_length
+        - pattern
+        - enum
+        - format
+        - unique
+      description: Validation constraint types for field-level errors
+    ValidationError:
+      type: object
+      required:
+        - field
+        - message
+      properties:
+        field:
+          type: string
+          description: JSON path to the field that failed validation
+          example: spec.name
+        value:
+          description: The invalid value that was provided (if safe to include)
+        constraint:
+          allOf:
+            - $ref: '#/components/schemas/ValidationConstraint'
+          description: The validation constraint that was violated
+        message:
+          type: string
+          description: Human-readable error message for this field
+          example: Cluster name is required
+      description: Field-level validation error detail (RFC 9457 extension)
   securitySchemes:
     BearerAuth:
       type: http