Pitfalls & testing

• Failing a whole batch on one bad record. Reject the single record with problems; apply the rest.
• Treating recordRef as your own id. It is the Consumer’s stable id — store it for upserts; return your id as externalId.
• Embedding/expecting file bytes in the payload. Documents transfer by reference; you fetch them.
• Skipping sha256 verification after downloading a document.
• Omitting aud on the document-resolution JWT, or signing with a key not in your published jwks_uri — the Consumer will (correctly) reject the call.
• Open dynamic registration. Always require a software statement or initial access token.
• Long-lived access tokens. Keep them short; rely on refresh.
• Non-idempotent ingest. Re-delivered batches must not create duplicate students.
• Translating the wrong things. Localize title/description/detail only — never property names, enum const values, or error codes. Translating those breaks mapping and validation on the Consumer.

11. Testing tips

Fastest path: the Playground

Point the SDI Playground harness at your base URL to run the whole flow end-to-end before you write your own test client — it shows the exact request and response for each step, so a failing check tells you precisely where to look. You can also read its reference Provider as a worked example.

• Start with discovery: a Consumer (or curl) should parse your .well-known document and find every endpoint it needs.
• Exercise both the happy path and partial failure: a batch with one valid and one invalid record should return created for one and rejected (with problems) for the other.
• Replay the same batch with the same Idempotency-Key and confirm identical results and no duplicates.
• If you localize, fetch the schema with Accept-Language: sw-KE and an unsupported tag: confirm titles change, Content-Language reflects what you returned (including the default_language fallback), and property names + enum values are byte-for-byte identical across languages.
• For documents, stand up a stub Consumer resolve endpoint that verifies your JWT (issuer + aud + your jwks_uri) and returns a signed URL to a known file; confirm your sha256 check passes and fails correctly on a tampered file.
• Run the steward’s published conformance suite for each level you claim before requesting certification.