Add A039 to OAS

[TomKinghorn]

Summary

• ✨ New Feature

Adds the A039 endpoint to the OAS and sandbox.

Reviews Required

• Dev
• Test
• Tech Author
• Product Owner

Review Checklist

ℹ️ This section is to be filled in by the reviewer.

• I have reviewed the changes in this PR and they fill all or part of the acceptance criteria of the ticket, and the code is in a mergeable state.
• If there were infrastructure, operational, or build changes, I have made sure there is sufficient evidence that the changes will work.
• I have ensured the changelog has been updated by the submitter, if necessary.

[Copilot]

🟡 Changes recommended

The new A039 contract/sandbox/tests have several concrete inconsistencies (notably around shared R4 responses/OperationOutcome shape and the Location header semantics) that should be resolved before approval.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds the A039 “Upload file to document store” (FHIR R4) operation into the e-RS API contract and wires up a corresponding sandbox endpoint + sandbox tests, aligning with this repo’s pattern of keeping OAS, sandbox fixtures, and pytest suites in step.

Changes:

• Adds /R4/Binary POST to the root OpenAPI spec and introduces the A039 endpoint definition.
• Implements a sandbox handler and mock response provider mapping for the new R4 route.
• Adds sandbox fixtures and a new pytest sandbox test suite for A039.

File summaries

File	Description
tests/sandbox/r4/test_a039_upload_attachment.py	New sandbox tests for A039 success scenarios across supported MIME types and a no-payload scenario.
specification/e-referrals-service-api.yaml	Adds /R4/Binary POST path ref for A039.
specification/components/r4/schemas/endpoints/a039-upload-file-to-document-store.yaml	New endpoint contract documentation and response wiring for A039.
specification/components/r4/schemas/responses/uploadFileToDocumentStore/200Response.yaml	Defines the A039 200 response shape and headers.
specification/components/r4/schemas/responses/uploadFileToDocumentStore/401Response.yaml	Adds a per-endpoint 401 response (but shared R4 responses already exist).
specification/components/r4/schemas/responses/uploadFileToDocumentStore/403Response.yaml	Adds a per-endpoint 403 response (but shared R4 responses already exist).
specification/components/r4/schemas/responses/uploadFileToDocumentStore/406Response.yaml	Adds a per-endpoint 406 response (but shared R4 responses already exist).
specification/components/r4/schemas/responses/uploadFileToDocumentStore/415Response.yaml	Adds a per-endpoint 415 response (but shared R4 responses already exist).
specification/components/r4/schemas/responses/uploadFileToDocumentStore/422Response.yaml	Adds a per-endpoint 422 response definition for upload validation failures.
specification/components/r4/schemas/responses/uploadFileToDocumentStore/429Response.yaml	Adds a per-endpoint 429 response (but shared R4 responses already exist).
specification/components/r4/schemas/responses/uploadFileToDocumentStore/500Response.yaml	Adds a per-endpoint 500 response (but shared R4 responses already exist).
specification/components/r4/schemas/responses/uploadFileToDocumentStore/503Response.yaml	Adds a per-endpoint 503 response (but shared R4 responses already exist).
sandbox/src/routes/r4/uploadFileToDocumentStore.js	Implements the sandbox POST /FHIR/R4/Binary handler for A039.
sandbox/src/routes/r4/services/mockResponseProvider.js	Adds response mapping for A039 including Location/Content-Disposition generation.
sandbox/src/routes/index.js	Registers the new R4 A039 route.
sandbox/src/mocks/r4/uploadFileToDocumentStore/responses/BinaryResource.json	Adds the R4 Binary example fixture used by sandbox/OAS.
sandbox/src/mocks/r4/uploadFileToDocumentStore/responses/OperationOutcome-401.json	Adds error fixture for A039 (currently STU3-profiled).
sandbox/src/mocks/r4/uploadFileToDocumentStore/responses/OperationOutcome-403.json	Adds error fixture for A039 (currently STU3-profiled).
sandbox/src/mocks/r4/uploadFileToDocumentStore/responses/OperationOutcome-422.json	Adds error fixture for A039 (currently STU3-profiled).
sandbox/src/mocks/r4/uploadFileToDocumentStore/responses/OperationOutcome-503.json	Adds error fixture for A039 (currently STU3-profiled).
sandbox/src/mocks/r4/uploadFileToDocumentStore/requests/upload.txt	Adds a test upload payload used by pytest.
sandbox/src/app.js	Extends sandbox CORS allowed headers to include new file headers.
proxies/sandbox/apiproxy/policies/AssignMessage.AddCors.xml	Extends Apigee sandbox CORS allow-headers list for new file headers.

Review details

• Files reviewed: 23/23 changed files
• Comments generated: 7
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[TomKinghorn]

Done

[kevinmason-nhs]

Seems like you are missing the example files for the specification/components/r4/schemas/responses/.*.yaml files

[TomKinghorn]

Seems like you are missing the example files for the specification/components/r4/schemas/responses/.*.yaml files

I’ve re-checked all current specification/components/r4/schemas/responses/**/*.yaml example $refs in this branch, and they all resolve to existing files under specification/components/r4/examples/.

For A039 specifically, the active response schemas now reference:

• .../uploadFileToDocumentStore/200Response.yaml -> .../examples/uploadFileToDocumentStore/responses/BinaryResource.json
• .../uploadFileToDocumentStore/422Response.yaml -> .../examples/uploadFileToDocumentStore/responses/OperationOutcome-422.json

So there shouldn’t be any missing example files in the current state.