Cursor rule

1---
2description: 
3globs: **/*.{openapi.yaml}
4alwaysApply: false
5---
6response:
7  - name: data
8    type: object | array
9    required: conditional
10    description: Must be present when request is successful (`2xx`). Single entity responses return an object; list responses return an array.
11 
12  - name: pagination
13    type: object
14    required: conditional
15    description: Must be included only in successful (`2xx`) responses that are paginated. Must follow the http-pagination spec.
16 
17  - name: errors
18    type: array
19    required: conditional
20    description: Must be present only when response is an error (`4xx` or `5xx`). Each item must include `code`, `reason`, and `message`.
21 
22  - name: debug
23    type: object
24    required: conditional
25    description: Only included when the `X-Grd-Debug: true` header is present. Contains metadata for traceability and debugging.
26 
27debug:
28  - name: trace_id
29    type: string
30    description: Unique global identifier for the request. Also returned in the `X-Grd-Trace-Id` header.
31 
32  - name: correlation_id
33    type: string
34    description: Correlation ID for distributed tracing. Also returned in the `X-Grd-Correlation-Id` header.
35 
36  - name: instance
37    type: string
38    description: Identifier of the instance or pod that processed the request.
39 
40  - name: timestamp
41    type: string
42    description: UNIX epoch timestamp representing when the request was received.
43 
44  - name: duration
45    type: string
46    description: Total time taken to process the request in milliseconds.
47 
48  - name: memory
49    type: string
50    description: Memory used to process the request in bytes.
51 
52  - name: query
53    type: string
54    optional: true
55    description: Raw query string of the request, if available.
56 
57  - name: params
58    type: string
59    optional: true
60    description: Path parameters used in the route, if any.
61 
62  - name: external_ip
63    type: string
64    description: External IP of the client request (e.g., proxy or gateway).
65 
66error:
67  - name: code
68    type: string
69    required: true
70    description: Standardized error code, used for programmatic handling. Defined in the Guardia error-handling spec.
71 
72  - name: reason
73    type: string
74    required: true
75    description: Concise reason for the error. Must match predefined reasons in the error catalog.
76 
77  - name: message
78    type: string
79    required: true
80    description: Informational message to help the developer understand and resolve the issue. Not intended for end-user display.
81 
82rules:
83  - if: status code is 2xx
84    then:
85      - must include: data as object when not is list
86      - must include: data as array when is list
87      - must not include: errors
88 
89  - if: status code is 4xx or 5xx
90    then:
91      - must include: list of errors
92      - must not include: data, pagination
93 
94  - if: X-Grd-Debug header is present and true
95    then:
96      - include: debug object in the response
97      - enforce: must not expose sensitive data
98 
99  - enforce: response payloads must be documented in the OpenAPI (OAS) contract
100 
101notes:
102  - All successful responses must include a `data` field and optionally a `pagination` field.
103  - All error responses must return an `errors` array with structured information.
104  - The `debug` block is a powerful tool for observability and must be used cautiously.
105  - This structure is the minimum standard for all RESTful APIs within Guardia.
106