@precepts/standards 0.1.0

package/standards/integration/standards/api/error-handling.md

@@ -0,0 +1,250 @@
+---
+identifier: "INTG-STD-009"
+name: "API Error Handling"
+version: "1.0.0"
+status: "MANDATORY"
+
+domain: "INTEGRATION"
+documentType: "standard"
+category: "error-handling"
+appliesTo: ["api", "webhooks"]
+
+lastUpdated: "2026-03-28"
+owner: "Integration Architecture Board"
+
+standardsCompliance:
+  iso: []
+  rfc: ["RFC-9457", "RFC-9110", "RFC-2119"]
+  w3c: []
+  other: ["Zalando-RESTful-API-Guidelines", "OWASP-API-Security-Top-10"]
+
+taxonomy:
+  capability: "api-design"
+  subCapability: "error-handling"
+  layer: "contract"
+
+enforcement:
+  method: "automated"
+  validationRules:
+    contentType: "application/problem+json"
+    requiredFields: ["type", "title", "status"]
+  rejectionCriteria:
+    - "Stack traces in error responses"
+    - "Internal implementation details in error messages"
+    - "Non-standard error response format"
+    - "Missing correlation ID in error responses"
+
+dependsOn: ["INTG-STD-004", "INTG-STD-008"]
+supersedes: ""
+---
+
+# Error Handling
+
+## Purpose
+
+All HTTP API error responses **MUST** use the RFC 9457 Problem Details format (`application/problem+json`). This eliminates bespoke error formats, enables machine-readable error processing by clients and AI agents, and prevents information leakage. RFC 9457 obsoletes RFC 7807 and aligns with industry guidelines from Zalando, Microsoft, and Google.
+
+## Rules
+
+### R-1: Content-Type
+
+- All error responses **MUST** use media type `application/problem+json`.
+- Servers **MUST** set `Content-Type: application/problem+json` for all 4xx and 5xx responses carrying a body.
+- Servers **MUST NOT** return errors using `application/json` or any other media type.
+
+### R-2: Required Fields
+
+Every Problem Details response **MUST** include:
+
+| Field           | Type    | Description                                              |
+| --------------- | ------- | -------------------------------------------------------- |
+| `type`          | string  | URI reference identifying the problem type               |
+| `title`         | string  | Short, human-readable summary of the problem type        |
+| `status`        | integer | HTTP status code (**MUST** match actual response status) |
+| `detail`        | string  | Human-readable explanation specific to this occurrence   |
+| `instance`      | string  | URI reference identifying this specific occurrence       |
+| `correlationId` | string  | UUID v4 for end-to-end correlation                       |
+
+### R-3: Recommended Extension Fields
+
+The following fields **SHOULD** be included where applicable:
+
+| Field       | Type   | Description                                    |
+| ----------- | ------ | ---------------------------------------------- |
+| `errorCode` | string | Machine-readable error code (see R-6)         |
+| `timestamp` | string | ISO-8601 UTC timestamp of the error occurrence |
+| `errors`    | array  | Per-field validation errors (see R-5)         |
+
+### R-4: Type URI Requirements
+
+- The `type` field **MUST** be an absolute URI following the pattern `https://{domain}/problems/{error-category}`.
+- Organizations **SHOULD** host human-readable documentation at the `type` URI.
+- When no specific problem type applies, `"about:blank"` **MUST** be used and `title` **SHOULD** match the standard HTTP status phrase from RFC 9110.
+
+### R-5: Validation Error Array
+
+For 400 and 422 responses involving input validation, the response **MUST** include an `errors` array. Each entry **MUST** contain:
+
+| Field     | Type   | Req.         | Description                                               |
+| --------- | ------ | ------------ | --------------------------------------------------------- |
+| `field`   | string | **MUST**     | JSON Pointer (RFC 6901) or dot-notation path to the field |
+| `message` | string | **MUST**     | Human-readable description of the validation failure      |
+| `code`    | string | **SHOULD**   | Machine-readable validation error code                    |
+| `value`   | any    | **MAY**      | The rejected value (**MUST NOT** include sensitive data)   |
+
+### R-6: Machine-Readable Error Codes
+
+- Each problem type **SHOULD** define a unique `errorCode` in `UPPER_SNAKE_CASE`.
+- Error codes **MUST** be stable across releases and **MUST NOT** be removed without a major version increment.
+- Error codes **SHOULD** follow the pattern `{DOMAIN}_{CATEGORY}_{SPECIFIC}` (e.g., `ORDER_VALIDATION_INVALID_QUANTITY`).
+
+### R-7: Correlation ID
+
+- Every error response **MUST** include `correlationId` in the body and `X-Correlation-ID` in the response header; values **MUST** match.
+- If the inbound request includes `X-Correlation-ID`, the server **MUST** propagate that value.
+- If absent, the server **MUST** generate a new UUID v4.
+- The `correlationId` **MUST** appear in all log entries related to the failed request.
+
+### R-8: Status Code Consistency
+
+- The `status` field **MUST** match the HTTP response status code.
+- Servers **MUST** use the most specific status code applicable and **MUST NOT** use generic codes (e.g., 400) when a more specific code (e.g., 422) applies.
+
+### R-9: HTTP Status Code Usage
+
+| Status | Title                 | When to Use                                                                          |
+| ------ | --------------------- | ------------------------------------------------------------------------------------ |
+| 400    | Bad Request           | Malformed syntax, invalid JSON, missing required headers                             |
+| 401    | Unauthorized          | Missing, expired, or malformed authentication credentials                            |
+| 403    | Forbidden             | Valid credentials but insufficient permissions                                       |
+| 404    | Not Found             | Requested resource does not exist                                                    |
+| 409    | Conflict              | State conflict (optimistic locking, duplicate creation)                              |
+| 422    | Unprocessable Content | Well-formed but semantically invalid (business rules, field validation)              |
+| 429    | Too Many Requests     | Rate limit exceeded; **MUST** include `Retry-After` header                           |
+| 500    | Internal Server Error | Unexpected server failure; **MUST NOT** expose internals                             |
+| 502    | Bad Gateway           | Upstream dependency returned an invalid response                                     |
+| 503    | Service Unavailable   | Temporary outage or maintenance; **SHOULD** include `Retry-After`                    |
+
+Use **400** for structurally malformed requests (bad JSON, wrong content type). Use **422** for well-formed requests that violate business rules or field validation.
+
+### R-10: Title Stability
+
+- The `title` field **SHOULD NOT** change between occurrences of the same problem type.
+- Clients **MUST NOT** parse `title` or `detail` for programmatic decisions; use `type`, `status`, and `errorCode` instead.
+
+### R-11: Security Requirements
+
+- Error responses **MUST NOT** include stack traces, exception class names, internal method names, SQL queries, database details, internal hostnames, IP addresses, file paths, or software version numbers.
+- The `detail` field **MUST** describe the problem from the client's perspective, not internal state.
+- For 5xx errors, `detail` **SHOULD** use a generic message and log full diagnostics server-side via `correlationId`.
+- Validation error `value` fields **MUST NOT** echo sensitive data (passwords, tokens, personal identifiers).
+
+### R-12: Retry Guidance
+
+- 429 responses **MUST** include a `Retry-After` header.
+- 503 responses **SHOULD** include a `Retry-After` header when the outage duration is known.
+- Retryable errors **MAY** include a `retryAfterSeconds` integer extension field.
+
+### R-13: Content Negotiation
+
+- If a client sends `Accept: application/problem+json`, the server **MUST** respond with Problem Details JSON.
+- If a client sends `Accept: application/json`, the server **SHOULD** still respond with Problem Details JSON using `Content-Type: application/problem+json`.
+- XML representation (`application/problem+xml`) **MAY** be supported but is not required.
+
+## Examples
+
+### Standard Error Response
+
+```json
+{
+  "type": "https://api.example.com/problems/malformed-request",
+  "title": "Malformed Request",
+  "status": 400,
+  "detail": "The request body contains invalid JSON. Expected a comma at position 42.",
+  "instance": "/logs/errors/a937b-41f2",
+  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
+  "errorCode": "REQUEST_PARSE_INVALID_JSON",
+  "timestamp": "2026-03-28T14:30:00.000Z"
+}
+```
+
+### Validation Error Response
+
+```json
+{
+  "type": "https://api.example.com/problems/validation-error",
+  "title": "Validation Error",
+  "status": 422,
+  "detail": "The request contains 2 validation errors that must be corrected.",
+  "instance": "/logs/errors/f682g-d6h5",
+  "correlationId": "3c6e0b8a-9c0a-45af-9db8-0b2e1f4b5c7d",
+  "errorCode": "REQUEST_VALIDATION_FAILED",
+  "timestamp": "2026-03-28T14:35:00.000Z",
+  "errors": [
+    {
+      "field": "/email",
+      "message": "Must be a valid email address.",
+      "code": "FIELD_FORMAT_INVALID",
+      "value": "not-an-email"
+    },
+    {
+      "field": "/quantity",
+      "message": "Must be greater than zero.",
+      "code": "FIELD_RANGE_BELOW_MINIMUM",
+      "value": -5
+    }
+  ]
+}
+```
+
+## Enforcement Rules
+
+### Gateway-Level
+
+- API gateways **MUST** intercept non-compliant error responses and transform them into valid Problem Details format.
+- API gateways **MUST** strip fields matching sensitive patterns (stack traces, SQL, internal paths).
+- API gateways **MUST** inject `correlationId` and `X-Correlation-ID` if the backend has not provided them.
+
+### Build-Time
+
+- OpenAPI specs **MUST** define `application/problem+json` for all 4xx and 5xx status codes.
+- Contract tests **MUST** validate error responses conform to the Problem Details schema.
+- Static analysis **SHOULD** flag error response definitions that do not reference the Problem Details schema.
+
+### Automated Checks
+
+The following **MUST** be enforced at the API gateway or integration test layer:
+
+1. All 4xx/5xx responses have `Content-Type: application/problem+json`.
+2. Required fields (`type`, `title`, `status`, `detail`, `instance`, `correlationId`) are present.
+3. The `status` field matches the HTTP response status code.
+4. `X-Correlation-ID` header is present and matches body `correlationId`.
+5. Response bodies do not match patterns for stack traces, SQL keywords, or internal hostnames.
+6. Responses with status 400 or 422 reporting field issues include the `errors` array.
+
+### Rejection Criteria
+
+CI/CD **MUST** reject: non-`application/problem+json` errors, missing required fields, sensitive data in response bodies (stack traces, SQL, internal paths, hostnames), and missing or mismatched `X-Correlation-ID` headers.
+
+## References
+
+- [RFC 9457 - Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc9457.html)
+- [RFC 9110 - HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110.html)
+- [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119.html) / [RFC 6901](https://www.rfc-editor.org/rfc/rfc6901.html)
+- [Zalando RESTful API Guidelines](https://opensource.zalando.com/restful-api-guidelines/) / [OWASP Error Handling](https://cheatsheetseries.owasp.org/cheatsheets/Error_Handling_Cheat_Sheet.html)
+
+## Rationale
+
+**Why RFC 9457?** Current IETF standard for HTTP error responses, widely supported by frameworks and gateways, eliminating the cost of bespoke formats.
+
+**Why require all core fields plus correlationId?** `type` enables deterministic branching, `status` survives proxy transformations, `instance` links alerts to occurrences, and `correlationId` is essential for distributed tracing.
+
+**Why strict security rules?** OWASP identifies error information leakage as a common API vulnerability - stack traces, SQL, and hostnames aid targeted exploits.
+
+**Why the errors[] array?** Returning all validation failures at once avoids trial-and-error loops and improves developer experience.
+
+## Version History
+
+| Version | Date       | Change             |
+| ------- | ---------- | ------------------ |
+| 1.0.0   | 2026-03-28 | Initial definition |

package/standards/integration/standards/api/resource-design.md

@@ -0,0 +1,286 @@
+---
+identifier: "INTG-STD-008"
+name: "API Resource Design and Naming"
+version: "1.0.0"
+status: "MANDATORY"
+
+domain: "INTEGRATION"
+documentType: "standard"
+category: "protocol"
+appliesTo: ["api"]
+
+lastUpdated: "2026-03-28"
+owner: "Integration Architecture Board"
+
+standardsCompliance:
+  iso: []
+  rfc: ["RFC-9110", "RFC-9205"]
+  w3c: []
+  other: ["Google-Cloud-API-Design-Guide", "Zalando-RESTful-API-Guidelines", "Microsoft-REST-API-Guidelines"]
+
+taxonomy:
+  capability: "api-design"
+  subCapability: "resource-modeling"
+  layer: "contract"
+
+enforcement:
+  method: "hybrid"
+  validationRules:
+    urlPattern: "^/v[0-9]+/[a-z][a-z0-9-]*(/{[a-z_]+}(/[a-z][a-z0-9-]*)*)*$"
+  rejectionCriteria:
+    - "Verbs in URL path segments"
+    - "Singular nouns for collection endpoints"
+    - "Missing pagination on collection endpoints"
+
+dependsOn: ["INTG-STD-004"]
+supersedes: ""
+---
+
+# Resource Design
+
+## Purpose
+
+This standard defines the required structure for RESTful API resources, URL paths, HTTP method usage, collection patterns, and operation semantics across all integration boundaries. Consistent resource design makes APIs predictable, securable, and machine-governable. Field naming within payloads is governed by INTG-STD-004; this standard covers URL structure, HTTP semantics, and collection-level patterns.
+
+> *Normative language (**MUST**, **MUST NOT**, **SHOULD**, **MAY**) follows RFC 2119 semantics.*
+
+---
+
+## Rules
+
+### R-1: URL Structure
+
+Every API URL **MUST** follow this pattern:
+
+```
+/v{major}/{collection}/{resource_id}/{sub-collection}/{sub_resource_id}
+```
+
+- The version prefix **MUST** be `v` + major version number as the first path segment.
+- Path segments after the version **MUST** alternate between collection names and resource identifiers.
+- Collection path segments **MUST** use plural nouns in kebab-case. They **MUST NOT** contain verbs.
+- Resource identifier path parameter names **MUST** use snake_case (e.g., `{order_id}`).
+- Identifier values **SHOULD** use a type prefix with an opaque string (e.g., `ord_82f3k`).
+- Identifier values **MUST** be URL-safe and **MUST NOT** expose sequential integers as the sole identifier.
+- URL paths **SHOULD NOT** exceed three levels of resource nesting.
+- URLs **MUST NOT** contain trailing slashes or empty path segments.
+- All API paths **MUST** match: `^/v[0-9]+/[a-z][a-z0-9-]*(/{[a-z_]+}(/[a-z][a-z0-9-]*)*)*$`
+
+**Valid URLs:**
+```
+/v1/orders
+/v1/line-items
+/v1/orders/ord_82f3k
+/v1/users/usr_19dk2/addresses/addr_7fj29
+```
+
+**Invalid URLs:**
+```
+/v1/order              # singular
+/v1/getOrders          # verb, camelCase
+/v1/order_items        # snake_case path segment
+/v1/orders/12345       # sequential integer
+/v1/orders/ord_82f3k/  # trailing slash
+```
+
+### R-2: HTTP Method Semantics
+
+APIs **MUST** use HTTP methods per RFC 9110.
+
+| Operation | Method | URL Target | Body | Idempotent | Safe |
+|-----------|--------|------------|------|------------|------|
+| List collection | `GET` | `/v1/resources` | None | Yes | Yes |
+| Get resource | `GET` | `/v1/resources/{id}` | None | Yes | Yes |
+| Create resource | `POST` | `/v1/resources` | Resource | No | No |
+| Full replace | `PUT` | `/v1/resources/{id}` | Complete | Yes | No |
+| Partial update | `PATCH` | `/v1/resources/{id}` | Partial | No* | No |
+| Delete resource | `DELETE` | `/v1/resources/{id}` | None | Yes | No |
+
+*PATCH **SHOULD** be designed to be idempotent where possible.
+
+- `GET` **MUST** be safe and **MUST NOT** accept a request body. Responses **MUST** be cacheable unless marked otherwise.
+- `POST` to a collection **MUST** return `201 Created` with a `Location` header. POST **SHOULD** accept an `Idempotency-Key` header for safe retries.
+- `PUT` **MUST** replace the entire resource and **MUST** be idempotent. Omitted fields **MUST** reset to defaults.
+- `PATCH` **MUST** use JSON Merge Patch (RFC 7396). Only fields present **MUST** be updated; absent fields **MUST** remain unchanged. To null a field, send JSON `null`.
+- `DELETE` **MUST** be idempotent and **MUST NOT** accept a request body. Return `204 No Content` or `200 OK`.
+- `GET` and `DELETE` **MUST NOT** accept a request body. `POST` **MUST NOT** be used for retrieval. `PUT` **MUST NOT** be used for partial updates.
+
+### R-3: Collection Response Envelope
+
+All collection responses **MUST** return a JSON object (never a bare array) with these fields:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `data` | array | **MUST** | The array of resource objects |
+| `pagination` | object | **MUST** | Pagination metadata |
+
+**Valid collection response:**
+```json
+{
+  "data": [
+    { "id": "ord_82f3k", "status": "confirmed" },
+    { "id": "ord_93g4l", "status": "draft" }
+  ],
+  "pagination": {
+    "has_more": true,
+    "next_cursor": "eyJpZCI6Im9yZF85M2c0bCJ9"
+  }
+}
+```
+
+### R-4: Pagination
+
+All collection endpoints **MUST** support pagination. Cursor-based pagination **MUST** be the default. Offset-based pagination (`?page=`, `?offset=`) **MUST NOT** be used.
+
+**Cursor request parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `limit` | integer | Max items to return. **MUST** default to a service-defined value (recommended: 20). **MUST NOT** exceed 100. |
+| `starting_after` | string | Return items after this resource ID |
+| `ending_before` | string | Return items before this resource ID |
+
+`starting_after` and `ending_before` are mutually exclusive; sending both **MUST** return `400 Bad Request`.
+
+**Cursor response fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `has_more` | boolean | `true` if additional items exist beyond this page |
+| `next_cursor` | string or null | Opaque cursor for next page. `null` when `has_more` is `false`. |
+
+Collection endpoints **SHOULD NOT** return `total_count` by default. If required, it **MAY** be opt-in via `?include_total=true`.
+
+### R-5: Filtering and Sorting
+
+Filtering **MUST** use query parameters with snake_case names. Range operators **SHOULD** use suffixed names:
+
+| Suffix | Meaning | Example |
+|--------|---------|---------|
+| (none) | Exact match | `?status=confirmed` |
+| `_gt`, `_gte` | Greater than (or equal) | `?created_at_gt=2026-03-01T00:00:00Z` |
+| `_lt`, `_lte` | Less than (or equal) | `?amount_lte=500` |
+| `_ne` | Not equal | `?status_ne=cancelled` |
+| `_in` | In set (comma-separated) | `?status_in=draft,confirmed` |
+
+Sorting **MUST** use the `sort` query parameter with field names optionally prefixed by `-` for descending. Multiple fields **MUST** be comma-separated. Default sort **MUST** be stable.
+
+### R-6: Field Selection and Expansion
+
+APIs **MAY** support `fields` (comma-separated field names) for sparse fieldsets. The `id` field **MUST** always be included regardless.
+
+APIs **MAY** support `expand` (comma-separated relationship names) to inline related resources. Expansion depth **MUST** be limited to one level - nested expansion **MUST NOT** be supported.
+
+### R-7: Sub-resources
+
+A resource **MUST** be modeled as a sub-resource only when it cannot exist without its parent, is never accessed independently, and shares authorization context with its parent. Otherwise it **SHOULD** be a top-level resource with a foreign key reference.
+
+Singleton sub-resources (one instance per parent) **MUST** use a singular noun, **MUST** support `GET` and `PUT`/`PATCH`, and **MUST NOT** support `POST`, `DELETE`, or list operations independently.
+
+### R-8: Bulk Operations
+
+Bulk operations **MUST** use `POST /v1/{collection}:bulk-{verb}`. The request **MUST** contain an array of identifiers or representations. The response **MUST** return per-item results including individual success or failure. Maximum item count **MUST** be enforced (recommended: 100).
+
+Batch operations (heterogeneous) **SHOULD** be avoided. If required, the endpoint **MUST** be `/v1/batch` and the response **MUST** use `207 Multi-Status`.
+
+### R-9: Long-running Operations
+
+Operations that cannot complete synchronously **MUST** return `202 Accepted` with an `Operation-Location` header pointing to a status monitor resource. The status field **MUST** use one of: `pending`, `running`, `succeeded`, `failed`, `cancelled`. The server **SHOULD** return a `Retry-After` header. On completion, the response **MUST** include `result` (success) or `error` (failure). Cancellation **SHOULD** be supported via `POST /v1/operations/{op_id}:cancel`.
+
+### R-10: Security
+
+- Resource identifiers **MUST NOT** be sequential integers. Use opaque, high-entropy identifiers.
+- Authorization checks **MUST** occur on every request. Sub-resource access **MUST** validate the parent chain.
+- Error responses **MUST NOT** distinguish between "does not exist" and "no access" - return `404` (or `403` consistently) for both.
+- Collection endpoints **MUST** apply authorization filters before pagination.
+- URLs **MUST NOT** contain PII or sensitive data.
+
+### R-11: Content Types
+
+| Operation | Content-Type | Notes |
+|-----------|-------------|-------|
+| Request body (create/update) | `application/json` | **MUST** be the default |
+| PATCH request body | `application/merge-patch+json` | **MUST** for JSON Merge Patch |
+| Response body | `application/json` | **MUST** be the default |
+
+---
+
+## Examples
+
+### Valid API resource structure
+
+```
+GET  /v1/orders                     # List orders (paginated)
+GET  /v1/orders/{order_id}          # Get single order
+POST /v1/orders                     # Create order
+GET  /v1/orders/{order_id}/items    # List items in order
+POST /v1/orders:bulk-cancel         # Bulk action on orders
+```
+
+### Invalid API resource structure
+
+```
+GET  /v1/getOrders                  # Verb in path
+GET  /v1/order/123                  # Singular collection name
+POST /v1/orders/123/cancel          # Action as sub-resource
+GET  /api/v1/orders                 # Redundant /api prefix
+GET  /v1/orders/                    # Trailing slash
+```
+
+## Enforcement Rules
+
+The following **MUST** be rejected at API gateway or design review:
+
+1. **Verbs in URL paths** - path segments containing action words (e.g., `get`, `create`, `delete`).
+2. **Singular collection names** - collection path segments that are not plural.
+3. **Missing pagination** - collection endpoints returning unbounded arrays.
+4. **Offset-based pagination** - use of `page`, `offset`, or `skip` query parameters.
+5. **Sequential integer identifiers** - predictable sequential resource IDs.
+6. **Request body on GET or DELETE** - any GET or DELETE accepting a body.
+7. **PII in URLs** - email addresses, names, or personal data in path segments.
+8. **Bare array responses** - collections returning a JSON array instead of `{"data": [], "pagination": {}}`.
+9. **URL path validation** - all paths **MUST** match: `^/v[0-9]+/[a-z][a-z0-9-]*(/{[a-z_]+}(/[a-z][a-z0-9-]*)*)*$`
+10. **Collection response validation** - `data` **MUST** be an array, `pagination` **MUST** be an object, `pagination.has_more` **MUST** be a boolean.
+11. **POST to collection** - **MUST** return `201`.
+12. **PUT idempotency** - repeated identical requests **MUST** produce the same result.
+
+Enforcement **MUST** occur at two stages: design time (OpenAPI linting) and runtime (API gateway validation).
+
+---
+
+## References
+
+- [RFC 9110 - HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110)
+- [RFC 9205 - Building Protocols with HTTP](https://www.rfc-editor.org/rfc/rfc9205)
+- [RFC 7396 - JSON Merge Patch](https://www.rfc-editor.org/rfc/rfc7396)
+- [Google AIP-121 - Resource-oriented Design](https://google.aip.dev/121)
+- [Zalando RESTful API Guidelines](https://opensource.zalando.com/restful-api-guidelines/)
+- [Microsoft REST API Guidelines](https://github.com/microsoft/api-guidelines)
+- [OWASP API Security - BOLA](https://owasp.org/API-Security/editions/2023/en/0xa1-broken-object-level-authorization/)
+- INTG-STD-004 - Naming Conventions
+
+---
+
+## Rationale
+
+**Resource-oriented design over RPC** - Modeling APIs as resources with standard methods reduces cognitive load; learn one resource, understand them all.
+
+**Cursor-based pagination** - Offset pagination breaks under concurrent writes (items shift between pages). Cursor pagination provides stable traversal at any scale.
+
+**Opaque identifiers** - Sequential integers are trivially enumerable and enable BOLA attacks. Prefixed opaque IDs provide type safety and security.
+
+**Kebab-case URLs, snake_case parameters** - Kebab-case is readable in logs and browsers. Snake_case in parameters aligns with JSON field naming per INTG-STD-004.
+
+**Collection envelope** - `{"data": [], "pagination": {}}` ensures pagination metadata can be added without breaking changes.
+
+**JSON Merge Patch** - Simpler than JSON Patch (RFC 6902) for common partial updates, using natural JSON structure rather than operation arrays.
+
+**Long-running operations as resources** - Treating operations as pollable resources follows the same pattern used throughout the API, avoiding WebSocket complexity.
+
+---
+
+## Version History
+
+| Version | Date       | Change             |
+| ------- | ---------- | ------------------ |
+| 1.0.0   | 2026-03-28 | Initial definition |

package/standards/integration/standards/data-formats/_category_.json

@@ -0,0 +1 @@
+{"label": "Data Formats", "position": 2}