HYPERFLEET-1231: align error-model.md detail field with RFC 9457 and TypeSpec

[kuudori]

Summary

• Relaxes detail field from Required=Yes to Required=No in the Standard Fields table of error-model.md
• Adds SHOULD guidance below the table preserving the expectation that implementations always populate detail
• Aligns the standard doc with TypeSpec (detail?: string), generated OpenAPI (required: [type, title, status]), and RFC 9457 Section 3.1 (SHOULD, not MUST)

Why

ADR-0003 establishes TypeSpec as the single source of truth for the API contract. The standard doc's Required=Yes contradicted both TypeSpec and RFC 9457 without documented justification. All existing implementations already populate detail via constructor patterns that require a reason string — this change is documentation-only with no behavioral impact.

Ticket: HYPERFLEET-1231

Verification

Source	Field	Status
error-model.md (this PR)	Required=No + SHOULD prose	updated
TypeSpec (model.tsp)	detail?: string	already optional
Generated OpenAPI	required: [type, title, status]	already excludes detail
RFC 9457 Section 3.1	SHOULD language	aligned

Test plan

• Markdownlint passes
• Reviewer confirms alignment with TypeSpec definition
• Reviewer confirms SHOULD prose is sufficient guardrail

[openshift-ci-robot]

@kuudori: This pull request references HYPERFLEET-1231 which is a valid jira issue.

Warning: The referenced jira issue has an invalid target version for the target branch this PR targets: expected the story to target the "5.0.0" version, but no target version was set.

Details

In response to this:

Summary

• Relaxes detail field from Required=Yes to Required=No in the Standard Fields table of error-model.md
• Adds SHOULD guidance below the table preserving the expectation that implementations always populate detail
• Aligns the standard doc with TypeSpec (detail?: string), generated OpenAPI (required: [type, title, status]), and RFC 9457 Section 3.1 (SHOULD, not MUST)

Why

ADR-0003 establishes TypeSpec as the single source of truth for the API contract. The standard doc's Required=Yes contradicted both TypeSpec and RFC 9457 without documented justification. All existing implementations already populate detail via constructor patterns that require a reason string — this change is documentation-only with no behavioral impact.

Ticket: HYPERFLEET-1231

Verification

Source	Field	Status
error-model.md (this PR)	Required=No + SHOULD prose	updated
TypeSpec (model.tsp)	detail?: string	already optional
Generated OpenAPI	required: [type, title, status]	already excludes detail
RFC 9457 Section 3.1	SHOULD language	aligned

Test plan

• Markdownlint passes
• Reviewer confirms alignment with TypeSpec definition
• Reviewer confirms SHOULD prose is sufficient guardrail

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

[openshift-ci]

Skipping CI for Draft Pull Request.
If you want CI signal for your change, please convert it to an actual PR.
You can still manually trigger a test run with /test all

[openshift-ci]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign tirthct for approval. For more information see the Code Review Process.

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

Details

Needs approval from an approver in each of these files:

• OWNERS

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

[openshift-ci-robot]

@kuudori: This pull request references HYPERFLEET-1231 which is a valid jira issue.

Warning: The referenced jira issue has an invalid target version for the target branch this PR targets: expected the story to target the "5.0.0" version, but no target version was set.

Details

In response to this:

Summary

• Relaxes detail field from Required=Yes to Required=No in the Standard Fields table of error-model.md
• Adds SHOULD guidance below the table preserving the expectation that implementations always populate detail
• Aligns the standard doc with TypeSpec (detail?: string), generated OpenAPI (required: [type, title, status]), and RFC 9457 Section 3.1 (SHOULD, not MUST)

Why

ADR-0003 establishes TypeSpec as the single source of truth for the API contract. The standard doc's Required=Yes contradicted both TypeSpec and RFC 9457 without documented justification. All existing implementations already populate detail via constructor patterns that require a reason string — this change is documentation-only with no behavioral impact.

Ticket: HYPERFLEET-1231

Verification

Source	Field	Status
error-model.md (this PR)	Required=No + SHOULD prose	updated
TypeSpec (model.tsp)	detail?: string	already optional
Generated OpenAPI	required: [type, title, status]	already excludes detail
RFC 9457 Section 3.1	SHOULD language	aligned

Test plan

