@precepts/standards 0.1.0

package/standards/integration/standards/events/event-envelope.md

@@ -0,0 +1,270 @@
+---
+identifier: "INTG-STD-015"
+name: "Event Envelope Standard"
+version: "1.0.0"
+status: "MANDATORY"
+
+domain: "INTEGRATION"
+documentType: "standard"
+category: "protocol"
+appliesTo: ["events", "streaming", "webhooks"]
+
+lastUpdated: "2026-03-28"
+owner: "Integration Architecture Board"
+
+standardsCompliance:
+  iso: []
+  rfc: []
+  w3c: []
+  other: ["CNCF-CloudEvents-v1.0.2"]
+
+taxonomy:
+  capability: "event-driven"
+  subCapability: "event-envelope"
+  layer: "contract"
+
+enforcement:
+  method: "automated"
+  validationRules:
+    requiredAttributes: ["specversion", "id", "source", "type"]
+    specversion: "1.0"
+    sourceFormat: "URI-reference"
+    idUniqueness: "unique-per-source"
+  rejectionCriteria:
+    - "Missing required CloudEvents context attributes"
+    - "Invalid specversion value"
+    - "Non-URI source attribute"
+    - "Duplicate event ID from same source"
+
+dependsOn: ["INTG-STD-004", "INTG-STD-005"]
+supersedes: ""
+---
+
+# Event Envelope
+
+## Purpose
+
+This standard mandates **CloudEvents v1.0.2** as the universal event envelope for all events produced, consumed, or relayed across integration boundaries. Without a uniform envelope, each team invents its own metadata schema, making cross-system correlation, schema evolution, and observability prohibitively expensive. CloudEvents - a CNCF graduated specification - provides a vendor-neutral, protocol-agnostic envelope with broad ecosystem support (Knative, Azure Event Grid, Amazon EventBridge, Google Eventarc).
+
+> *Normative language (**MUST**, **MUST NOT**, **SHOULD**, **MAY**) follows RFC 2119 semantics.*
+
+---
+
+## Rules
+
+### R-1: Mandatory CloudEvents Adoption
+
+All events crossing a service boundary **MUST** use the CloudEvents v1.0.2 envelope. The `specversion` attribute **MUST** be `"1.0"`. Non-conforming events **MUST** be rejected by gateways, brokers, and consumers.
+
+### R-2: Required Context Attributes
+
+Every CloudEvent **MUST** include these four context attributes:
+
+| Attribute | Type | Constraint | Description |
+|-----------|------|------------|-------------|
+| `specversion` | String | Exactly `"1.0"` | CloudEvents specification version |
+| `id` | String | Non-empty; unique within scope of `source` | Event identifier; UUID v4 or ULID **RECOMMENDED** |
+| `source` | URI-reference | Non-empty; absolute URI **RECOMMENDED** | Identifies the producing system and context |
+| `type` | String | Non-empty; reverse-DNS prefix **REQUIRED** | Describes the kind of occurrence |
+
+The combination of `source` + `id` **MUST** be globally unique for distinct events. A producer **MAY** reuse the same `id` when re-delivering the same logical event (idempotency).
+
+### R-3: Recommended Context Attributes
+
+Producers **SHOULD** include the following optional attributes:
+
+| Attribute | Type | Constraint | Recommendation |
+|-----------|------|------------|----------------|
+| `time` | Timestamp | RFC 3339, UTC (`Z` suffix) | **SHOULD** be included for audit trail. **MUST** use UTC per INTG-STD-002 when present. |
+| `datacontenttype` | String | RFC 2046 media type | **SHOULD** be included when data is present. Defaults to `application/json` when omitted. |
+| `dataschema` | URI | Absolute URI | **SHOULD** be included for schema-governed events. **MUST** point to a versioned schema endpoint. |
+| `subject` | String | Non-empty | **SHOULD** be included when the event pertains to a specific resource within the source. |
+
+### R-4: Event Type Naming
+
+Event types **MUST** follow INTG-STD-004 (Naming Standard):
+
+- **MUST** use reverse-DNS prefix rooted at the organization domain.
+- **MUST** follow the pattern: `{reverse-dns}.{domain}.{entity}.{action}[.{version}]`
+- **MUST** use lowercase with dots as separators.
+- A version suffix (e.g., `.v2`) **SHOULD** be appended for breaking schema changes.
+
+### R-5: Source Attribute Formatting
+
+The `source` attribute **MUST** be a valid URI-reference per RFC 3986. Producers **SHOULD** use absolute URIs. The source **MUST** identify the producing system and **MAY** include a path to narrow context. The source **MUST NOT** expose internal hostnames, IP addresses, port numbers, or infrastructure identifiers (see R-14).
+
+### R-6: Extension Attributes
+
+Extension attribute names **MUST** contain only lowercase ASCII letters (`a`-`z`) and digits (`0`-`9`), with a recommended maximum length of 20 characters.
+
+Recommended extensions:
+
+| Extension | Source Specification | Purpose |
+|-----------|---------------------|---------|
+| `traceparent` | W3C Trace Context | Distributed tracing. Producers **SHOULD** propagate from the originating request. |
+| `tracestate` | W3C Trace Context | Vendor-specific tracing data. **SHOULD** accompany `traceparent`. |
+| `partitionkey` | CloudEvents Partitioning | Ordered delivery within a partition. **SHOULD** be set for causally ordered events. |
+| `sequence` | CloudEvents Sequence | Event ordering from a source. **MAY** be used with `partitionkey`. |
+
+Custom extensions **MUST** be namespaced to avoid collisions (e.g., `examplecorrelationid`). Custom extensions **MUST NOT** redefine semantics of documented CloudEvents extensions. Intermediaries **SHOULD** forward all extension attributes, even unrecognized ones.
+
+### R-7: Structured Content Mode
+
+In structured mode, the entire CloudEvent **MUST** be serialized as a single JSON object per the CloudEvents JSON Format. The transport content-type **MUST** be `application/cloudevents+json; charset=utf-8`. JSON payloads **MUST** be embedded directly in `data` (not string-escaped). Binary payloads **MUST** use `data_base64` instead. The `data` and `data_base64` fields **MUST NOT** both be present.
+
+### R-8: Binary Content Mode
+
+In binary mode, context attributes **MUST** be mapped to transport-native headers and the data payload **MUST** occupy the message body directly. For HTTP, headers use the `ce-` prefix. For Kafka, headers use the `ce_` prefix with UTF-8 encoded values. The transport content-type header **MUST** reflect the actual data media type. The `datacontenttype` attribute **MUST NOT** appear as a separate header in HTTP binary mode.
+
+### R-9: Content Mode Selection
+
+| Transport | Default Mode | Guidance |
+|-----------|-------------|----------|
+| HTTP (webhooks, REST callbacks) | Structured | Binary **MAY** be used when payload size dominates and header inspection is not needed. |
+| Kafka | Structured | Binary **MAY** be used on high-throughput internal topics with tightly coupled consumers. |
+| AMQP | Binary | Leverages AMQP application properties for context attributes. |
+| MQTT | Structured | **MUST** use structured for MQTT v3.1 (no user-defined headers). MQTT v5 **MAY** use binary. |
+
+Producers **MUST** document which content mode they emit in their API or AsyncAPI definition.
+
+### R-10: Batch Delivery
+
+Batch delivery **MUST** use the CloudEvents JSON Batch Format. The content-type **MUST** be `application/cloudevents-batch+json; charset=utf-8`. The body **MUST** be a JSON array of complete CloudEvents. An empty batch **MUST** be `[]`. Each event **MUST** independently satisfy all attribute requirements. Consumers **MUST NOT** assume ordering unless events share the same `partitionkey` and include `sequence` values.
+
+A single batch **MUST NOT** exceed 1 MiB unless producer and consumer have an explicit bilateral agreement. Producers **SHOULD** target 100 events or fewer per batch.
+
+### R-11: Event Size Constraints
+
+| Constraint | Limit | Rationale |
+|-----------|-------|-----------|
+| Single event (envelope + data) | **MUST NOT** exceed 256 KiB | Lowest common denominator across major brokers and webhook receivers |
+| Context attributes only | **SHOULD NOT** exceed 4 KiB | Keep headers lightweight for binary mode |
+| `data` payload | **SHOULD NOT** exceed 252 KiB | Envelope overhead budget |
+
+Events exceeding 256 KiB **MUST** use the claim-check pattern: store the payload externally and include a retrieval URI in the `data` field with `claimCheckUri` and `claimCheckContentType` fields.
+
+### R-12: HTTP Protocol Binding
+
+HTTP-bound CloudEvents **MUST** comply with the CloudEvents HTTP Protocol Binding v1.0.2. Events **MUST** be sent as HTTP POST requests. Receivers **MUST** return `2xx` for successfully received events. A `429` response **MUST** trigger sender-side backoff. A `5xx` response **SHOULD** trigger retry with exponential backoff. Senders **SHOULD** support the CloudEvents webhook validation handshake (HTTP OPTIONS with `WebHook-Request-Origin`).
+
+### R-13: Kafka Protocol Binding
+
+Kafka-bound CloudEvents **MUST** comply with the CloudEvents Kafka Protocol Binding v1.0.2. The Kafka message key **SHOULD** be set to the `partitionkey` extension value when present, or to the `subject` attribute, to colocate related events. Producers **MUST** set `partitionkey` when causal ordering is required.
+
+### R-14: Security - Metadata Hygiene
+
+Event envelope metadata **MUST NOT** leak internal infrastructure details:
+
+- `source` **MUST NOT** contain internal hostnames, private IPs, container/pod identifiers, or internal ports.
+- Extension attributes **MUST NOT** carry credentials, tokens, session identifiers, or PII.
+- `dataschema` **MUST** be reachable only from authorized networks or **MUST** be a logical identifier (URN).
+- Gateways at trust boundaries **SHOULD** validate and sanitize envelope attributes before forwarding externally.
+
+### R-15: Auditability
+
+- Producers **MUST** set `id` to a value traceable in the producing system's logs.
+- Producers **SHOULD** set `time` for temporal correlation and `traceparent` for distributed trace correlation.
+- Consumers **MUST** log `id`, `source`, `type`, and `time` upon receipt.
+- The combination of `source` + `id` + `time` **MUST** be sufficient to locate the originating event in producer logs.
+
+### R-16: Allowed Serialization Formats
+
+The CloudEvents JSON Event Format **MUST** be the default serialization. All implementations **MUST** support it. Producers and consumers **MAY** use CloudEvents Protobuf or Avro formats by bilateral agreement, but **MUST** still carry all required context attributes.
+
+---
+
+## Examples
+
+### Valid Event - Structured Content Mode
+
+```json
+{
+  "specversion": "1.0",
+  "id": "01HZX3KQVB8E72GQJHF5RM6YWN",
+  "source": "//orders.example.com/checkout",
+  "type": "com.example.order.created",
+  "time": "2026-03-28T14:22:31.482Z",
+  "datacontenttype": "application/json",
+  "dataschema": "https://schemas.example.com/orders/created/v1.json",
+  "subject": "order-8842",
+  "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
+  "data": {
+    "orderId": "order-8842",
+    "customerId": "cust-1029",
+    "totalAmount": { "value": "149.99", "currency": "USD" }
+  }
+}
+```
+
+### Invalid Event - Missing Required Attributes
+
+The following event is **non-compliant** and **MUST** be rejected:
+
+```json
+{
+  "id": "evt-100",
+  "type": "OrderCreated",
+  "data": { "orderId": "order-100" }
+}
+```
+
+**Violations:** Missing `specversion` (required). Missing `source` (required). `type` uses PascalCase without reverse-DNS prefix (violates R-4).
+
+---
+
+## Enforcement Rules
+
+### Gateway Enforcement
+
+API gateways and event brokers at trust boundaries **MUST** enforce:
+
+1. **Ingress validation** - All required context attributes present and well-formed (`specversion` matches `^1\.0$`; `id` is non-empty; `source` is a valid URI-reference; `type` matches `^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*(-[a-z0-9]+)*){3,}$`).
+2. **Source sanitization** - Reject `source` values matching internal infrastructure patterns (private IPs, `.internal`, `.local`, `localhost`, `k8s://`).
+3. **Size enforcement** - Reject events exceeding 256 KiB with HTTP 413 or equivalent.
+4. **Time validation** - When present, `time` **MUST** match RFC 3339 UTC format (`^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?Z$`).
+5. **Extension name validation** - Extension attribute names **MUST** match `^[a-z][a-z0-9]{0,19}$`.
+
+### Producer Enforcement
+
+Build pipelines **SHOULD** include a CloudEvents linting step validating required attributes, `source`/`type` naming per INTG-STD-004, and approved extension names.
+
+### Consumer Enforcement
+
+Consumers **MUST** reject events missing any required context attribute, log `id`/`source`/`type`/`time` of every received event, and forward unrecognized extension attributes when re-emitting.
+
+---
+
+## References
+
+| Reference | URI |
+|-----------|-----|
+| CloudEvents Specification v1.0.2 | https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md |
+| CloudEvents JSON Event Format v1.0.2 | https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/formats/json-format.md |
+| CloudEvents HTTP Protocol Binding v1.0.2 | https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/http-protocol-binding.md |
+| CloudEvents Kafka Protocol Binding v1.0.2 | https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/kafka-protocol-binding.md |
+| W3C Trace Context | https://www.w3.org/TR/trace-context/ |
+| INTG-STD-004 - Naming Standard | Internal |
+
+---
+
+## Rationale
+
+**Why CloudEvents over a custom envelope?** CloudEvents is the only CNCF graduated event envelope specification with broad industry adoption across Azure Event Grid, Amazon EventBridge, Google Eventarc, and Knative. A custom envelope would forgo ecosystem compatibility and impose a perpetual translation tax.
+
+**Why structured mode as default?** Structured mode keeps envelope and data together as a single unit, eliminating header-body mismatches during transport hops. Binary mode is permitted for documented performance-sensitive paths.
+
+**Why the 256 KiB size limit?** This is the lowest common denominator across major event infrastructure. The claim-check pattern provides an escape hatch for large payloads.
+
+**Why prohibit internal topology in source?** Event metadata flows across trust boundaries - a `source` containing internal hostnames or IPs reveals cloud provider, VPC structure, and service ports to external consumers.
+
+**Why `time` is SHOULD rather than MUST?** Some producers (legacy adapters, IoT gateways) cannot guarantee accurate clocks. Systems requiring strict temporal ordering should use the `sequence` extension.
+
+**Why ULID or UUID v4 for event IDs?** Both provide strong uniqueness without centralized coordination. ULIDs add temporal sortability. Sequential integers are discouraged as they require coordination and leak volume information.
+
+---
+
+## Version History
+
+| Version | Date       | Change             |
+| ------- | ---------- | ------------------ |
+| 1.0.0   | 2026-03-28 | Initial definition |

