> For the complete documentation index, see [llms.txt](https://specs.govstack.global/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://specs.govstack.global/ai-readiness/6-examples.md). # 6 Examples ### 6.1 Scope: The "God Service" vs. Single Capability **The Rule:** A service must own a single domain of logic. If you cannot describe the service function without using the word "and" (e.g., "Login and Tax"), the boundary is too broad. **BAD: The Ambiguous Monolith** * **Problem:** Multiple, unrelated domains mixed in one endpoint (e.g., mixing user logic with business processing). * **AI Consequence:** The Agent cannot determine the scope or intent of the service, leading to hallucination risks. ``` // POST /api/handleStuff // Description: Missing. { "action": "register_and_notify", // Mixing logic "data": { ... }, // Generic object with no schema "misc_flag": true } ``` **GOOD: The Bounded Context** * **Solution:** One purpose per API. The service handles exactly one coherent capability. * **AI Benefit:** The agent can instantly identify which endpoint handles a specific life event. ``` // POST /benefits/unemployment/claims { "openapi": "3.1.0", "paths": { "/claims": { "post": { "summary": "Submit Unemployment Claim", "description": "Creates a new claim for a specific citizen context.", "operationId": "submitClaim", "tags": ["Unemployment"] } } } } ``` ### 6.2 Data Models: Vague Inputs vs. Explicit Types **The Rule:** Architects must strictly avoid free-text string fields for data that has a finite set of valid values. **BAD: The "Stringly Typed" Interface** * **Problem:** Inputs are vague with no clear patterns. Almost everything is optional (nillable). * **AI Consequence:** Leads to "hallucinations" where the AI invents plausible but non-existent status codes (e.g., "Partially\_OK") because the rules aren't strict. ``` { "status": "string", // Could be anything? "date": "string", // DD/MM/YYYY? YYYY-MM-DD? "file": "string" // Base64? URL? S3 bucket? } ``` **GOOD: Deterministic Types & Enums** * **Solution:** Define strict types, enums, patterns, and required fields using OpenAPI 3.1 standards. * **AI Benefit:** Reduces the "search space" for the agent, making invalid states unrepresentable. ``` { "properties": { "status": { "type": "string", "enum": ["PENDING", "APPROVED", "REJECTED"] // Strict bounds }, "submissionDate": { "type": "string", "format": "date-time" // ISO 8601 enforced }, "evidenceDocument": { "type": "string", "contentMediaType": "application/pdf", // Explicit MIME type "format": "binary" } }, "required": ["status", "submissionDate"] } ``` ### 6.3 Error Handling: Ambiguity vs. Structured Logic **The Rule:** When an AI agent encounters a roadblock, the system must provide explicit, machine-readable instructions on how to resolve it. **BAD: The "False Success"** * **Problem:** Responses mix success data and error fields. The HTTP status is 200 OK, but the body contains an error. * **AI Consequence:** The automation fails to detect the failure or hallucinates a workaround because it lacks structured feedback. ``` // HTTP 200 OK (Misleading Status) { "success": false, "errorMsg": "Something went wrong", // Vague text "data": null } ``` **GOOD: RFC 9457 Structured Errors** * **Solution:** Always return standard status codes and structured Problem Details (RFC 9457). * **AI Benefit:** The agent can parse the error logic programmatically and apply a specific fix (e.g., reformatting a phone number). ``` // HTTP 400 Bad Request { "type": "https://api.gov/errors/invalid-format", "title": "Invalid Identification Number", "detail": "The ID number must be exactly 11 digits.", "instance": "/claims/12345/id", "invalid-params": [ { "name": "national_id", "reason": "must match regex ^[0-9]{11}$" } ] } ``` ### 6.4 Naming: Inconsistency vs. Documentation **The Rule:** The API Contract is the primary product interface for machine agents. **BAD: The Linguistic Mix** * **Problem:** Naming is inconsistent (mixing local language + English, different casing styles). * **AI Consequence:** Confusing to map; requires "guessing" the intent of fields. ``` { "Synniaeg": "1990-01-01", // Local Language mixed in "firstName": "John", // English camelCase "LAST_NAME": "DOE" // English CONSTANT_CASE } ``` **GOOD: Consistent Semantics** * **Solution:** Use one language and style. Include short descriptions for every field. * **AI Benefit:** Ensures the machine agent can distinguish between unrelated tasks despite underlying complexity ``` { "properties": { "dateOfBirth": { "type": "string", "format": "date", "description": "The official date of birth as recorded in the population registry." }, "firstName": { "type": "string", "description": "Given name." }, "lastName": { "type": "string", "description": "Family name." } } } ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://specs.govstack.global/ai-readiness/6-examples.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.