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

[rafabene]

Summary

• Update Error model to RFC 9457 Problem Details format
• Add required fields: type, title, status
• Add optional fields: detail, instance, code, timestamp, trace_id
• Add ValidationError model with field, value, constraint, message
• Add ValidationConstraint enum for constraint types
• Update ErrorResponse to use application/problem+json content type

Test plan

• TypeSpec compiles successfully
• Generated OpenAPI schema matches RFC 9457 format
• Verify alignment with hyperfleet-api implementation

Related

• hyperfleet-api PR: HYPERFLEET-452 - feat: implement RFC 9457 Problem Details error model hyperfleet-api#37

Breaking Change

This is a breaking change. The error response format changes from custom format to RFC 9457 Problem Details.

Resolves: https://issues.redhat.com/browse/HYPERFLEET-452

Summary by CodeRabbit

• New Features

  • Enhanced error responses with RFC 9457 Problem Details: required type/title/status, detailed messages, timestamps, trace IDs, and structured field-level validation errors.
  • Added explicit validation constraint types for clearer, machine-readable validation feedback.

• Refactor

  • Standardized API error shape for more consistent client handling.

• Chores

  • Bumped public API/spec version to 1.0.3 and set error responses' content type to application/problem+json.

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

[coderabbitai]

Walkthrough

The PR converts the Error model to RFC 9457 Problem Details with HyperFleet extensions: adds a ValidationConstraint enum and ValidationError model; replaces Error fields (id, href, kind) with type, title, status, detail, instance, code, timestamp, trace_id and an errors array of ValidationError; updates ErrorResponse to a single generic ErrorCode and sets Content-Type to application/problem+json. OpenAPI/Swagger manifests and schema files are updated to expose ValidationConstraint and ValidationError and to bump the API version from 1.0.2 to 1.0.3.

Sequence Diagram(s)

(omitted)

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• feat: standardize TypeSpec schema definitions with enums and validation enhancements #17 — Previously modified Error to include structured field-level validation details; overlaps with ValidationError/ValidationConstraint and the errors array changes.

Suggested reviewers

• rh-amarin

🚥 Pre-merge checks | ✅ 3

✅ 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 and specifically describes the main change: implementing RFC 9457 Problem Details error model, which is the primary focus of all modified files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

---

📜 Recent review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 9185fe9 and e813fbf.

📒 Files selected for processing (5)

• main.tsp
• models/common/model.tsp
• schemas/core/openapi.yaml
• schemas/gcp/openapi.yaml
• schemas/gcp/swagger.yaml

🚧 Files skipped from review as they are similar to previous changes (1)

• main.tsp

🔇 Additional comments (15)

schemas/core/openapi.yaml (4)

1-4: LGTM! Version bump to 1.0.3 for breaking change.

The version increment correctly signals the breaking change in error response format.

---

40-42: LGTM! Content-Type updated to RFC 9457 standard.

The application/problem+json media type is correctly applied to all default error responses throughout the spec, aligning with RFC 9457 requirements.

---

917-965: LGTM! Well-structured RFC 9457 Error schema.

The Error model correctly implements RFC 9457 Problem Details with:

• Required fields: type, title, status (RFC 9457 core)
• HyperFleet extensions: code, timestamp, trace_id, errors
• Proper URI format annotations for type and instance

---

1292-1325: LGTM! ValidationConstraint and ValidationError definitions.

The new schema components provide good coverage:

• ValidationConstraint covers common validation types
• ValidationError with required field and message enables clear field-level error reporting
• The untyped value property correctly allows flexibility for any invalid value type

models/common/model.tsp (4)

46-59: LGTM! ValidationConstraint enum with appropriate identifiers.

Good approach using distinct identifiers (e.g., pattern_match, enum_value, format_check) that map to the desired string values, avoiding potential reserved word conflicts in TypeSpec while producing the correct enum values in generated schemas.

---

64-78: LGTM! ValidationError model with flexible value type.

Using unknown for the value property is appropriate here, allowing any type of invalid value to be reported while maintaining type safety.

---

125-129: LGTM! ErrorResponse simplified to single generic parameter.

Removing the Kind generic parameter and keeping only ErrorCode is a clean simplification that aligns with the RFC 9457 approach where error types are identified by URI (type field) rather than a kind discriminator.

---

83-89: Remove or clarify the @header contentType concern—Error model's header declaration is intentional.

The @header contentType on the Error model is not redundant. The @defaultResponse decorator indicates Error is used as a direct response option in response unions (e.g., | Error in service definitions), not only when wrapped in ErrorResponse. The generated OpenAPI schema confirms this—Error is referenced with application/problem+json content-type. While both Error and ErrorResponse declare the same header, this is standard TypeSpec: the header applies when each model is used in its context (directly for Error, as a wrapper for ErrorResponse).

schemas/gcp/openapi.yaml (3)

1-4: LGTM! GCP schema version consistent with core schema.

Version 1.0.3 correctly synchronized across both OpenAPI specs.

---