package/standards/integration/standards/foundational/_category_.json

@@ -0,0 +1 @@
+{"label": "Foundational", "position": 1}

package/standards/integration/standards/foundational/naming-conventions.md

@@ -0,0 +1,334 @@
+---
+identifier: "INTG-STD-004"
+name: "Integration Naming Conventions"
+version: "1.0.0"
+status: "MANDATORY"
+
+domain: "INTEGRATION"
+documentType: "standard"
+category: "naming"
+appliesTo: ["api", "events", "a2a", "files", "mcp", "webhooks", "grpc", "graphql", "batch", "streaming"]
+
+lastUpdated: "2026-03-28"
+owner: "Integration Architecture Board"
+
+standardsCompliance:
+  iso: []
+  rfc: ["RFC-9110", "RFC-9457"]
+  w3c: []
+  other: ["Google-AIP-140", "Google-AIP-190", "Zalando-RESTful-API-Guidelines"]
+
+taxonomy:
+  capability: "naming"
+  subCapability: "conventions"
+  layer: "contract"
+
+enforcement:
+  method: "automated"
+  validationRules:
+    fieldNames: "snake_case"
+    urlPaths: "kebab-case"
+    eventTypes: "dot.notation.past.tense"
+  rejectionCriteria:
+    - "Mixed case conventions within a single API"
+    - "Verbs in URL path segments"
+    - "Abbreviations without prior approval"
+
+dependsOn: []
+supersedes: ""
+---
+
+# Naming Conventions
+
+## Purpose
+
+This standard defines **MANDATORY** naming conventions for all artifacts exchanged across integration boundaries - JSON fields, REST API paths, event types, queue topics, HTTP headers, enum values, query parameters, and file names. Consistent naming eliminates mapping ambiguity between services, enables automated CI/CD linting, and ensures AI agents operate on predictable structures.
+
+> *Normative language follows RFC 2119 semantics.*
+
+| Context | Convention | Example |
+|---------|-----------|---------|
+| JSON field names | `snake_case` | `order_total` |
+| URL path segments | `kebab-case` | `/shipping-addresses` |
+| Event type names | `dot.notation` | `order.payment.completed` |
+| Queue/topic names | `dot.notation` | `retail.orders.created.v1` |
+| HTTP headers | `Kebab-Case` | `X-Correlation-Id` |
+| Enum values | `UPPER_SNAKE_CASE` | `PAYMENT_PENDING` |
+| Query parameters | `snake_case` | `page_size` |
+| File/directory names | `kebab-case` | `order-export-2026-03.csv` |
+
+---
+
+## Rules
+
+#### General
+
+### R-1: American English
+
+All names **MUST** use American English (`color` not `colour`).
+
+### R-2: Descriptive Names
+
+Names **MUST** be descriptive. Single-character or opaque abbreviations **MUST NOT** be used. Names **MUST NOT** encode internal system names or infrastructure details. Use `customer_address` not `tbl_cust_addr`.
+
+### R-3: Approved Abbreviations
+
+Pre-approved abbreviations (all others **MUST** go through the registry):
+
+| `id` identifier | `config` configuration | `info` information | `spec` specification |
+|---|---|---|---|
+| `stats` statistics | `auth` authentication | `msg` message | `org` organization |
+| `env` environment | `max` maximum | `min` minimum | `avg` average |
+| `src` source | `dest` destination | `prev` previous | `temp` temporary |
+| `num` number | `qty` quantity | | |
+
+### R-4: Name Syntax
+
+Names **MUST NOT** begin with a digit. Names **MUST NOT** contain leading, trailing, or consecutive separators. Reserved words (`class`, `new`, `type`, `default`) **SHOULD** be avoided. Where unavoidable, **MUST** be domain-qualified (`account_type`).
+
+#### JSON Field Names
+
+### R-5: snake_case for JSON Fields
+
+**MUST** use `snake_case`. **MUST NOT** use `camelCase`, `PascalCase`, or `kebab-case`.
+
+### R-6: Plural Arrays and Singular Scalars
+
+Arrays **MUST** be plural (`line_items`). Scalars/objects **MUST** be singular (`order`).
+
+### R-7: Boolean Field Names
+
+Booleans **MUST** use adjective/past-participle form (`active`, `verified`). **SHOULD** omit `is_` unless the bare word is reserved (`is_new`).
+
+### R-8: Temporal Suffixes
+
+Date/time fields **SHOULD** use temporal suffixes: `_at` (timestamp), `_on` (date), `_until` (expiry), `_after` (lower bound), `_duration` (elapsed).
+
+### R-9: Field Name Word Order
+
+**MUST NOT** include structural prepositions: `error_reason` not `reason_for_error`. Adjectives **MUST** precede the noun: `primary_address` not `address_primary`. Fields **MUST** represent state, not intent: `collected_items` not `collect_items`.
+
+### R-10: URI and URL Suffixes
+
+URI/URL fields **SHOULD** use `_url` (locator) or `_uri` (identifier) suffixes.
+
+#### REST API URL Paths
+
+### R-11: kebab-case URL Paths
+
+Path segments **MUST** use `kebab-case`. **MUST NOT** include trailing slashes.
+
+### R-12: Plural Resource Nouns
+
+Resources **MUST** be plural nouns. Singular only for singletons (`/users/{user_id}/profile`).
+
+### R-13: No Verbs in Paths
+
+**MUST NOT** contain verbs. Model actions as sub-resources: `POST /orders/{id}/cancellation` not `POST /orders/{id}/cancel`.
+
+### R-14: snake_case Path Parameters
+
+Path parameters **MUST** use `snake_case`: `/orders/{order_id}` not `/orders/{orderId}`.
+
+### R-15: Version Prefix
+
+**SHOULD NOT** include `/api`. Version prefix **MUST** use `/v{major}`: `/v1/orders`.
+
+### R-16: Maximum Nesting Depth
+
+Nesting **MUST NOT** exceed three levels. Use query filters for deeper relationships.
+
+#### Event Type Names
+
+### R-17: Dot-Notation Event Types
+
+**MUST** use dot-notation: `{domain}.{resource}.{action}` with past-tense action. Multi-word segments **MUST** use `snake_case`: `order_management.purchase_order.approved`. Valid: `order.payment.completed`. Invalid: `order.payment.complete` (not past tense), `ORDER.PAYMENT.COMPLETED` (uppercase).
+
+### R-18: Event Segment Depth
+
+Additional segments **MAY** be appended; total depth **SHOULD NOT** exceed five.
+
+### R-19: Event Catalog Registration
+
+Types **MUST** be registered in the event catalog. Unregistered types **MUST** be rejected.
+
+#### Message Queue and Topic Names
+
+### R-20: Topic Name Structure
+
+**MUST** use: `{domain}.{resource}.{event_type}.v{major}`. Valid: `retail.orders.created.v1`. Multi-word segments **MUST** use `snake_case`. **MUST NOT** contain application or team names. Describe the business event.
+
+### R-21: Dead Letter and Retry Suffixes
+
+Dead letter queues **MUST** append `.dlq`. Retry topics **MUST** append `.retry.{attempt}`.
+
+#### HTTP Header Names
+
+### R-22: Custom Header Casing
+
+Custom headers **MUST** use `Kebab-Case` (title capitalized). `X-` prefix only for organization-specific headers; omit for broad adoption per RFC 6648.
+
+### R-23: Standard Header Names
+
+**MUST** use these exact names when semantics match:
+
+| Header | Purpose |
+|--------|---------|
+| `X-Correlation-Id` | Distributed trace correlation |
+| `X-Request-Id` | Unique request identifier |
+| `X-Tenant-Id` | Multi-tenant context |
+| `X-Flow-Id` | Business process flow |
+| `X-Idempotency-Key` | Client-supplied idempotency token |
+
+### R-24: No Internal Details in Headers
+
+**MUST NOT** leak internal system names or infrastructure details.
+
+#### Enum Values
+
+### R-25: UPPER_SNAKE_CASE Enums
+
+**MUST** use `UPPER_SNAKE_CASE`. **MUST NOT** use numeric codes, abbreviations, or single characters.
+
+### R-26: Self-Descriptive Enum Values
+
+Values **MUST** be self-descriptive without the field name: `PAYMENT_PENDING` not `PP`.
+
+### R-27: UNKNOWN Default Value
+
+Every enum **MUST** include `UNKNOWN` as the default for forward compatibility.
+
+### R-28: Deprecated Value Preservation
+
+Deprecated values **MUST** be preserved until all consumers migrate.
+
+#### Query Parameter Names
+
+### R-29: Query Parameter Conventions
+
+**MUST** use `snake_case`. Standard pagination: `page_size` (integer), `page` (integer, 1-based), `cursor` (string). Sorting: `sort_by`, `sort_order` (`asc`/`desc`). Filters **SHOULD** use the field name directly. Complex filters **MAY** use brackets: `created_at[gte]=2026-01-01T00:00:00Z`.
+
+### R-30: Boolean Query Parameters
+
+Boolean parameters **MUST** accept `true`/`false` strings. Presence alone **MUST NOT** imply truth.
+
+#### File and Directory Names
+
+### R-31: File Naming Pattern
+
+**MUST** use `kebab-case`. Pattern: `{resource}-{qualifier}-{date}.{extension}`.
+
+### R-32: File Extension Conventions
+
+Extensions **MUST** be lowercase. Schema files **MUST** follow `{resource}.{version}.schema.json`.
+
+---
+
+## Examples
+
+```
+GET /v1/purchase-orders/{purchase_order_id}/line-items?status=SHIPPED&sort_by=created_at&page_size=10
+
+Headers:
+  X-Correlation-Id: 8f14e45f-ceea-467f-a8dc-e67e2d16eb68
+  X-Tenant-Id: tenant-acme-corp
+
+Response:
+{
+  "line_items": [
+    {
+      "line_item_id": "li-001",
+      "product_name": "Wireless Keyboard",
+      "quantity": 5,
+      "unit_price": { "amount": "49.99", "currency_code": "USD" },
+      "status": "SHIPPED",
+      "shipped": true,
+      "created_at": "2026-03-27T14:30:00Z",
+      "tracking_url": "https://tracking.example.com/pkg/12345"
+    }
+  ],
+  "pagination": { "page": 1, "page_size": 10, "total_items": 1 }
+}
+
+Event:  procurement.line_item.shipped
+Topic:  procurement.line_items.shipped.v1
+File:   line-item-shipments-2026-03-28.csv
+```
+
+---
+
+## Enforcement Rules
+
+| Boundary | Validates | Rejection |
+|----------|-----------|-----------|
+| CI/CD Pipeline | OpenAPI paths, field names, enum values | Build fails, PR blocked |
+| Schema Registry | Field names, event types | Registration rejected |
+| API Gateway | URL path segments, header names | Route deployment rejected |
+| Event Bus | Event type names, topic names | Publish rejected with error |
+| Contract Review | All naming contexts | Review blocked |
+
+### Hard Rejections (**MUST** reject)
+
+Mixed case conventions in a single contract; verbs in URL path segments; non-past-tense event actions; unapproved abbreviations; internal system names in public contracts; missing version segment in topic names; enum values not in `UPPER_SNAKE_CASE`.
+
+### Soft Warnings (**SHOULD** fix)
+
+`is_` prefix on booleans (unless bare word is reserved); URL nesting beyond three levels; missing temporal suffix on date/time fields; query parameter names inconsistent with JSON fields.
+
+### Validation Regex
+
+| Context | Pattern |
+|---------|---------|
+| JSON fields | `^[a-z][a-z0-9]*(_[a-z0-9]+)*$` |
+| URL path segments | `^[a-z][a-z0-9]*(-[a-z0-9]+)*$` |
+| Path parameters | `\{[a-z][a-z0-9]*(_[a-z0-9]+)*\}` |
+| Event types | `^[a-z][a-z0-9]*(_[a-z0-9]+)*(\.[a-z][a-z0-9]*(_[a-z0-9]+)*){2,4}$` |
+| Queue/topic names | `^[a-z][a-z0-9]*(_[a-z0-9]+)*(\.[a-z][a-z0-9]*(_[a-z0-9]+)*){2,}\.v[0-9]+(\.(dlq\|retry\.[0-9]+))?$` |
+| Enum values | `^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$` |
+| Custom HTTP headers | `^X-([A-Z][a-z0-9]*(-[A-Z][a-z0-9]*)*)$` |
+| File names | `^[a-z][a-z0-9]*(-[a-z0-9]+)*\.[a-z]+$` |
+
+OpenAPI specs **MUST** be validated via Spectral or equivalent in CI/CD. AsyncAPI specs **MUST** be validated for event/topic naming. Schema registries **MUST** reject non-conforming field names. API gateways **SHOULD** enforce path conventions at route registration.
+
+---
+
+## References
+
+### Normative
+
+- [RFC 9110 - HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110)
+- [RFC 9457 - Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc9457)
+- [RFC 2119 - Key Words for Use in RFCs](https://www.rfc-editor.org/rfc/rfc2119)
+- [RFC 6648 - Deprecating X- Prefix](https://www.rfc-editor.org/rfc/rfc6648)
+
+### Informative
+
+- [Google AIP-140: Field Names](https://google.aip.dev/140) | [AIP-190: Naming](https://google.aip.dev/190) | [AIP-122: Resources](https://google.aip.dev/122)
+- [Zalando RESTful API Guidelines](https://opensource.zalando.com/restful-api-guidelines/)
+- [Microsoft REST API Guidelines](https://github.com/microsoft/api-guidelines)
+- [CloudEvents Specification](https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md)
+- [Confluent Kafka Topic Naming](https://www.confluent.io/learn/kafka-topic-naming-convention/)
+
+---
+
+## Rationale
+
+**snake_case for JSON fields:** Aligns with Google AIP-140 and Zalando. Most interoperable convention - valid identifier in Python, Ruby, Rust, SQL; maps cleanly to camelCase via serialization libraries.
+
+**kebab-case for URLs:** Most readable in browser bars and logs, avoids case-sensitivity ambiguity. Google, Zalando, and Microsoft converge here.
+
+**Dot-notation for events/topics:** Enables wildcard subscription (`order.payment.*`) in brokers like RabbitMQ and NATS. Slashes conflict with URL semantics; hyphens prevent wildcard matching.
+
+**UPPER_SNAKE_CASE for enums:** Near-universal constant convention across languages. Visually distinct from field names and URL segments.
+
+**Security:** Business-domain naming prevents leaking internal table names, service mesh topology, or infrastructure details that aid reconnaissance.
+
+**Observability:** Uniform naming enables distributed trace aggregation without per-service field mapping. Predictable event structures enable pattern-based alerting (`*.payment.failed`).
+
+---
+
+## Version History
+
+| Version | Date       | Change             |
+| ------- | ---------- | ------------------ |
+| 1.0.0   | 2026-03-28 | Initial definition |

package/standards/integration/standards/observability/_category_.json

@@ -0,0 +1 @@
+{"label": "Observability", "position": 6}