OpenAPI spec has broken schema references

[tacman]

Issue: OpenAPI spec (swagger.json) has broken schema references

The OpenAPI spec at https://catalog.archives.gov/api/v2/swagger.json has several issues that prevent code generation tools (like JanePHP) from working:

1. Case Mismatch in Schema References

Some $ref values use different case than the actual schema names:

Ref in spec	Schema exists as
#/components/schemas/ContributionStat	contributionStat (lowercase)
#/components/schemas/ContributionRecord	contributionRecord
#/components/schemas/MetaData	metaData
#/components/schemas/User	user

Fix: Update all refs to match exact schema names.

2. Missing Schema Definitions

~250+ $ref values point to schemas that dont exist in /components/schemas/. Examples:

• Field-level types: naId, title, levelOfDescription, date, name
• Parameters referenced as schemas: paramQuery, paramLimit, paramPage, paramNaId
• The /announcements endpoints reference Announcement schema which does not exist

Fix: Either add these as proper schema definitions, or remove the broken refs.

3. Missing Response Schemas

Endpoints like /records/search and /transcriptions/search return:

{"200": {"description": "A body of response data containing full record objects if any were found."}}

No content/application/json/schema is defined, so code generators cant create typed DTOs for responses.

Fix: Add proper response schemas describing the actual JSON structure returned.

Reproduction

curl -s "https://catalog.archives.gov/api/v2/swagger.json" > openapi.json
vendor/bin/jane-openapi generate
# Error: Json Pointer /components/schemas/ContributionStat references a nonexistent value

Environment

• OpenAPI version: 3.0.0
• API version: v2 (NextGen Catalog API 0.2.0)

---

This is blocking PHP SDK generation using JanePHP and similar tools. The API itself works fine - its just the OpenAPI spec that needs cleanup.