Build an SDI Provider with AI

You can build SDI support into your School Management System with an AI coding agent — Claude Code, Cursor, GitHub Copilot, or any agent that can read a URL and edit your codebase. The prompt below is written for exactly that: it points the agent at the canonical, live specification, has you fill in a few details about your stack, and walks it through building a conformant Provider in the right order.

Because the prompt links to the standard by URL instead of pasting a copy, the agent always works against the current spec and the real JSON Schemas — there is no stale snapshot to drift out of date.

How to use it

1. Copy the prompt below into your AI coding agent, inside your SMS codebase.
2. Replace the {{…}} placeholders in Step 2 with your stack and context. The agent will ask if you leave any blank.
3. Let it read the spec and propose a plan before it writes code, then build endpoint by endpoint.
4. When it’s done, validate end-to-end in the Playground.

The prompt

You are an expert backend engineer. Your task is to implement an SDI Provider — the Provider
side of the Student Data Interoperability (SDI) standard — inside an existing School Management
System (SMS).

SDI lets an admissions system (the "Consumer") push an admitted applicant into an SMS (the
"Provider", which you are building) as a student record, over a small OAuth 2.0–secured HTTP
interface. You are implementing the server that the Consumer calls.

## Step 1 — Read the standard before writing any code

These URLs are the single source of truth. Fetch and read them first. Do not rely on prior
knowledge of SDI, and do not invent endpoints, field names, headers, or behaviours that are
not in the specification.

- Standard (the normative spec):        https://sdi.admissio.app/standard/
- Provider guide (worked examples):     https://sdi.admissio.app/guide/introduction/
- Canonical JSON Schemas (the wire contract):
  - https://sdi.admissio.app/schemas/1.0/envelope.json
  - https://sdi.admissio.app/schemas/1.0/document-descriptor.json

Treat every MUST / SHOULD / MAY as an RFC 2119 requirement. Where your assumptions and the
standard disagree, the standard wins — re-read the relevant section rather than guessing.

## Step 2 — Understand my system, then plan

My stack and context:
- Language / framework:          {{e.g. Node.js + Fastify, Laravel, Django, Spring Boot}}
- Database / ORM:                {{e.g. PostgreSQL + Prisma}}
- How students are stored today: {{the model/table an incoming record maps to}}
- Public base URL of the SMS:    {{e.g. https://sms.example.edu}}
- Existing auth/OAuth, if any:   {{describe it, or say "none"}}

If any of this is missing or unclear, ask me before implementing. Then give me a short
implementation plan and wait for my confirmation before writing code.

## Step 3 — Implement a conformant Provider

Build these in order, matching the standard exactly:

1. Discovery — GET /.well-known/sdi-configuration (HTTPS, unauthenticated) advertising your
   endpoints, supported OAuth grants, scopes, capabilities, and contract version.
2. OAuth 2.0 — at least one grant working end-to-end; short-lived, scoped access tokens;
   return 403 on insufficient scope; rotate refresh tokens with reuse detection if you issue them.
3. Field schema — GET {schema_endpoint} returning a JSON Schema (Draft 2020-12) of the fields
   you expect, tagged with the contract version.
4. Ingest — POST {ingest_endpoint} that validates the envelope against the canonical schema,
   validates each record against your field schema, applies the valid records even when others
   fail, returns per-record results, upserts by recordRef (no duplicates), and is idempotent on
   Idempotency-Key + recordRef.
5. Document resolution (only if you accept documents) — fetch bytes by calling the descriptor's
   resolveUrl with a signed JWT assertion whose `aud` is that resolveUrl, then verify the sha256
   of what you downloaded.

Apply throughout:
- All endpoints are HTTPS; tokens travel only in the Authorization header.
- Errors use application/problem+json; honour Idempotency-Key and Retry-After.
- Never translate property names, enum values, or error `code`s. If you localize, honour
  Accept-Language and set Content-Language + Vary: Accept-Language, falling back to the
  Provider's default language.
- Follow my codebase's existing conventions, layering, and data-access patterns. Don't add a
  dependency without telling me why.

## Step 4 — Prove it conforms

Work against the conformance checklist: https://sdi.admissio.app/guide/conformance/
Write tests for each endpoint. When the implementation is ready, validate it end-to-end with
the SDI Playground (https://sdi-playground.admissio.app): point its harness at my base URL and
make every step — discover → authorize → schema → map → push → documents — pass.

Deliver the code, the tests, and a short note on anything in the spec you implemented only
partially or deferred, and why.

What to do next

• Don’t have a tech stack picked yet? Read the Provider guide first — it shows exactly what each endpoint looks like, with copy-pasteable examples, so you can review the agent’s output against a known-good reference.
• Building documents support? Point the agent at §10 — Documents; resolution is the one place where you call the Consumer, which is easy to get backwards.
• Ready to verify? The Playground runs the whole conformance flow against your live base URL and shows the request and response for every step — it’s the fastest way to find the gap between “looks done” and “actually conformant”.

Note

Once your Provider passes, get listed in the SDI Provider directory so Consumers can find you, and add the Supports SDI badge to your product.