TypeSpec: A new language for API-centric development

[domoritz]

This looks interesting but I already have TypeScript types for my APIs so I developed https://github.com/vega/ts-json-schema-generator which lets me generate JSON schema from the sources directly. Yes, it does have some oddities because the two languages have slightly different feature sets but it’s been working well for us for a few years. If I didn’t have TypeScript or a smaller API surface I’d be okay with typing again I would look at TypeSpec though. It definitely beats writing JSON schema by hand.

[usrusr]

Feels like cheating, next to the yaml of openapi anything will look good. And that's all while I'm still considering openapi one of the best things that have happened.

But I've also been kind of holding my breath for typescript making it's breakthrough as a schema language. More specifically its surprisingly big non-imperative, non-functional subset, obviously. And at first glance this seems to be exactly this, "what if we removed javascript from typescript so that only typing for JSON remains and added some endpoint metadata description to make it a viable successor to openapi and wsdl.

[tshaddox]

> next to the yaml of openapi anything will look good.

Challenge accepted!

https://github.com/bufbuild/protovalidate/blob/main/examples...

[vbezhenar]

TypeScript type system is very advanced. It won't be possible to generate corresponding bindings for all popular languages, while keeping them idiomatic. I'd prefer API language to be very simple and straightforward.

[BillyTheKing]

I've been using it for my latest API - I was looking for a tool that allowed me to describe APIs similarly to GraphQL and in a design-first sorta way. All these openapi editors just felt crazy clunky and made data-relationship within the API non-obvious. TypeSpec is a great tool, really helped me out here - was exactly what I was looking for!

[pjmlp]

> At Microsoft, we believe in the value of using our own products, a practice often referred to as "dogfooding".

One would think, unfortunely that is not how it looks like in the zoo of native Windows desktop development, or Xamarin/MAUI adoption in their mobile apps.

[madeofpalk]

Windows is dog fooding _all_ the native app development options simultaneously.

[jayd16]

Dogfooding doesn't mean write everything from scratch as soon as something new comes up.

[Savageman]

It must be a new policy, or maybe only for this product (which makes good marketing).

I've used Microsoft Graph to manage emails, and I'd be very surprised if they use if for Outlook...

[dexwiz]

So this is coming from Microsoft. I assume it’s going to be their answer to graphql. If the project is dogfooded internally, the tools may actually be half decent, compared to whatever an open source consortium cobbles together. Not sold yet, but might gain more traction.

[bterlson]

(I work on the team)

I wouldn't say that TypeSpec is like GraphQL, so it would be hard for TypeSpec to become that on its own. GraphQL has a lot of opinions that are required in order to build a concrete application (protocols, error handling, query semantics, etc.), whereas TypeSpec at its core is just an unopinionated DSL for describing APIs. Bindings for particular protocols are added via libraries, and a GraphQL library is something we have long considered.

So in short, if Microsoft invented a set of opinions that solved similar scenarios to GraphQL, it might use TypeSpec as the API description language in that context, but it wouldn't be fair to equate those opinions with TypeSpec itself.

[vbezhenar]

I failed to find an answer to the main question: what output languages are supported. The only way is to emit OpenAPI and then using one of their terrible generators?

[JoyrexJ9]

You can create your own emitters, there's info in the docs on how to do so. My team built a custom TypeSpec emitter to output a SDK and set of libraries

[thesuperbigfrog]

Looks like the Typescript version of WSDL:

https://en.wikipedia.org/wiki/Web_Services_Description_Langu...

Perhaps it will last longer than WSDL did?

[dexwiz]

I still use WSDLs, or rather the platform I work on does. Maybe not popular for new tech but they are still alive. Hate me, but I’d rather have generated xml than generate yaml.

[paulddraper]

You may already know this but:

1. A more exact analogy would be WSDL+SOAP.

2. WSDL and SOAP are defined in XML, and SOAP describes XML.

3. The popularity of these technologies followed the popularity (both rise and decline) of XML generally.

4. TypeSpec describes JSON and protobuf, and will likely also lose popularity if those formats do.

[vbezhenar]

WSDL issue was that it was designed by a committee of several huge companies. So it was inconsistent and bloated. Same could be said about many XML-related standards.

Nowadays big companies rarely work together and prefer to throw their own solutions to the market, hoping to capture it. That results in a higher quality approaches, because it's developed by a single team and focused on a single goal, rather than trying to please 10 vendors with their own agendas.

[DanielHB]

Would be nice if you could just import those typespec files in typescript (and other languages?) and get automatic typescript types from them.

Codegen is annoying and error prone.

[kristiandupont]

I generally prefer code generation. I don't see why it is "error prone" any more than anything else is. In fact, it means that errors aren't concealed in two levels of abstraction which can make them much harder to debug. Also, with generated code, you can add a build step to work around short comings or bugs in the generator where as you otherwise have no choice to live with it.

The "annoying" part I do get -- it's obviously nicer to have instant feedback than being forced to rebuild things -- so for things where you iterate a lot, that does weigh in the other direction.

[AntonCTO]

+1. It even looks very similar to TypeScript. Why not use TypeScript as a description of APIs in the first place? Get TypeScript types and even generate OpenAPI schema on the fly to serve it at `/openapi`?

[dbrower]

Will it translate to yaml for toolchains that want that?

I'd be delighted to have a high-level IDL that gave the same sort of thing that CORBA IDL gave us 25 years ago -- schema and stub generation for multiple languages.

[mnahkies]