863-911: LGTM! Error schema consistent with core/openapi.yaml.

The RFC 9457 Error schema is correctly duplicated in the GCP-specific OpenAPI spec with identical structure and fields.

---

1360-1393: LGTM! ValidationConstraint and ValidationError consistent across specs.

These definitions match the core schema, ensuring consistent validation error handling across all API variants.

schemas/gcp/swagger.yaml (4)

19-29: LGTM! Swagger 2.0 correctly adapted for RFC 9457.

The produces array approach is the correct Swagger 2.0 pattern for specifying response content types. Including both application/json (for success) and application/problem+json (for errors) allows proper content negotiation.

---

993-1041: LGTM! Error definition in Swagger 2.0 format.

The Error schema correctly implements RFC 9457 with:

• Required array with type, title, status
• All optional extension fields properly defined
• URI format annotations where applicable

---

1512-1545: LGTM! ValidationConstraint and ValidationError for Swagger 2.0.

Definitions are consistent with the OpenAPI 3.0 schemas. Note that in Swagger 2.0, the value property in ValidationError (lines 1540-1541) omits the type field entirely, which effectively allows any type—matching the unknown type semantics from the TypeSpec model.

---

342-346: Note: getClusterStatuses endpoint intentionally excludes application/problem+json.

This endpoint only has explicit 200, 400, and 404 responses without a default error schema, so not including application/problem+json in the produces array is correct. Just flagging for visibility that this is an intentional difference from other endpoints.

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

---

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

[coderabbitai]

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

schemas/core/openapi.yaml (1)

37-42: Add RFC 9457-compliant content type to error responses.

Error responses currently generate application/json in the OpenAPI spec, but RFC 9457 (Problem Details for HTTP APIs) specifies application/problem+json. The TypeSpec model defines an ErrorResponse wrapper with @header contentType: "application/problem+json", but it's unused—services return the bare Error model instead, which lacks the content-type header directive.

To fix this, either:

1. Add @header contentType: "application/problem+json"; to the Error model in models/common/model.tsp, or
2. Refactor service operations to return ErrorResponse<statusCode> instead of bare Error

Option 1 is simpler and ensures all error responses comply with RFC 9457.

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 0222dde and 9185fe9.

📒 Files selected for processing (5)

• main.tsp
• models/common/model.tsp
• schemas/core/openapi.yaml
• schemas/gcp/openapi.yaml
• schemas/gcp/swagger.yaml

🔇 Additional comments (14)

main.tsp (1)

23-23: LGTM! Version bump aligns with breaking change.

The version increment to 1.0.3 is appropriate given the breaking change in error response format from custom to RFC 9457 Problem Details.

models/common/model.tsp (4)

46-59: LGTM! ValidationConstraint enum is well-designed.

The constraint types cover common validation scenarios. The enum provides meaningful string literals that will serialize consistently in the OpenAPI output.

---

61-78: LGTM! ValidationError model follows RFC 9457 extension pattern.

The model properly extends RFC 9457 with field-level validation details. Using unknown for the value field is appropriate to accommodate any data type.

---

80-122: LGTM! Error model correctly implements RFC 9457 Problem Details.

The model properly defines:

• Required fields per RFC 9457: type, title, status
• Optional fields per RFC 9457: detail, instance
• HyperFleet extensions: code, timestamp, trace_id, errors

Format decorators (@format("uri"), @format("date-time")) are correctly applied.

---

124-128: LGTM! ErrorResponse correctly specifies RFC 9457 content type.

The application/problem+json content type header is correctly set per RFC 9457 requirements.

schemas/core/openapi.yaml (3)

4-4: LGTM! Version aligned across spec files.

---

917-965: LGTM! Error schema correctly implements RFC 9457.

Required fields (type, title, status) and optional fields are properly defined with appropriate formats and examples.

---

1292-1325: LGTM! ValidationConstraint and ValidationError schemas are correct.

The schemas match the TypeSpec definitions and follow OpenAPI conventions. The allOf pattern for the constraint field properly references the enum while allowing additional metadata.

schemas/gcp/openapi.yaml (3)

4-4: LGTM! Version consistent with other spec files.

---

863-911: LGTM! Error schema consistent with core OpenAPI spec.

The RFC 9457 Problem Details implementation mirrors the core spec correctly.

---

1360-1393: LGTM! Validation schemas consistent with core OpenAPI spec.

schemas/gcp/swagger.yaml (3)

19-19: LGTM! Version consistent across all spec files.

---

985-1033: LGTM! Error definition correctly implements RFC 9457 in Swagger 2.0 format.

The required fields (type, title, status) and property definitions are consistent with the OpenAPI 3.0 specs.

---

1504-1537: LGTM! Validation definitions correct for Swagger 2.0.

The allOf pattern for the constraint field is valid in Swagger 2.0, though some older tools may have limited support. This maintains consistency with the OpenAPI 3.0 specs.

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

[rh-amarin]

/lgtm

[openshift-ci]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: rh-amarin

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [rh-amarin]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment