---
id: review-002-import-loudness-cluster
name: Import loudness cluster — oneOf body, self-ref requestBody, siblings, collisions, header precedence, error truncation (OAI-10/14/15/17/19, JS-02/03)
status: pending
depends_on: [review-002-oai11-ref-memoization]
scope: moderate
risk: low
impact: component
level: implementation
tags: [adapters, review-002, from-openapi, from-jsonschema]
---

## Description

Six review-002 minor findings across the two import files, all in the
"unsupported-feature loudness + import robustness" family (the OAI-06
matrix completion). Batched — each is small:

- **OAI-10**: `$ref` sibling keys are silently discarded
  (openapi_spec.rs:396-410). Under 3.1 semantics siblings apply
  alongside the `$ref` (advertise/enforce drift); there is no
  `openapi: 3.1` version gate anywhere. Fix: warn on `$ref` siblings,
  and/or gate `openapi: "3.1*"` like other unsupported features
  (at minimum document the 3.0-only stance).
- **OAI-14**: top-level `oneOf` requestBodies (unconstraining `body`
  contract — import-time gate), `discriminator`, `xml`, `callbacks`,
  `security` blocks silently ignored. Extend the OAI-06 loudness
  matrix: reject-or-warn at import with the established message
  template.
- **OAI-15**: a self-`$ref`'d requestBody resolves to content-less →
  body-less op registered silently (openapi_spec.rs:486-498). Fail
  import with the OAI-04 error shape when a resolved requestBody
  still contains a top-level `$ref` or lacks `content`.
- **OAI-17**: import errors echo unbounded spec-derived strings
  (openapi_spec.rs:264-272 servers locations join; from_openapi.rs
  placeholder/path interpolation). Truncate (first N + count) and cap
  interpolated path/ref strings in `SchemaParse` messages.
- **OAI-19**: declared `in: header` params silently lose to
  `default_headers` and credential headers (forward.rs:169-238 insert
  order). Reject or warn at import when a header param collides with
  a configured `default_headers` key or the auth scheme's header;
  also reject peer-visible header params named `Authorization` on
  authed namespaces.
- **JS-02**: `from_openapi` templates are not validated for balanced
  braces at import (`/x{open` imports, fails per-call INTERNAL) —
  reuse/hoist `from_jsonschema`'s `validate_path_template` into the
  shared path and run it in `build_registration`.
- **JS-03**: `assert_eq!` in library code (`reject_collisions`,
  from_openapi.rs:74-75) — return `Err(AdapterError::internal(…))` or
  zip-iterate and drop the asserts.

## Acceptance Criteria

- [ ] Each item landed with its import-time test (loud-error content
      asserted; sibling-warning case; header-collision warning/reject;
      unterminated-template import failure; no asserts in non-test code)
- [ ] OAI-17: a 100k-path servers-list import error message is
      bounded (test with a large synthetic spec asserting message
      length < a sane cap)
- [ ] The OAI-06 matrix (or its successor doc section) lists the newly
      loud features
- [ ] `cargo test`, `cargo clippy --all-targets -- -D warnings`,
      `cargo fmt --check` pass

## References

- docs/reviews/002-post-remediation-review.md (Part E', OAI-10/14/15/17/19, JS-02, JS-03)
- src/adapters/openapi_spec.rs:396-410, :486-498, :241-273, :314-320, :264-272, :539-573
- src/adapters/from_openapi.rs:69-89 (JS-03), :162-171 (the "body" collision pattern to extend for OAI-19), from_jsonschema.rs (the template validator to hoist)
- tasks/adapters/review-001-openapi-loud-degradation.md (the OAI-06 matrix), tasks/adapters/review-001-openapi-import-integrity.md

## Notes

Sequence after review-002-oai11-ref-memoization (same resolver
function for OAI-10/15 — or rebase-verify). Slice per finding, commit
per finding. The OAI-19 import-time check may not see the assembly
layer's `default_headers` (config lives elsewhere) — if the
import-time surface cannot know, the loud point moves to
first-call-time (warn-once) — implementer documents which.