I added support for typespec as an input specification to my openapi 3 based code generator a couple of days ago.

They provide an API to convert to openapi documents so it was pretty painless (https://github.com/mnahkies/openapi-code-generator/pull/158)

My focus is on doing both client sdk and server stub generation, though only typescript so far - will hopefully add other languages eventually, when I'm satisfied with the completeness of the typescript templates.

[bterlson]

The OpenAPI and Json Schema emitters can produce yaml.

[verdverm]

Bespoke languages are a hard sell and incur significant extra effort on the team building this.

1. People don't want to learn bespoke languages.

2. You have to build all the ecosystem tools for a language (compiler, docs, language-server, IDE integrations, dependency management)

Similar endeavors are WaspLang and DarkLang, which I have yet to see in the wild or (meaningfully) on HN. Better to use an existing language and focus on the value add.

I personally built something with similar value add (source of truth -> all the things). I've been through some of these pain points myself.

https://github.com/hofstadter-io/hof

The idea is CUE + text/template = <all the things> (not limited to APIs)

[BillyTheKing]

It's this or writing openapi ymls... Even for people who know yml picking this up to define and write basic openapi definitions is much simpler than writing an openapi doc from hand, which is really painful

[cjonas]

New languages are at an even bigger disadvantage now with the rise of generative AI programming. A fancy new framework that is objectively better may actually be less productive because AI haven't been trained on it

[lifty]

Thanks for hof! Thinking of using it for a project. In what state is the project? I noticed that commits slowed down lately and I was wondering if you consider it stable at the moment and can be used as is.

[joelwilsson]

Looks like a competitor/alternative to Smithy, https://smithy.io/2.0/index.html. Since at least one person from the TypeSpec team is here, do you have any thoughts on how they compare?

[jen20]

This was my thought too - since smithy is already out there and used in a similar domain, it would be useful to have a comparison. “Doesn’t have Kotlin and Gradle all over the show” seems like a significant advantage in favour of TypeSpec.

[mdaniel]

some prior discussion, just not from the main url: https://news.ycombinator.com/item?id=39833321

[favflam]

What is wrong with protobufs and grpc?

[_ZeD_]

Both of them. Both of them are wrong.

[frankrobert]

The protobuf v3 spec doesn't support required fields anymore and also mandates field ordering. In my opinion, both of these are deal breakers for generating types and typed clients for your FE environment (or any consuming application). Your entire schema would be Partial<T> on every field. It defeats the purpose of the type safety to me

[62951413]

CORBA, Avro RPC, Thrift RPC, gRPC, now this. In this industry each generation wants to re-invent IDL every decade. But anything is better then JSON over HTTP so why not this.

[hoppersftw]

lol, about 5 years too late. I've been developing REST APIs with Ballerina for some time now and there's a multitude of quality of life improvements for me. Look at this https://ballerina.io/learn/write-a-restful-api-with-ballerin...

I guess it's NIH for Microsoft. Oh well, at least it's TypeScript.

[H12]

Seems like this exists in a similar problem domain as pkl?

https://pkl-lang.org/index.html

[vaylian]

Not quite. pkl is a language that is mostly designed for parsing and serialization of data. TypeSpec is a language that is designed to describe APIs and the structure of data that those APIs take. You can actually combine the two technologies as follows:

1. Read a .pkl file from disk and generate (for example) a Person struct with a first, last name and an age value.

2. Let's say that according to some TypeSpec, the HTTP endpoint /greet accepts a POST request with a JSON payload containing a first and a last name. You convert your Person struct into a JSON literal (and drop the age field in the process) and send it to the HTTP endpoint

3. You should receive a greeting from the HTTP endpoint as a response. The TypeSpec may define a greeting as a structure that contains the fields "message" and "language".

4. You can then use pkl to write that greeting structure to disk.

Sidenote: pkl also supports methods[1] but in almost all use cases you only use pkl to define which fields your data has. TypeSpec cares most about the methods/endpoints. Of course, you still need to define the shape of the arguments to these methods and that is where you have a bit of overlap between these two technologies. I can imagine that you would generate pkl definitons from TypeSpec definitions.

[1] https://pkl-lang.org/main/current/language-reference/index.h...

[ActionHank]

Yeah, but this one is better because new.

I might be wrong, but I suspect that the crazy hype-driven-development has started to move on from frontend to backend.

[kkukshtel]

I wish any of Typespec, Cue, Pkl, Dhall, etc. would just implement their core functionality in C with an ABI for other language bindings. Needing to use whatever dep they decided to operate with as part of adoption of the language itself is a big ask. I want to try out your config language, I don't want/need all of node to make this happen.

[verdverm]

CUE is building out language bindings for various languages right now

Since CUE is written in Go, you can output a .so that is then used like your C based desire, if I understand you correctly

[aleksiy123]

Has validations thats awesome.

I have a project in mind and was looking for something like this. Closest I found was CueLang.

Now just need to find the time...

[danhudlow]

The toy example with an API definition that includes zero semantic documentation doesn’t give me a lot of confidence that TypeSpec helps author API definitions that are actually good. It’s easy to create a concise language if all you want to generate is boilerplate.

[stapert]

Looks interesting, but what would be the advantage of this over just writting an openAPI specification? It's more concise, but currently this would require you to increase your toolchain to go from TypeSpec to openAPI to generating code.

Any plans to add code generatio to this project?

[leetrout]

I love the idea of tools like this. I have looked at Buf and Fern and am curious to try this as well.