Why it's built this way
Every codebase has load-bearing decisions that look arbitrary until someone explains them. This section is those explanations — short, plain-language accounts of the three decisions the whole SDK rests on. Each page states the decision, the reasons, and what it means for the code you write; each links to its Architecture Decision Record (ADR) in the ADR catalog, which is the primary source when you want the deeper technical why and how, the alternatives considered, and the trade-offs accepted.
Read these when a convention feels like friction — the answer to "why won't review let me just…" is almost always one of these three.
The decisions
| The question you were about to ask | The short answer | Deep dive |
|---|---|---|
| "Why is everything hand-written when Kiota has a generator?" | ServiceNow publishes no reliable OpenAPI specs, and its response shapes need human judgment — so the repo hand-writes the surface on Kiota's runtime, and enforces generator-grade uniformity by convention instead. | Why hand-written on Kiota? · ADR 003 |
| "Why aren't models just structs?" | A struct field can't tell "the instance sent an empty value" from "the instance didn't send this field" — a backing store can, and it dirty-tracks so Patch bodies only carry what you actually set. | Why aren't models plain structs? · ADR 002 |
"Why can't I just errors.New here?" | v1 had hundreds of similar-but-different error strings, which broke errors.Is for every consumer. Shared sentinels and one status-code mapping fixed that — a fresh errors.New reintroduces the bug. | Why sentinel errors everywhere? · ADR 001 |
Making a decision of your own
Significant design changes follow the same lightweight norm that produced these pages:
- Write the ADR in the ADR catalog under
website/docs/contributing/adrs/— context, decision, consequences, alternatives considered. The ADR is the primary source and the artifact reviewers evaluate; its index page explains numbering and registration. - Add (or update) the readable summary here — a short page in the shape of the three above: the decision, the why, and "what to do in new code," linking back to the ADR.
If you're not sure a change rises to ADR level, open an issue and ask — that conversation is cheaper than the rework either way.