openapi-typescript VS typebox

OpenAPI TypeScript is the closest thing I’ve found to perfection when your API is written in a different language than your client.

https://openapi-ts.dev/

openapi-ts/openapi-typescript is a powerful tool for generating TypeScript schema definitions from OpenAPI 3 specifications. The same organization also provides openapi-fetch, a type-safe fetch client library designed to work seamlessly with these generated schemas. Although very useful, one notable hurdle with openapi-fetch is that developers must manually implement client code for each API endpoint.

Overly expressive type systems have way more potential for footguns than simple type systems. In fact, I would say that overly expressive type systems make it easy to create unmaintainable code (still waiting on this showstopping bug which nobody can debug because it uses overly expressive types in TS: https://github.com/openapi-ts/openapi-typescript/issues/1769)

hi, few questions,

-who is your ideal user/customer? what stack are they using, and why do they use you?

-why did you decide to work on this? (ie, what inspired you?)

-how do you compare against openapi templated/generated SDKs? ie i use openapi-typescript (https://openapi-ts.dev/) and it is fantastic

-there seem to be some VC backed companies in the space: https://news.ycombinator.com/item?id=40147281, what is your edge?

-as someone who tried to maintain a few SDKs in my non-familiar languages (go, java, c#), i think i definitely see a paid use case for giving the problem to someone else who can maintain a quality SDK, but there are already 3-4 VC backed companies in the space, and i think the existing free tools are not bad if you spend some time with them, what is the gap/thing they're missing?

ty, john

Oof, I strongly disagree with this article's description of how REST apis are used, and the distinction between openAPI and rest. If I design a REST api in 2023, and in 2024 produce an openapi yaml or json file for that API with no other changes, is it somehow no longer a REST api? of course not. The article seems to be predicated on this distinction.

> The least-commonly used API model is REST

Is that true? I don't think it is frankly, though I suppose if any API that would be a REST api _if it didn't have an openapi spec_ is somehow no longer a REST api, then maybe? But as previously stated, I just don't think that's true.

> A signature characteristic of [REST APIs] is that clients do not construct URLs from other information

I don't think this is true in practice. Let us consider the case of a webapp that uses a REST api to fetch/mutate data. The client is a browser, and is almost certainly using javascript to make requests. Javascript doesn't just magically know how to access resources, your app code is written to construct urls (example: getting an ID from the url, and then constructing a new url using that extracted ID to make an api call to fetch that resource). In fact, the only situation where I think this description of how a REST api is used is _defensibly_ true (and this is hella weak), is where the REST api in question has provided an openapi spec, and from that spec, you've converted that into a client library (example: https://openapi-ts.dev). In such a situation, the client has a nice set of functions to call that abstract away the construction of the URL. But somewhere in the client, _urls are still being constructed_. And going back to my first complaint about this article, this contrived situation combines what the article states are two entirely distinct methods for designing apis (rest vs openapi).

Re: the article's description of rpc, I actually don't have any major complaints.

I've seen some truly insane TS types. Ones that validate SQL queries and stuff.

The problem with complex TS types is that there's no debug tooling. You can't set a breakpoint, you can't step through the type propagation. If there's an issue you have to just do trial and error, which can be extremely difficult if the type is super complex.

Here's a super complex type I ran into in the wild that has a bug that is extremely difficult to fix unless you burn hours on trial and error: https://github.com/openapi-ts/openapi-typescript/blob/main/p...

Related issue: https://github.com/openapi-ts/openapi-typescript/issues/1769...

> I must be a part of the problem because reading that type isn't too difficult. I also think types like this aren't innately problematic when they live in libraries.

Despite the star count on the repo, that particular type has a ton of bugs with it that are currently open issues, some of which are super esoteric to solve:

https://github.com/openapi-ts/openapi-typescript/issues/1778...

In this case ^ the problem was due to "behavioral differences based on the strictNullChecks ... compiler option. When that option is false (the default), undefined is considered to be a subtype of every other type except never"

Maybe I'm old school, but as long as we are using metaprogramming to solve a problem, I'd rather code gen dumb types vs. an ultra complex type that acheieves the same thing. Dumb types are easy to debug and you won't run into language corner cases like when `undefined extends` has different behavior when strict mode is on or off.

Tbh, there is no benefit of using this package if the API you are working with has an openapi spec, as there are other great libraries to help you generate accurate types such as https://github.com/openapi-ts/openapi-typescript. But I made this package to use when working with external apis that don't have an available spec.

Maybe I just have bad luck, but most of the libraries I've tried that are "crazy to look at" seem good in theory but are janky in practice. For example, openapi-fetch (https://github.com/openapi-ts/openapi-typescript/tree/main/p...), on paper seems great, but has lots of jank in practice.

And I would wager the bugs and jank are in no small part due to the extremely complex generics/constraints.

I was using TypeBox but switched to Zod. I like TypeBox but I found I don't actually need my schema to be a JSON Schema and the one time I did want a JSON Schema it was hard to get actual JSON back out of TypeBox.

The thing I like about Zod is the "refinements" and "transforms" and the new "overwrite" in Zod 4 was just what I wanted.

TypeBox does have a transform (https://github.com/sinclairzx81/typebox?tab=readme-ov-file#t...) but you can't transform and then apply more validations and then maybe another transform, etc. For example, I like to trim strings before checking length.

My hunch was that Zod v4 started using eval (or, more precisely, JIT compilation via new Function) for validation. This isn’t a bad thing — libraries like TypeBox, ArkType, and even Sury use similar techniques for speed.

Sury uses new Function under the hood. This approach makes it the fastest schema library available, but also means it cannot be used in environments that don't allow dynamic code evaluation, like CloudFlare Workers. Most users won't be affected, but might be an issue for some. Regarding safety of the approach you shouldn't be worried. Everything embeded to the generated code is escaped and thoroughly tested. Also, other libraries like TypeBox and Zod@4 use new Function under the hood as well.

The original library only supports Zod. While Zod is excellent, many developers use alternatives like Valibot, ArkType, and TypeBox. hono-openapi is validator-agnostic, offering first-class support for multiple libraries.

If you were willing to bring additional zod tooling or move to something like TypeBox (https://github.com/sinclairzx81/typebox), the json schema would be a direct derivation of the tools' input schemas in code.

I'd recommend TypeBox[1] as an alternative, which has a runtime “compiler” for generating optimized JS functions from the type objects. It also produces a JSON schema, which can be useful for generating API docs and API clients if needed.

It also has a companion library[2] for generating TypeBox validators from TypeScript definitions, which I'm currently using in an RPC library I'm working on.

[1]: https://github.com/sinclairzx81/typebox

Big fan of your work and impressed by your productivity. Currently reading https://www.oreilly.com/library/view/unifying-business-data/....

Currently experimenting with programmatic generation of json schemas via https://github.com/sinclairzx81/typebox. Trying to maximize reuse of schema components.

Was wondering if JSON BinPack is a good serialization format to sign json documents? Can it be used to somehow canonicalize json?

The documentation can be found here.

So far I like the commonly used approach in the Typescript community best:

1. Create your Schema using https://zod.dev or https://github.com/sinclairzx81/typebox

2. Generate your Types from the schema. It's very simple to create partial or composite types, e.g. UpdateModel, InsertModels, Arrays of them, etc.

3. Most modern Frameworks have first class support for validation, like is a great example Fastify (with typebox). Just reuse your schema definition.

That is very easy, obvious and effective.