finding_id: REV-2026-010
priority: P1
area: validator
kind: bug
paths:
- api-codegen-core/src/main/java/com/apicgen/validator/ApiValidator.java
- api-codegen-core/src/main/java/com/apicgen/validator/ValidationAnalyzer.java
- api-codegen-core/src/main/java/com/apicgen/bridge/UiDocumentService.java
blocked_by: []
automation: needs-design
Summary
Return structured validation errors for null and nested API fields instead of throwing or misclassifying internal failures as YAML syntax errors.
Evidence
Global review finding REV-2026-010 identified null elements such as apis:[null] and fields:[null], insufficient nested-field validation, and bridge error mapping that can mask internal NPEs.
Impact
Malformed documents can crash validation, lose the failing index/path, or produce misleading UI diagnostics; valid callers cannot rely on a stable result contract.
Scope
Add indexed ValidationError results for null and nested malformed values, preserve immutable validation snapshots, and distinguish model/validation failures from YAML parse failures in the bridge.
Out of scope
Changing accepted Swagger/OpenAPI dialects, parser security limits, or unrelated generator diagnostics.
Acceptance criteria
apis:[null] 和 fields:[null] 返回带索引的 ValidationError，不抛 NPEnested fields 递归校验 name/type/validation- bridge 不把内部 NPE 伪装成 YAML 语法错误
ValidationResult 返回不可变快照- 增加 null/nested malformed fixture
Verification
Run validator and bridge tests with null, nested malformed, parse-invalid, and valid fixtures; assert error types, indexes, paths, and immutable result behavior.
Rollback
Revert the validation-contract implementation while retaining malformed fixtures and documenting compatibility constraints discovered.
Dependencies
None. Keep this issue labeled automation:needs-design; do not add automation:ready until design review is complete.
finding_id: REV-2026-010
priority: P1
area: validator
kind: bug
paths:
blocked_by: []
automation: needs-design
Summary
Return structured validation errors for null and nested API fields instead of throwing or misclassifying internal failures as YAML syntax errors.
Evidence
Global review finding REV-2026-010 identified null elements such as
apis:[null]andfields:[null], insufficient nested-field validation, and bridge error mapping that can mask internal NPEs.Impact
Malformed documents can crash validation, lose the failing index/path, or produce misleading UI diagnostics; valid callers cannot rely on a stable result contract.
Scope
Add indexed
ValidationErrorresults for null and nested malformed values, preserve immutable validation snapshots, and distinguish model/validation failures from YAML parse failures in the bridge.Out of scope
Changing accepted Swagger/OpenAPI dialects, parser security limits, or unrelated generator diagnostics.
Acceptance criteria
apis:[null]和fields:[null]返回带索引的ValidationError，不抛 NPEnested fields递归校验name/type/validationValidationResult返回不可变快照Verification
Run validator and bridge tests with null, nested malformed, parse-invalid, and valid fixtures; assert error types, indexes, paths, and immutable result behavior.
Rollback
Revert the validation-contract implementation while retaining malformed fixtures and documenting compatibility constraints discovered.
Dependencies
None. Keep this issue labeled
automation:needs-design; do not addautomation:readyuntil design review is complete.