OSAC-2750: PRD: API Quality: Declarative Validation, Auto-Generated Public API, and Consistency

[htayrie-rh]

PRD: API Quality — Declarative Validation, Auto-Generated Public API, and Consistency

Jira: https://redhat.atlassian.net/browse/OSAC-1577

Summary

This PRD covers four API quality workstreams for the fulfillment service: declarative validation via protovalidate (already complete), automated public API generation from annotated private protos, a standard pattern for cross-object constraint enforcement respecting soft deletion, and incremental DAO/query consistency fixes. The scope is bounded to the four existing epics (OSAC-1275, OSAC-1274, OSAC-1331, OSAC-1540) with no new resource types or breaking changes.

Requesting Review On

• Requirements completeness and accuracy
• Scope (in scope and out of scope)
• User stories — do they capture the right developer and consumer needs?
• Assumptions — are these valid?

How to Review

• Comment inline on specific sections
• Approve when the PRD accurately reflects the agreed requirements

Summary by CodeRabbit

• Documentation
  • Added a PRD covering improvements to API validation consistency, automated public API generation, standardized cross-object constraint enforcement, and incremental query/DAO semantics cleanup.
  • Documented scope, user stories, assumptions, dependencies, and out-of-scope items for the API quality initiative.

[coderabbitai]

Warning

Review limit reached

@htayrie-rh, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 39 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Repository: osac-project/coderabbit/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: eda7f021-5d60-4bc5-95f6-72dcf282acf1

📥 Commits

Reviewing files that changed from the base of the PR and between e4c6646 and 496161c.

📒 Files selected for processing (1)

• enhancements/OSAC-1577-api-quality/prd.md

Walkthrough

Adds a PRD describing declarative validation, generated public APIs, soft-deletion-aware constraint enforcement, DAO/query semantics cleanup, scope boundaries, assumptions, dependencies, and provenance.

Changes

API Quality PRD

Layer / File(s)	Summary
API quality requirements and scope enhancements/OSAC-1577-api-quality/prd.md	Defines the problem statement, deliverables, exclusions, user stories, assumptions, protoc-gen-cleanapi dependency, and provenance metadata.

Estimated code review effort: 1 (Trivial) | ~3 minutes

Suggested reviewers: ygalblum, rgolangh

🚥 Pre-merge checks | ✅ 11