• Markdownlint passes
• Reviewer confirms alignment with TypeSpec definition
• Reviewer confirms SHOULD prose is sufficient guardrail

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Enterprise

Run ID: 67d63aa9-77b0-4e83-8664-fb7ef3aba6a2

📥 Commits

Reviewing files that changed from the base of the PR and between 403ac39 and e91e92a.

📒 Files selected for processing (1)

• hyperfleet/standards/error-model.md

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• openshift-hyperfleet/architecture (manual)
• openshift-hyperfleet/hyperfleet-api (manual)
• openshift-hyperfleet/hyperfleet-sentinel (manual)
• openshift-hyperfleet/hyperfleet-adapter (manual)
• openshift-hyperfleet/hyperfleet-broker (manual)

---

📝 Walkthrough

Summary by CodeRabbit

• Documentation
  • Updated the error model guidance with a new “Last Updated” date.
  • Clarified that the detail field is now optional, while still strongly recommending it be included whenever possible.
  • Added guidance that providing detail helps deliver more actionable error messages and improves the developer experience.

Walkthrough

Updated hyperfleet/standards/error-model.md with a new “Last Updated” date and revised the RFC 9457 detail field guidance from required to optional, while adding text that implementations SHOULD still populate detail. No code paths or public entities changed. No CWE/CVE IDs are implicated.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

🚥 Pre-merge checks | ✅ 11

✅ Passed checks (11 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the change: making error-model.md's detail field optional and aligning it with RFC 9457 and TypeSpec.
Description check	✅ Passed	The description is directly related and accurately explains the documentation-only change and its alignment rationale.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Sec-02: Secrets In Log Output	✅ Passed	PASS: PR is doc-only; no non-test/example slog/logr/zap/fmt.Print* calls with token/password/credential/secret found (CWE-532).
No Hardcoded Secrets	✅ Passed	No hardcoded creds found; the PR only changes markdown docs, and scans found no user:pass@ URLs or literal apiKey/secret/token/password assignments (CWE-798).
No Weak Cryptography	✅ Passed	PASS: docs-only change; no crypto imports/usages, no SHA1/MD5/DES/RC4/ECB, and no secret comparisons found (CWE-327).
No Injection Vectors	✅ Passed	Only Markdown docs changed; diff has no exec.Command/template.HTML/yaml.Unmarshal/fmt.Sprintf query patterns.
No Privileged Containers	✅ Passed	PASS: PR only changes Markdown docs (error-model.md et al.); no K8s/OpenShift manifests, Helm templates, or Dockerfiles were modified, so no CWE-250/CWE-269 privilege issue.
No Pii Or Sensitive Data In Logs	✅ Passed	No CWE-532/CWE-209 issue: the touched doc logs only generic error text, path, field, and trace_id—no PII, secrets, or raw bodies.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

✨ Simplify code

• Create PR with simplified code

---

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

[openshift-ci-robot]

@kuudori: This pull request references HYPERFLEET-1231 which is a valid jira issue.

Warning: The referenced jira issue has an invalid target version for the target branch this PR targets: expected the story to target the "5.0.0" version, but no target version was set.

Details

In response to this:

Summary

• Relaxes detail field from Required=Yes to Required=No in the Standard Fields table of error-model.md
• Adds SHOULD guidance below the table preserving the expectation that implementations always populate detail
• Aligns the standard doc with TypeSpec (detail?: string), generated OpenAPI (required: [type, title, status]), and RFC 9457 Section 3.1 (SHOULD, not MUST)

Why

ADR-0003 establishes TypeSpec as the single source of truth for the API contract. The standard doc's Required=Yes contradicted both TypeSpec and RFC 9457 without documented justification. All existing implementations already populate detail via constructor patterns that require a reason string — this change is documentation-only with no behavioral impact.

Ticket: HYPERFLEET-1231

Verification

Source	Field	Status
error-model.md (this PR)	Required=No + SHOULD prose	updated
TypeSpec (model.tsp)	detail?: string	already optional
Generated OpenAPI	required: [type, title, status]	already excludes detail
RFC 9457 Section 3.1	SHOULD language	aligned

Test plan

• Markdownlint passes
• Reviewer confirms alignment with TypeSpec definition
• Reviewer confirms SHOULD prose is sufficient guardrail

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.