Deliverables and versioning
What the project publishes, all from the same TypeScript sources and listed on the Deliverables page:
| Deliverable | Where | Version |
|---|---|---|
| TypeScript library and types | this package (src/index.ts), TypeDoc |
package semver (package.json) |
| JSON Schemas | schemas/*.v1.schema.json, published at /schemas/ |
v1 in the file names and $ids |
| Format registry | schemas/formats.json, GET /v1/formats |
follows the package |
| HTTP API | openapi/openapi.yaml (and .json), einvoice serve, the Dockerfile |
/v1 path prefix; the spec carries its own info.version |
| Command line | einvoice binaries on each GitHub release |
package semver |
| Browser converter, conformance checklist, corpus results | the Pages site | built from main |
Compatibility promise. The JSON Schema major version and the API prefix move together: v1 stays compatible for as long as it is published.
- Additive changes keep
v1(a minor or patch release): new optional fields, new extension blocks, new formats and code-list values, new warning codes, new endpoints or query parameters. Objects are open and clients must ignore fields they do not know. - Breaking changes get
v2(a major release): removing or renaming a field, changing its type or meaning, making an optional field required, narrowing a pattern, removing an endpoint or changing a problemtype.*.v2.schema.jsonand/v2are published next to v1, and the v1 files and endpoints stay available. - Package semver follows the TypeScript API: a major release for breaking changes to exported functions and types, which also bumps the schema and API version when the output shape changed. The CLI’s exit codes and the problem
typeURIs are part of the promise. - Everything generated is checked in CI: the schemas,
formats.jsonandopenapi.jsonare rebuilt and compared (bun run check:schemas), and the contract tests fail when a response no longer matches the spec.