openapi.json documents the wrong error shape (faults and top-level code)
- Dominant language
- Go
- Stars
- 0
- Forks
- 0
- Avg merge
- 9h 33m
- Merged PRs (30d)
- 9
Description
The `Error` component in `api/openapi.json` does not match what the API actually returns, in two ways.
### What the spec says
```json
"faults": {
"type": "array",
"items": {
"type": "object",
"properties": {
"properties": { "type": "array", "items": { "type": "string" },
"description": "Property paths that failed." },
"description": { "type": "string" }
}
}
},
"code": { "type": "integer", "description": "HTTP status code.", "example": 422 }
```
### What the API returns
```console
$ curl -s -X POST https://gobl.dev/v0/build -H 'Content-Type: application/json' \
-d '{"data":{"$schema":"https://gobl.org/draft-0/bill/invoice","$regime":"ES","supplier":{"name":"X"}}}'
{"key":"validation","faults":[
{"code":"GOBL-BILL-INVOICE-09","paths":["$.totals"],"message":"invoice totals are required"},
{"code":"GOBL-BILL-INVOICE-10","paths":["$.lines"],"message":"invoice lines are required without discounts or charges"},
{"code":"GOBL-ES-BILL-INVOICE-02","paths":["$.supplier.tax_id"],"message":"invoice supplier tax ID in Spain is required"}]}
```
So:
1. **Fault fields are `{code, message, paths}`**, not `{properties, description}`. This matches `gobl`'s `Fault` struct and the published `bill/fault` schema — `paths` are JSON paths (`$.supplier.tax_id`), not path segment arrays.
2. **There is no top-level `code`.** `(*gobl.Error).MarshalJSON` marshals `{key, faults, message}` only. Validation responses also carry no `message`, just `key` and `faults`.
### Impact
A client generated from or written against the spec mis-parses every validation error. Writing the `gobl.ts` client I modelled `faults[].properties` / `.description` from the spec, and every fault came through as `undefined` until a live test caught it; a UI relying on it would silently lose all field highlighting.
### Suggested fix
Point the fault schema at the existing `bill/fault` definition (or inline `{code, message, paths}`) and drop the top-level `code`, since the HTTP status already conveys it. Given `gobl.Fault` is already a published schema, referencing it would keep the spec from drifting again.
Happy to send a PR if useful.
Found while writing the TypeScript client (invopop/gobl.ts#10).
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the Error component in api/openapi.json and compare its faults and top-level fields with the existing bill/fault schema and the payload examples. Reference the published fault definition or represent {code, message, paths}, remove the top-level code, and confirm the resulting specification matches the documented API responses.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- json, typescript
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 88/100