✅ Passed checks (11 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the PRD and the main API quality workstreams covered in the change.
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.
No-Hardcoded-Secrets	✅ Passed	The only changed file is a PRD markdown doc; it contains no secret literals, embedded credentials, or sensitive variable assignments.
No-Weak-Crypto	✅ Passed	No MD5/SHA1/DES/RC4/3DES/Blowfish/ECB or custom crypto found; the PR changes are documentation only.
No-Injection-Vectors	✅ Passed	PASS: The PR only adds a markdown PRD; the touched file contains no executable code or flagged sinks (SQL/shell/eval/pickle/yaml/innerHTML).
Container-Privileges	✅ Passed	PR only updates a markdown PRD; the diff has no container/K8s manifests or privilege flags like privileged, hostPID, hostNetwork, SYS_ADMIN, or allowPrivilegeEscalation.
No-Sensitive-Data-In-Logs	✅ Passed	The only changed file is a PRD markdown, and it contains no logging instructions or sensitive-data exposures.
Ai-Attribution	✅ Passed	PRD includes AI provenance, and both PR commits carry Assisted-by trailers; no Co-Authored-By AI attribution was found.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[github-actions]

AI EP Review: EP-152

Score: 5/10 | Verdict: PASS

Criterion	Score	Notes
What	1/2	Uses non-standard personas (API Developer, API Consumer) instead of canonical OSAC personas. No services identified. Cross-cutting dimensions not addressed. User stories describe developer experience, not user-observable product outcomes. Need is partially clear but framed internally.
Why	1/2	Problem statement describes real pain (inconsistent errors, validation gaps, manual proto sync) but provides no specific examples, no quantified impact, and no strategic tie. 'Slows down development and consumption' is asserted without evidence.
How	1/2	Significant design leakage: 'protovalidate annotations,' 'protoc plugin,' 'JSONB columns,' 'DAO/query semantics.' In Scope reads like a task list. No acceptance criteria or success metrics — user stories describe desired states but nothing measurable.
Task	1/2	Engineering quality initiative — refactoring validation, build tooling, code pattern standardization, cleanup. OSAC-1275 already complete. Users gain no new capability; existing behavior becomes more consistent. Not documentation-only, but not a clear product feature enhancement.
Size	1/2	Bundles 4 independent epics (OSAC-1274, OSAC-1275, OSAC-1331, OSAC-1540), one already shipped. Each can ship independently. Same theme (API quality) but clearly separable work — should be structured as an epic with individual features.

Verdict: The PRD is a marginally passing engineering quality initiative that bundles four independent epics under an API consistency theme, but lacks standard OSAC personas, measurable acceptance criteria, and contains significant design leakage.

Feedback: Reframe user stories around canonical OSAC personas (Tenant User, Tenant Admin, etc.) experiencing the actual product outcomes — e.g., 'As a Tenant User, I receive consistent, actionable validation error messages when creating any resource type.' Remove implementation details (protovalidate, protoc plugin, JSONB, DAO) from the PRD and reserve them for the design document. Consider whether this belongs as a Jira epic with individual tasks rather than a PRD, since no new product capability is introduced — the value is consistency and quality of existing behavior.

Critical (0)

None.

Important (4)

1. Non-standard personas: 'API Developer' and 'API Consumer' are not canonical OSAC personas. Map to Cloud Provider Admin, Tenant Admin, Tenant User, etc. to clarify who actually benefits from the product perspective.
2. Design leakage throughout: 'protovalidate annotations in proto files,' 'protoc plugin,' 'JSONB columns,' 'DAO/query semantics' are all implementation details that belong in the design document, not the PRD.
3. No acceptance criteria or measurable success metrics: User stories state desired states but provide no way to verify them. Add observable criteria like 'validation error messages include the field name, constraint violated, and accepted format for every resource type.'
4. Bundles 4 independent epics (one already complete) — consider structuring as an epic with separate features that can be prioritized and delivered independently.

Suggestions (3)

1. Identify which OSAC services are affected (BMaaS, CaaS, VMaaS, etc.) and which cross-cutting dimensions apply.
2. Remove OSAC-1275 from scope since it is already complete — reference it as prior work instead.
3. Quantify the problem: how many resource types have validation gaps? How many inconsistent error patterns exist? This would strengthen the WHY.

---

Review cost

Model: claude-opus-4-6
Cost: $0.6104
Tokens: 6 in / 6.5k out
Cache: 151.3k read
Active time: 2m 26s
API calls: 0

[openshift-ci]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: avishayt, htayrie-rh

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 [avishayt]

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

[avishayt]

Looks good but I saw it's in draft state

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@enhancements/OSAC-1577-api-quality/prd.md`:
- Around line 15-16: Clarify the OSAC-1275 entry in the PRD as a completed
prerequisite rather than an OSAC-1577 deliverable: remove its implementation
from the in-scope requirements, retain the completion/status note, and update
the repeated assumption accordingly. Ensure the remaining scope describes only
OSAC-1577 acceptance criteria.
- Around line 17-18: Update the PRD requirements around cross-object constraints
to define observable soft-deletion behavior: specify whether soft-deleted
resources release unique names and whether references to soft-deleted resources
are rejected or ignored. Keep the guidance at the behavioral-requirements level
without prescribing storage or implementation mechanics.
- Around line 23-24: Reconcile the “Breaking API changes” scope in the PRD with
the backward-compatibility statement near the upgrade-support discussion: define
which existing consumers and persisted records must remain compatible during the
current deployment, and explicitly identify the owner or validation process for
the cross-epic contract. Update the relevant AIP adoption and compatibility
assumptions without relying solely on per-epic testing.
- Line 50: Update the protoc-gen-cleanapi bullet in the OSAC-1577 PRD to define
a verifiable production-ready criterion for OSAC-1274, using a measurable
requirement such as API compatibility coverage, performance benchmarks, or a
formal schema-stability guarantee. Alternatively, link directly to OSAC-1274’s
acceptance criteria, while preserving the dependency statement.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository: osac-project/coderabbit/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 1d756dbe-7ed9-4b0e-9421-f7606e665bf2

📥 Commits

Reviewing files that changed from the base of the PR and between 3c0fb4d and 96a8908.

📒 Files selected for processing (1)

• enhancements/OSAC-1577-api-quality/prd.md

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@enhancements/OSAC-1577-api-quality/prd.md`:
- Line 17: Revise the OSAC-1331 soft-deletion requirement in the PRD to require
rejecting relationships to soft-deleted objects without mandating database-level
enforcement. Leave the implementation mechanism open for the OSAC-1331 design
unless database-level enforcement has been explicitly validated.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository: osac-project/coderabbit/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: d543b7fb-5a43-42c4-8798-b60d5ac51d9c

📥 Commits

Reviewing files that changed from the base of the PR and between 96a8908 and e4c6646.

📒 Files selected for processing (1)

• enhancements/OSAC-1577-api-quality/prd.md

[github-actions]

AI EP Review: EP-152

Score: 5/10 | Verdict: FAIL

Criterion	Score	Notes
WHAT (clear need)	1/2	The PRD uses non-standard personas ('API Developer' and 'API Consumer') instead of OSAC's canonical personas (Cloud Provider Admin, Cloud Infrastructure Admin, Tenant Admin, Tenant User). 'API Developer' is an internal engineering role, not a platform user. User stories exist under persona headings but half describe developer experience (maintaining proto files, not writing Go validation code) rather than user-observable product capabilities. Some user-facing benefits exist — consistent validati
WHY (justification)	1/2	The problem statement describes real pain — inconsistent error messages, invalid input getting through, manual dual-maintenance of proto files, ad-hoc enforcement logic varying by resource type. However, the justification is generic ('slow down both API development and API consumption') without quantified impact, specific customer incidents, or strategic tie-in. There is no evidence of how many resources are affected, how often invalid input causes problems, or why this work matters now versus l
User-Facing Focus	1/2	Significant design leakage throughout the In Scope section: 'protovalidate annotations in proto files, replacing hand-written Go validation' (HOW), 'via a protoc plugin' (HOW), 'PostgreSQL foreign keys' (implementation detail), 'DAO/query semantics cleanup' (internal). The Dependencies section names a specific tool (protoc-gen-cleanapi). Even user stories contain implementation details: 'validation rules declared in proto files', 'public API generated automatically from the private API'. The sme
Right-Sized	1/2	Bundles four independent engineering initiatives with separate Jira tickets: declarative validation (OSAC-1275, already complete), public API auto-generation (OSAC-1274), soft-deletion cross-object constraints (OSAC-1331), and DAO/query cleanup (OSAC-1540). Each can ship independently — demonstrated by OSAC-1275 already being complete. They share a 'quality' theme and the same personas but address different problems (validation vs. code generation vs. referential integrity vs. consistency). Inde
Testability	1/2	Mixed. Some requirements are verifiable by using the product: 'error messages are consistent across resource types' (make API calls and compare errors), 'reject attempts to reference soft-deleted objects' (try to attach to a deleted subnet, expect an error), 'documented behavior matches actual behavior' (compare API docs to responses). But others describe internal engineering outcomes not observable from the outside: 'validation rules declared in proto files' (internal tooling), 'consistent DAO

Verdict: The PRD scores 5/10 and fails the >=7 threshold — it reads as an internal engineering quality initiative with non-standard personas, pervasive design leakage in the In Scope section, generic business justification, and four independent capabilities bundled under one umbrella.

Feedback: Rewrite the PRD from the perspective of API consumers using OSAC's canonical personas (Tenant User, Tenant Admin, Cloud Provider Admin, Cloud Infrastructure Admin) — describe what they observe changing, not how the engineering works internally. Replace implementation-specific In Scope items ('protovalidate annotations', 'protoc plugin', 'DAO cleanup') with user-observable outcomes ('validation errors are consistent and derived from the API schema', 'the API rejects references to deleted resources with a clear error'). Consider whether this belongs as a PRD at all — four independent engineering improvements with separate Jira tickets may be better tracked as individual Jira tasks or as an epic with separate features, especially since OSAC-1275 is already complete.

Critical (2)

1. Non-standard personas: PRD uses 'API Developer' (an internal engineering role) and 'API Consumer' instead of OSAC's canonical personas. The PRD review rubric requires each affected persona to have user stories under persona headings using the four canonical OSAC personas. Rewrite user stories under Tenant User, Tenant Admin, Cloud Provider Admin, and/or Cloud Infrastructure Admin headings describing what each persona observes changing.
2. Pervasive design leakage in In Scope: all four In Scope items prescribe implementation — 'protovalidate annotations in proto files, replacing hand-written Go validation', 'via a protoc plugin', 'at the database level', 'DAO/query semantics cleanup'. Rewrite as user-observable outcomes: e.g., 'API validation errors are consistent across all resource types and accurately reflect accepted input formats' instead of 'Declarative input validation via protovalidate annotations'.

Important (4)

1. Business justification lacks specifics: the problem statement describes pain generically ('slow down API development and consumption') without naming how many resources are affected, citing specific incidents of invalid input causing problems, or tying to a strategic goal. Strengthen with concrete evidence.
2. Four independent capabilities bundled: OSAC-1275 (complete), OSAC-1274, OSAC-1331, and OSAC-1540 are each independently deliverable with separate Jira tickets. Consider restructuring as an epic with individual features, or justify in the PRD why they must ship together.
3. No OSAC services identified: the PRD does not declare which services (BMaaS, CaaS, VMaaS, MaaS, Enclave) are in scope, which is expected per osac-dimensions.md.
4. User stories contain implementation details: 'I want validation rules declared in proto files', 'I want the public API generated automatically from the private API', 'I want cross-object constraints to automatically prevent relationships' all describe engineering approaches rather than user-observable outcomes.

Suggestions (3)

1. Add a Risks section — the dependency on protoc-gen-cleanapi being 'production-ready' is a significant risk that deserves mitigation planning, not just a Dependencies note.
2. Consider whether the DAO/query cleanup (OSAC-1540) belongs in a PRD at all — 'incremental cleanup and consistency fixes' is typically tracked as tech debt in Jira tasks, not as a product requirement.
3. The fact that OSAC-1275 is already complete suggests it should be removed from In Scope or moved to a 'Completed' section to avoid confusion about what remains to be delivered.

---

Review cost

Model: claude-opus-4-6
Cost: $0.6190
Tokens: 6 in / 6.5k out
Cache: 153.5k read
Active time: 2m 23s
API calls: 0

[github-actions]

AI EP Review: EP-152

Score: 4/10 | Verdict: FAIL

Criterion	Score	Notes
WHAT (clear need)	1/2	The PRD identifies two personas — 'API Developer' and 'API Consumer' — but neither maps to OSAC's canonical personas (Cloud Provider Admin, Cloud Infrastructure Admin, Tenant Admin, Tenant User). 'API Developer' is an internal engineering role, not a product user. Some user-observable outcomes exist in the 'API Consumer' stories (consistent validation errors, rejection of soft-deleted references), but they are mixed with engineering-internal concerns. No OSAC services (BMaaS, CaaS, VMaaS, etc.)
WHY (justification)	1/2	The Problem Statement describes real pain — hand-written validation drifting from schemas, manual dual-maintenance of proto files, ad-hoc soft-deletion enforcement — and names a consequence: 'slow down both API development and API consumption.' However, the justification is entirely in engineering terms. There is no user impact quantification, no incident evidence, no strategic tie. 'Allowing invalid input through gaps in coverage' hints at user pain but is not developed. Score 1: plausible but
User-Facing Focus	0/2	The PRD has pervasive design leakage. The Problem Statement names PostgreSQL foreign keys, Go validation code, proto files, and ad-hoc implementations. In Scope names a protoc plugin (protoc-gen-cleanapi), DAO/query semantics, and proto file maintenance. User stories for 'API Developer' describe engineering workflow: 'maintain one set of proto definitions instead of two', 'do not maintain separate Go validation code', 'consistent DAO and query semantics.' Even 'API Consumer' stories reference im
Right-Sized	1/2	The PRD bundles three independent epics: OSAC-1274 (auto-generate public API), OSAC-1331 (cross-object soft-deletion constraints), and OSAC-1540 (DAO/query semantics cleanup). Each could ship independently and provide value on its own — auto-generating the public API does not depend on soft-deletion enforcement, and DAO cleanup is orthogonal to both. They share a theme ('API quality') and the same personas, which keeps this from a 0, but they are clearly separable capabilities. Score 1: 1-2 sepa
Testability	1/2	Some requirements are testable from outside: 'API to reject attempts to reference soft-deleted objects' can be verified by attempting such a reference and expecting an error. 'Validation errors... consistent across resource types' can be partially verified by testing multiple resource types. However, 'public API generated automatically from private API' is an engineering process not testable by a PM. 'Consistent DAO and query semantics' is purely internal. 'Maintain one set of proto definitions

Verdict: The PRD scores 0 on User-Facing Focus due to pervasive design leakage (protoc plugins, DAO semantics, Go validation code, PostgreSQL foreign keys), triggering an automatic fail at 4/10 total.

Feedback: Rewrite the PRD from the perspective of API consumers using OSAC's canonical personas (Tenant User, Tenant Admin, Cloud Provider Admin, Cloud Infrastructure Admin) — not 'API Developer.' Frame the problem as user pain: what goes wrong for a Tenant User who submits invalid input today, or who tries to reference a deleted subnet? Strip all implementation details (protoc plugins, DAO, Go validation, PostgreSQL FK) into the design document; the PRD should describe only what users can observe changing. Consider whether the three independent epics (OSAC-1274, OSAC-1331, OSAC-1540) belong as separate features rather than one bundled PRD, since each can ship and deliver value independently.

Critical (2)

1. User-Facing Focus scores 0: The PRD names internal tools (protoc-gen-cleanapi, protovalidate), code-level concepts (DAO, Go validation, PostgreSQL foreign keys), and engineering processes (proto file maintenance) throughout. The In Scope section reads as three engineering tasks, not user outcomes. Rewrite each in-scope item as a user-observable change: e.g., 'API validation errors are consistent across all resource types and match the documented schema' instead of 'Automated generation of the pu
2. Personas 'API Developer' and 'API Consumer' are not OSAC canonical personas. 'API Developer' is an internal engineering role — user stories like 'I do not maintain separate Go validation code' describe developer workflow, not product capabilities. Map to Cloud Provider Admin, Tenant Admin, Tenant User, or Cloud Infrastructure Admin and write stories about what each persona can observe.

Important (3)

1. WHY justification is framed entirely in engineering terms ('drifts from proto documentation', 'error-prone manual sync', 'ad-hoc implementations'). Add user-facing impact: what do end users experience when validation is inconsistent? Have invalid inputs caused incidents? What happens when a tenant references a soft-deleted object today?
2. Three independent epics (OSAC-1274, OSAC-1331, OSAC-1540) are bundled as one PRD. Each can ship independently. Consider whether this should be an epic with three separate feature PRDs, or at minimum justify in the PRD why they must ship together.
3. No acceptance criteria section. Add measurable, user-observable acceptance criteria for each in-scope item — e.g., 'Submitting invalid input to any resource type returns a 400 error with a message that names the invalid field and the constraint violated.'

Suggestions (3)

1. Add an OSAC services declaration — which services (BMaaS, CaaS, VMaaS, etc.) are affected by the API quality improvements?
2. The cross-cutting dimensions (E2E testing, documentation, UI, installation) are unaddressed. Even if each epic owns its own testing (per Assumptions), the PRD should declare what's in scope vs. deferred for these dimensions.
3. Consider adding a milestone scoping section with a target milestone and what's explicitly deferred, per OSAC dimension guidelines.

---

Review cost

Model: claude-opus-4-6
Cost: $0.5591
Tokens: 6 in / 4.9k out
Cache: 150.9k read
Active time: 1m 58s
API calls: 0

[CrystalChun]

/retitle OSAC-2750: PRD: API Quality: Declarative Validation, Auto-Generated Public API, and Consistency