Skip to content

Commit fa30210

Browse files
Bucknallaclaude
Bucknalla
and
claude
authored
feat: centralised error/status code definitions with codeRef support (#303)
* feat: add centralised error and status code definitions with codeRef support Introduces notecard.error.json and notecard.status.json as single-source-of-truth definition files where each error/status code is defined exactly once. Response schemas declare which codes they can emit via a codeRef array of individual references, making the contract explicit and auditable per schema. Updates the doc generator to resolve codeRef arrays into sub-descriptions at build time. Applies the pattern to hub.status and hub.sync.status as initial test cases. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * chore: collapse notecard.error.json and notecard.status.json into notecard.codes.json Merge the two separate code definition files into a single source of truth (`notecard.codes.json`) since the error/status distinction is not meaningful — codes can appear in either the `err` or `status` field depending on context. Update `hub.status` and `hub.sync.status` response schemas to reference `notecard.codes.json` via `codeRef` arrays. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix: restore alphabetical property order in hub.sync.status response schema err property was placed after seconds instead of after completed, failing the schema hierarchy CI check. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 88ac91e commit fa30210

4 files changed

Lines changed: 462 additions & 6 deletions

File tree

‎hub.status.rsp.notecard.api.json‎

Lines changed: 60 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,68 @@
1717
"description": "`true` if the Notecard is connected to Notehub.",
1818
"type": "boolean"
1919
},
20+
"err": {
21+
"description": "If present, a string describing a connection or authentication error, e.g. `{\"err\":\"unable to connect to notehub {notehub-open-failure}\"}`.",
22+
"type": "string",
23+
"codeRef": [
24+
"notecard.codes.json#/$defs/auth",
25+
"notecard.codes.json#/$defs/auth-retry",
26+
"notecard.codes.json#/$defs/connect-aborted",
27+
"notecard.codes.json#/$defs/device-delay-5",
28+
"notecard.codes.json#/$defs/device-disabled",
29+
"notecard.codes.json#/$defs/extended-network-failure",
30+
"notecard.codes.json#/$defs/extended-service-failure",
31+
"notecard.codes.json#/$defs/host-unreachable",
32+
"notecard.codes.json#/$defs/hub-not-connected",
33+
"notecard.codes.json#/$defs/network",
34+
"notecard.codes.json#/$defs/network-timeout",
35+
"notecard.codes.json#/$defs/notehub-open-failure",
36+
"notecard.codes.json#/$defs/product-noexist",
37+
"notecard.codes.json#/$defs/request-failure",
38+
"notecard.codes.json#/$defs/service",
39+
"notecard.codes.json#/$defs/session-closed",
40+
"notecard.codes.json#/$defs/ticket",
41+
"notecard.codes.json#/$defs/transport-unreachable",
42+
"notecard.codes.json#/$defs/web-payload"
43+
]
44+
},
2045
"status": {
2146
"description": "Details about the Notecard's transport (e.g. cellular, WiFi, LoRa) connection status.\n\nUse `connected` to check if the Notecard is connected to Notehub.",
22-
"type": "string"
47+
"type": "string",
48+
"codeRef": [
49+
"notecard.codes.json#/$defs/auth",
50+
"notecard.codes.json#/$defs/auth-retry",
51+
"notecard.codes.json#/$defs/connect-aborted",
52+
"notecard.codes.json#/$defs/connected",
53+
"notecard.codes.json#/$defs/device-delay-5",
54+
"notecard.codes.json#/$defs/device-disabled",
55+
"notecard.codes.json#/$defs/disconnected",
56+
"notecard.codes.json#/$defs/extended-network-failure",
57+
"notecard.codes.json#/$defs/extended-service-failure",
58+
"notecard.codes.json#/$defs/host-retry",
59+
"notecard.codes.json#/$defs/host-unreachable",
60+
"notecard.codes.json#/$defs/hub-not-connected",
61+
"notecard.codes.json#/$defs/net-init",
62+
"notecard.codes.json#/$defs/network",
63+
"notecard.codes.json#/$defs/network-timeout",
64+
"notecard.codes.json#/$defs/no-changes",
65+
"notecard.codes.json#/$defs/not-connected",
66+
"notecard.codes.json#/$defs/notehub-connected",
67+
"notecard.codes.json#/$defs/notehub-disconnected",
68+
"notecard.codes.json#/$defs/notehub-open-failure",
69+
"notecard.codes.json#/$defs/product-noexist",
70+
"notecard.codes.json#/$defs/request-failure",
71+
"notecard.codes.json#/$defs/service",
72+
"notecard.codes.json#/$defs/session-closed",
73+
"notecard.codes.json#/$defs/socket-ip-init",
74+
"notecard.codes.json#/$defs/socket-ip-term",
75+
"notecard.codes.json#/$defs/ticket",
76+
"notecard.codes.json#/$defs/transport-unreachable",
77+
"notecard.codes.json#/$defs/wait-data",
78+
"notecard.codes.json#/$defs/wait-gateway",
79+
"notecard.codes.json#/$defs/wait-service",
80+
"notecard.codes.json#/$defs/web-payload"
81+
]
2382
}
2483
},
2584
"required": [

‎hub.sync.status.rsp.notecard.api.json‎

Lines changed: 194 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,75 @@
2121
"description": "Number of seconds since the last sync completion.",
2222
"type": "integer"
2323
},
24+
"err": {
25+
"description": "If present, a string describing the error that occurred during sync, e.g. `{\"err\":\"sync error {sync-error}\"}`.",
26+
"type": "string",
27+
"codeRef": [
28+
"notecard.codes.json#/$defs/auth",
29+
"notecard.codes.json#/$defs/auth-retry",
30+
"notecard.codes.json#/$defs/connect-aborted",
31+
"notecard.codes.json#/$defs/connect-failure",
32+
"notecard.codes.json#/$defs/connect-ll-failure",
33+
"notecard.codes.json#/$defs/device-delay-5",
34+
"notecard.codes.json#/$defs/device-disabled",
35+
"notecard.codes.json#/$defs/dfu-bad-target",
36+
"notecard.codes.json#/$defs/dfu-config-backup",
37+
"notecard.codes.json#/$defs/dfu-dl",
38+
"notecard.codes.json#/$defs/dfu-dl-chunk-length",
39+
"notecard.codes.json#/$defs/dfu-ext-chunk",
40+
"notecard.codes.json#/$defs/dfu-ext-get-length",
41+
"notecard.codes.json#/$defs/dfu-ext-length",
42+
"notecard.codes.json#/$defs/dfu-ext-written",
43+
"notecard.codes.json#/$defs/dfu-int-append",
44+
"notecard.codes.json#/$defs/dfu-int-chunk",
45+
"notecard.codes.json#/$defs/dfu-int-chunk-length",
46+
"notecard.codes.json#/$defs/dfu-modem-fs",
47+
"notecard.codes.json#/$defs/dfu-not-ready",
48+
"notecard.codes.json#/$defs/dfu-post-md5",
49+
"notecard.codes.json#/$defs/dfu-pre-md5",
50+
"notecard.codes.json#/$defs/dfu-sig",
51+
"notecard.codes.json#/$defs/dfu-superseded",
52+
"notecard.codes.json#/$defs/dfu-total-length",
53+
"notecard.codes.json#/$defs/dfu-watchdog",
54+
"notecard.codes.json#/$defs/extended-network-failure",
55+
"notecard.codes.json#/$defs/extended-service-failure",
56+
"notecard.codes.json#/$defs/file-open",
57+
"notecard.codes.json#/$defs/host-unreachable",
58+
"notecard.codes.json#/$defs/hub-not-connected",
59+
"notecard.codes.json#/$defs/incompatible",
60+
"notecard.codes.json#/$defs/modem-power-failure",
61+
"notecard.codes.json#/$defs/network",
62+
"notecard.codes.json#/$defs/network-timeout",
63+
"notecard.codes.json#/$defs/no-address",
64+
"notecard.codes.json#/$defs/no-handler",
65+
"notecard.codes.json#/$defs/no-session",
66+
"notecard.codes.json#/$defs/notefile-noexist",
67+
"notecard.codes.json#/$defs/notehub-open-failure",
68+
"notecard.codes.json#/$defs/odfu-aux-mode",
69+
"notecard.codes.json#/$defs/odfu-fail",
70+
"notecard.codes.json#/$defs/product-noexist",
71+
"notecard.codes.json#/$defs/receive-timeout",
72+
"notecard.codes.json#/$defs/registration-failure",
73+
"notecard.codes.json#/$defs/request-failure",
74+
"notecard.codes.json#/$defs/service",
75+
"notecard.codes.json#/$defs/session-closed",
76+
"notecard.codes.json#/$defs/socket-connect-error",
77+
"notecard.codes.json#/$defs/socket-dns-failure",
78+
"notecard.codes.json#/$defs/socket-invalid-cert",
79+
"notecard.codes.json#/$defs/socket-tls-error",
80+
"notecard.codes.json#/$defs/sync-error",
81+
"notecard.codes.json#/$defs/sync-local-error",
82+
"notecard.codes.json#/$defs/sync-remote-error",
83+
"notecard.codes.json#/$defs/ticket",
84+
"notecard.codes.json#/$defs/transport-unreachable",
85+
"notecard.codes.json#/$defs/web-payload",
86+
"notecard.codes.json#/$defs/wifi-ap",
87+
"notecard.codes.json#/$defs/wifi-auth",
88+
"notecard.codes.json#/$defs/wifi-config",
89+
"notecard.codes.json#/$defs/wifi-error",
90+
"notecard.codes.json#/$defs/wifi-fatal"
91+
]
92+
},
2493
"mode": {
2594
"description": "The current state of the wireless connectivity module in use.",
2695
"type": "string"
@@ -40,8 +109,131 @@
40109
"minApiVersion": "4.1.1"
41110
},
42111
"status": {
43-
"description": "The status of the current or previous sync. Refer to [this listing](/support/notecard-error-and-status-codes/) for the meaning of the various status codes returned (e.g. `{sync-end}`).",
44-
"type": "string"
112+
"description": "The status of the current or previous sync.",
113+
"type": "string",
114+
"codeRef": [
115+
"notecard.codes.json#/$defs/address-assigned",
116+
"notecard.codes.json#/$defs/auth",
117+
"notecard.codes.json#/$defs/auth-retry",
118+
"notecard.codes.json#/$defs/cell-disconnect-begin",
119+
"notecard.codes.json#/$defs/cell-disconnected",
120+
"notecard.codes.json#/$defs/cell-registered",
121+
"notecard.codes.json#/$defs/cell-registration-wait",
122+
"notecard.codes.json#/$defs/cell-scan",
123+
"notecard.codes.json#/$defs/cell-scan-wait",
124+
"notecard.codes.json#/$defs/connect-aborted",
125+
"notecard.codes.json#/$defs/connect-failure",
126+
"notecard.codes.json#/$defs/connect-ll-failure",
127+
"notecard.codes.json#/$defs/connected",
128+
"notecard.codes.json#/$defs/connecting",
129+
"notecard.codes.json#/$defs/device-delay-5",
130+
"notecard.codes.json#/$defs/device-disabled",
131+
"notecard.codes.json#/$defs/dfu-bad-target",
132+
"notecard.codes.json#/$defs/dfu-config-backup",
133+
"notecard.codes.json#/$defs/dfu-dl",
134+
"notecard.codes.json#/$defs/dfu-dl-chunk-length",
135+
"notecard.codes.json#/$defs/dfu-ext-chunk",
136+
"notecard.codes.json#/$defs/dfu-ext-get-length",
137+
"notecard.codes.json#/$defs/dfu-ext-length",
138+
"notecard.codes.json#/$defs/dfu-ext-written",
139+
"notecard.codes.json#/$defs/dfu-int-append",
140+
"notecard.codes.json#/$defs/dfu-int-chunk",
141+
"notecard.codes.json#/$defs/dfu-int-chunk-length",
142+
"notecard.codes.json#/$defs/dfu-modem-fs",
143+
"notecard.codes.json#/$defs/dfu-not-ready",
144+
"notecard.codes.json#/$defs/dfu-post-md5",
145+
"notecard.codes.json#/$defs/dfu-pre-md5",
146+
"notecard.codes.json#/$defs/dfu-sig",
147+
"notecard.codes.json#/$defs/dfu-superseded",
148+
"notecard.codes.json#/$defs/dfu-total-length",
149+
"notecard.codes.json#/$defs/dfu-watchdog",
150+
"notecard.codes.json#/$defs/disconnected",
151+
"notecard.codes.json#/$defs/disconnecting",
152+
"notecard.codes.json#/$defs/extended-network-failure",
153+
"notecard.codes.json#/$defs/extended-service-failure",
154+
"notecard.codes.json#/$defs/file-open",
155+
"notecard.codes.json#/$defs/host-retry",
156+
"notecard.codes.json#/$defs/host-unreachable",
157+
"notecard.codes.json#/$defs/hub-not-connected",
158+
"notecard.codes.json#/$defs/idle",
159+
"notecard.codes.json#/$defs/incompatible",
160+
"notecard.codes.json#/$defs/joining-network",
161+
"notecard.codes.json#/$defs/modem-off",
162+
"notecard.codes.json#/$defs/modem-on",
163+
"notecard.codes.json#/$defs/modem-power-failure",
164+
"notecard.codes.json#/$defs/net-init",
165+
"notecard.codes.json#/$defs/network",
166+
"notecard.codes.json#/$defs/network-error-wait",
167+
"notecard.codes.json#/$defs/network-timeout",
168+
"notecard.codes.json#/$defs/network-up",
169+
"notecard.codes.json#/$defs/no-address",
170+
"notecard.codes.json#/$defs/no-changes",
171+
"notecard.codes.json#/$defs/no-handler",
172+
"notecard.codes.json#/$defs/no-session",
173+
"notecard.codes.json#/$defs/not-connected",
174+
"notecard.codes.json#/$defs/notefile-noexist",
175+
"notecard.codes.json#/$defs/notehub-connected",
176+
"notecard.codes.json#/$defs/notehub-disconnected",
177+
"notecard.codes.json#/$defs/notehub-open-failure",
178+
"notecard.codes.json#/$defs/ntn-connected",
179+
"notecard.codes.json#/$defs/ntn-connecting",
180+
"notecard.codes.json#/$defs/ntn-disconnecting",
181+
"notecard.codes.json#/$defs/ntn-idle",
182+
"notecard.codes.json#/$defs/ntn-initializing",
183+
"notecard.codes.json#/$defs/ntn-power",
184+
"notecard.codes.json#/$defs/odfu-aux-mode",
185+
"notecard.codes.json#/$defs/odfu-fail",
186+
"notecard.codes.json#/$defs/product-noexist",
187+
"notecard.codes.json#/$defs/receive-timeout",
188+
"notecard.codes.json#/$defs/registration-failure",
189+
"notecard.codes.json#/$defs/request-failure",
190+
"notecard.codes.json#/$defs/service",
191+
"notecard.codes.json#/$defs/session-closed",
192+
"notecard.codes.json#/$defs/socket-closed-session",
193+
"notecard.codes.json#/$defs/socket-connect-error",
194+
"notecard.codes.json#/$defs/socket-connected",
195+
"notecard.codes.json#/$defs/socket-connecting",
196+
"notecard.codes.json#/$defs/socket-disconnected",
197+
"notecard.codes.json#/$defs/socket-dns-failure",
198+
"notecard.codes.json#/$defs/socket-dns-success",
199+
"notecard.codes.json#/$defs/socket-invalid-cert",
200+
"notecard.codes.json#/$defs/socket-ip-init",
201+
"notecard.codes.json#/$defs/socket-ip-term",
202+
"notecard.codes.json#/$defs/socket-open-session",
203+
"notecard.codes.json#/$defs/socket-opened-notification-session",
204+
"notecard.codes.json#/$defs/socket-opened-session",
205+
"notecard.codes.json#/$defs/socket-tls",
206+
"notecard.codes.json#/$defs/socket-tls-connected",
207+
"notecard.codes.json#/$defs/socket-tls-connecting",
208+
"notecard.codes.json#/$defs/socket-tls-error",
209+
"notecard.codes.json#/$defs/sync",
210+
"notecard.codes.json#/$defs/sync-begin",
211+
"notecard.codes.json#/$defs/sync-completed",
212+
"notecard.codes.json#/$defs/sync-disconnecting",
213+
"notecard.codes.json#/$defs/sync-end",
214+
"notecard.codes.json#/$defs/sync-error",
215+
"notecard.codes.json#/$defs/sync-get-local-changes",
216+
"notecard.codes.json#/$defs/sync-get-remote-changes",
217+
"notecard.codes.json#/$defs/sync-local-error",
218+
"notecard.codes.json#/$defs/sync-remote-error",
219+
"notecard.codes.json#/$defs/ticket",
220+
"notecard.codes.json#/$defs/transport",
221+
"notecard.codes.json#/$defs/transport-unreachable",
222+
"notecard.codes.json#/$defs/unavailable",
223+
"notecard.codes.json#/$defs/wait-data",
224+
"notecard.codes.json#/$defs/wait-gateway",
225+
"notecard.codes.json#/$defs/wait-service",
226+
"notecard.codes.json#/$defs/web-payload",
227+
"notecard.codes.json#/$defs/wifi-ap",
228+
"notecard.codes.json#/$defs/wifi-auth",
229+
"notecard.codes.json#/$defs/wifi-config",
230+
"notecard.codes.json#/$defs/wifi-disconnect-begin",
231+
"notecard.codes.json#/$defs/wifi-disconnected",
232+
"notecard.codes.json#/$defs/wifi-error",
233+
"notecard.codes.json#/$defs/wifi-fatal",
234+
"notecard.codes.json#/$defs/wifi-join-wait",
235+
"notecard.codes.json#/$defs/wifi-joined"
236+
]
45237
},
46238
"sync": {
47239
"description": "`true` if the notecard has unsynchronized notes, or requires a sync to set its internal clock.",

0 commit comments

Comments
 (0)