diff --git a/main.tsp b/main.tsp index d3dd4c3..5980b87 100644 --- a/main.tsp +++ b/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; diff --git a/models/common/model.tsp b/models/common/model.tsp index 7d7fc3d..82878b8 100644 --- a/models/common/model.tsp +++ b/models/common/model.tsp @@ -43,32 +43,88 @@ model ObjectReference2 { 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: Kind; +model ErrorResponse { @statusCode statusCode: ErrorCode; + @header contentType: "application/problem+json"; @body error: Error; } diff --git a/schemas/core/openapi.yaml b/schemas/core/openapi.yaml index d19b926..8e656c5 100644 --- a/schemas/core/openapi.yaml +++ b/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 diff --git a/schemas/gcp/openapi.yaml b/schemas/gcp/openapi.yaml index 1139595..7f7ca4e 100644 --- a/schemas/gcp/openapi.yaml +++ b/schemas/gcp/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: @@ -240,7 +240,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: @@ -296,7 +296,7 @@ paths: default: description: An unexpected error response. content: - application/json: + application/problem+json: schema: $ref: '#/components/schemas/Error' security: @@ -862,33 +862,53 @@ components: type: string 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 NetworkingSpec: type: object properties: @@ -1337,6 +1357,40 @@ components: - NoSchedule - PreferNoSchedule - NoExecute + 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 diff --git a/schemas/gcp/swagger.yaml b/schemas/gcp/swagger.yaml index 512776b..c8854dd 100644 --- a/schemas/gcp/swagger.yaml +++ b/schemas/gcp/swagger.yaml @@ -16,7 +16,7 @@ info: name: Apache 2.0 url: 'https://www.apache.org/licenses/LICENSE-2.0' title: HyperFleet API - version: 1.0.2 + version: 1.0.3 host: hyperfleet.redhat.com basePath: / schemes: @@ -26,6 +26,7 @@ paths: get: produces: - application/json + - application/problem+json parameters: - description: >- Filter results using TSL (Tree Search Language) query syntax. @@ -80,6 +81,7 @@ paths: - application/json produces: - application/json + - application/problem+json parameters: - in: body name: body @@ -118,6 +120,7 @@ paths: get: produces: - application/json + - application/problem+json parameters: - description: >- Filter results using TSL (Tree Search Language) query syntax. @@ -151,6 +154,7 @@ paths: get: produces: - application/json + - application/problem+json parameters: - description: Cluster ID in: path @@ -211,6 +215,7 @@ paths: - application/json produces: - application/json + - application/problem+json parameters: - description: Cluster ID in: path @@ -244,6 +249,7 @@ paths: get: produces: - application/json + - application/problem+json parameters: - description: Cluster ID in: path @@ -275,6 +281,7 @@ paths: get: produces: - application/json + - application/problem+json parameters: - description: Cluster ID in: path @@ -393,6 +400,7 @@ paths: get: produces: - application/json + - application/problem+json parameters: - description: >- Filter results using TSL (Tree Search Language) query syntax. @@ -983,33 +991,53 @@ definitions: type: string type: object Error: + description: RFC 9457 Problem Details error format with HyperFleet extensions properties: code: + description: Machine-readable error code in HYPERFLEET-CAT-NUM format + example: HYPERFLEET-VAL-001 type: string - details: - description: Field-level validation errors (optional) + detail: + description: Human-readable explanation specific to this occurrence + example: The cluster name field is required + type: string + errors: + description: Field-level validation errors (for validation failures) items: - properties: - error: - description: Validation error message for this field - type: string - field: - description: Field path that failed validation - type: string - type: object + $ref: '#/definitions/ValidationError' type: array - href: - description: Resource URI + instance: + description: URI reference for this specific occurrence + example: /api/hyperfleet/v1/clusters + format: uri type: string - id: + status: + description: HTTP status code + example: 400 + format: int32 + type: integer + timestamp: + description: RFC3339 timestamp of when the error occurred + example: '2024-01-15T10:30:00Z' + format: date-time type: string - kind: - description: Resource kind + title: + description: Short human-readable summary of the problem + example: Validation Failed type: string - operation_id: + trace_id: + description: Distributed trace ID for correlation + example: abc123def456 type: string - reason: + type: + description: URI reference identifying the problem type + example: 'https://api.hyperfleet.io/errors/validation-error' + format: uri type: string + required: + - type + - title + - status type: object NetworkingSpec: properties: @@ -1481,6 +1509,40 @@ definitions: - key - effect type: object + ValidationConstraint: + description: Validation constraint types for field-level errors + enum: + - required + - min + - max + - min_length + - max_length + - pattern + - enum + - format + - unique + type: string + ValidationError: + description: Field-level validation error detail (RFC 9457 extension) + properties: + constraint: + allOf: + - $ref: '#/definitions/ValidationConstraint' + description: The validation constraint that was violated + field: + description: JSON path to the field that failed validation + example: spec.name + type: string + message: + description: Human-readable error message for this field + example: Cluster name is required + type: string + value: + description: The invalid value that was provided (if safe to include) + required: + - field + - message + type: object securityDefinitions: BearerAuth: in: header