---
id: review-002-yaml-normalization
name: YAML input normalization — duplicates, .inf, merge keys, non-string keys (OAI-12)
status: completed
depends_on: []
scope: narrow
risk: medium
impact: component
level: implementation
tags: [adapters, review-002, from-openapi, openapi-spec]
---

## Description

Review 002 OAI-12 [major]. `OpenAPISpec::from_yaml`
(`openapi_spec.rs:153-158`) is a single `yaml_serde::from_str::<Value>`
with zero post-parse normalization; three verified corruptions flow
through unimpeded (empirically confirmed against yaml_serde 0.10.7):

1. **Duplicate keys silently last-win** on the Value path
   (`visit_map → values.insert`) while the JSON path *errors* on the
   same document — the two input formats disagree, YAML's failure
   mode is silent.
2. **`.inf`/`.nan` numbers become `Value::Null`** through
   `Number::from_f64(∞) → None` — a declared constraint (`maximum:
   .inf` is unusual, but any float inf) silently vanishes from the
   advertised schema.
3. **Merge keys (`<<: *anchor`) are not applied** (yaml_serde's
   `apply_merge()` is opt-in and unused) — `<<` survives as a literal
   property name in the resolved/advertised schema.

Non-string keys (`200:` response codes as numbers etc.) were checked —
plain statuses survive via string round-trips — but numeric inference
into any string-matched field is a live hazard (e.g. `style: 1`).

## Acceptance Criteria

- [ ] A post-parse normalization pass on the YAML path (before
      `from_value`): reject duplicate keys (loud, naming the path or
      at least the document context), reject `.inf/.nan`-derived
      nulls-from-floats (either reject or reject-with-context), and
      decide merge keys: either invoke `apply_merge()` (matching YAML
      1.1 user expectations; ADR-051 declares YAML 1.2 via yaml_serde —
      verify which the crate claims) or reject `<<` keys loudly
- [ ] Non-string keys: reject or coerce-with-loudness (decide; JSON
      path parity is the goal — the same document should mean the same
      thing through both entry points or the difference must be loud)
- [ ] Tests at the `from_yaml` seam (not the parser): duplicate keys →
      error; `.inf` → loud error (not silent null); merge key applied
      or rejected; quoted-always spec (`"200":`) unchanged
- [ ] A doc note on the YAML/JSON parity contract (ADR-051 section or
      the module doc)
- [ ] `cargo test`, `cargo clippy --all-targets -- -D warnings`,
      `cargo fmt --check` pass

## References

- docs/reviews/002-post-remediation-review.md (Part E', OAI-12; Test-gap 9)
- src/adapters/openapi_spec.rs:153-158 (the seam), from_openapi.rs (the consumers)
- docs/architecture/decisions/051-yaml-input-for-from-openapi.md
- tasks/adapters/review-001-openapi-import-integrity.md (the import-integrity context)

## Notes

Keep the walk cheap (one pass, no allocation beyond error messages).
The alias-bomb/depth bounds are dependency-provided and verified
working (review 002 re-verified) — do not re-implement them; the task
is about *semantic* normalization, not resource limits. ADR-051 is the
decision record to update if the merge-key stance changes behavior.

## Summary

Post-parse YAML normalization at the from_yaml seam: loud duplicate-key rejection (yaml_serde native), merge keys applied (shallow), .inf/.nan + non-representable keys rejected with pointers, scalar keys stringified per YAML 1.2 core schema. Premise correction recorded: serde_json Value itself last-wins on dups - parity contract is YAML-stricter-by-design. ADR-051 section added.