invopop / invopop/gobl.dev

GET /v0/schemas lists two schemas that GET /v0/schemas/{path} returns 404 for

Open
#53 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

`GET /v0/schemas` advertises two schema IDs that cannot be fetched:

```console
$ curl -s https://gobl.dev/v0/schemas | jq -r '.schemas[] | select(contains("/mx/"))'
https://gobl.org/draft-0/regimes/mx/food-vouchers
https://gobl.org/draft-0/regimes/mx/fuel-account-balance

$ curl -s -o /dev/null -w '%{http_code}\n' https://gobl.dev/v0/schemas/regimes/mx/food-vouchers
404
$ curl -s -o /dev/null -w '%{http_code}\n' 'https://gobl.dev/v0/schemas/regimes/mx/food-vouchers?bundle'
404
```

### Cause

The two endpoints have different sources of truth:

- `handleSchemaList` returns `schema.List()`, the in-process registry, which includes types registered by the external addon modules pulled in via `bundle` — here `gobl.mx.cfdi`.
- `handleSchema` reads `data.Content`, the `embed.FS` in `github.com/invopop/gobl`, which only contains core schemas. The external modules' JSON is not there, so the read fails and it returns `ErrNotFound`.

`schema.BundleSchema` reads the same embed, hence the `?bundle` 404 too.

### Impact

The listing is the discovery mechanism, so a consumer that walks `/v0/schemas` and fetches each entry hits two unavoidable 404s. I ran into it writing a coverage test for `gobl.ts`, asserting that every advertised schema has a generated type — these two have no published JSON for anyone to generate from, so they had to be special-cased.

### Possible directions

Either would resolve the inconsistency:

1. **Serve them** — have the external addon modules embed their schema JSON and have `handleSchema` fall back to a registry-aware lookup. This is the better outcome, since the types genuinely exist and are usable in documents.
2. **Stop listing them** — filter `handleSchemaList` to IDs that `data.Content` can actually serve. Cheaper, but loses discoverability for schemas that really are part of the addon surface.

Happy to send a PR for either if you have a preference.

Found while generating TypeScript types from the schemas (invopop/gobl.ts#10).

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by tracing handleSchemaList, handleSchema, and schema.BundleSchema, comparing schema.List() with data.Content and the embedded core schemas. Confirm how the external gobl.mx.cfdi schemas are registered and whether their JSON is available to the API. Done means both advertised Mexican schema IDs can be fetched, including with ?bundle, or are consistently excluded from the list.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
api, backend
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.