invopop / invopop/gobl.dev

openapi.json documents the wrong error shape (faults and top-level code)

Open Beginner friendly
#54 0 comments 0 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.