Microsoft TypeSpec | Hacker News Reader

Microsoft TypeSpec

typespec.io

107 pointsbundie81 comments

I just don’t get why they absolutely had to come up with new syntax. All of this would have been possible with standard Typescript, unlocking heaps of existing tooling, editor support, and prior knowledge. But no! Let’s come up with a new language, bespoke compiler, new LSP and IDE integrations, and make developers learn yet a new DSL.

It’s creating changes for the sake of creating changes.

We first tried a TypeScript DSL and I really wish it would have worked for our use cases (e.g. describing complex REST APIs in Azure), but unfortunately it didn't.

I explained a bit more here last time TypeSpec was on here: https://news.ycombinator.com/item?id=39843184

https://www.speakeasy.com/guides/api-frameworks/typespec

This post has a bit more detail about why "we don't need more standards" might not be the correct take here

(Disclaimer speakeasy is a client but I wasn't directly involved in writing this and just figured it's pretty relevant here)

Pydantic/FastAPI - it is well designed, industry proven. Doesn’t need custom DSLs.

Having your Framework generate the Docs is nice, but doesn't always fit.

At work, I build backends for mobile applications. When designing new APIs to be consumed by apps, we want input from the mobile developers. We facilitate this by having an api-specs repo with TSP and using Pull Requests to discuss, track and finally commit on new APIs.

It also allows mobile developers to open PRs with changes they want. The contracts are basically an interface that both sides can discuss and agree on.

Came here to post this. We use Django Ninja at work (basically FastAPI style endpoints for Django), and it automatically does OpenAPI and Swagger docs for us. Whatever web framework one chooses in whichver language should def have this built-in by now, IMO, seems like tablestakes for anything larger than a "micro-framework"

Nah, it doesn't really say why they didn't just use TypeScript.

Off the top of my head, I don't think you can perfectly describe the type (string format) of an UUID in typescript types, which you can do with OpenAPI. That may be a reason.

You can do it with template string types: https://ybogomolov.me/type-level-uuid

The built in DOM types for the browser's `crypto.randomUUID` function actually already use this technique to a lesser extent: https://github.com/microsoft/TypeScript/blob/121c5dd36bd87e4...

You can get by, e.g. you can use JSDoc comments describing format or pattern, generic types taking a parameter of either format or pattern along with a base type, or create a custom well-known type you define as having the properties of a UUID. But aside from comments, this is not reflected well in the tooling, and none of these options compose particularly well.

See n2d4's comment but also AJV's JSONSchemaType

import { JSONSchemaType } from 'ajv'

It will bridge the JSON Schema and TypeScript types

We've found this useful too:

import { OpenAPIV3_1 as oa } from 'openapi-types'

export type Schema<T> = JSONSchemaType<T> & oa.SchemaObject

We validate that the type aligns with the schema and load the schema to validate all incoming requests

It's even worse, you still need node to run this thing, so you don't avoid the node dependency.

You don't get a bonus and promotion for just using TypeScript.

Facts, bonus-driven "innovation".

Also why Google has so many dead products.

"3 years of experience with TypeSpec"

Corollary: Not even a patent cube.

"Looks good on my CV" syndrome.

Is that why a lot of teams inside azure use it for their API? Do all of them just do it for their CV? Or maybe it is that you're missing something ?

I'm not sure why you're getting downvoted. It might be hitting too close to home for some. But yeah, 95% of developers choose things to do to boost them for the next job.

I believe that 99% of the time, a reuse of older technologies results in greater innovation that is more stable and a return is multiple of the underlying foundations.

This applies here as well. Typescript could go a long way.

But admittedly, writing a grammar, parser and then a whole compiler along with its tooling of a new DSL is fun for sure but does look good on CV as well.

I didn't say anything more than that.

I downvoted both of your comments because I think it's rude and insulting to assume the motivation of someone's work is self-aggrandizing, and to dismiss out of hand the work might be motivated by technical needs because you can't immediately recognize those needs. I find the attitude frustrating, similar to the other common HN dismissal of "I could build it in a weekend".

> Create a new TypeSpec project
> Run the following command in a clean directory to create a new TypeSpec project.
> tsp init

> This will prompt you with a few questions. Pick the Generic REST API template...

I’d just like to interject for a moment. What you’re referring to as REST, is, in fact, JSON/RPC, or as I’ve recently taken to calling it, JSON plus RPC. JSON is not a hypermedia unto itself, but rather a simple data format made useful by out of band information often specified with tools such as your TypeSpec project or similar.

Many computer users work with a canonical version of REST every day, without realizing it. Through a peculiar turn of events, the version of REST which is widely used today is often called “The Web”, and many of its users are not aware that it is basically the REST-ful architecture, defined by Roy Fielding.

There really is a REST, and these people are using it, but it is just a part of The Web they use. REST is the network architecture: hypermedia encodes the state of resources for hypermedia clients. JSON is an essential part of Single Page Applications, but is useless by itself; it can only function in the context of a complete API specification. JSON is normally used in combination with SPA libraries: the whole system is basically RPC with JSON added, or JSON/RPC. All these so-called “REST-ful” APIs are really JSON plus RPC.

You can be technically correct or you can move on and accept that terminology means what majority of people mean.

https://learningenglishwithoxford.com/2024/02/29/15-modern-e...

i will NOT

https://htmx.org/essays/how-did-rest-come-to-mean-the-opposi...

Eagerly awaiting AsyncAPI Support: https://github.com/microsoft/typespec/issues/2463

AsyncAPI support would make TypeSpec the end-all/be-all API spec tool for a lot of people.

TypeSpec looks amazing - but until we can go "all in" on using it for both our external and internal API, it's difficult for the team to justify yet another new DSL. It's needs to support all of our common API definition woes, and currently it only addresses 50%.

As someone mostly using compiled programming languages, I am perplexed about the built-in types that this new language provides.

According to https://typespec.io/docs/standard-library/built-in-data-type...:

* unixTimestamp32, but no 64-bit version

* plainDate that can be "April 10th" without the year

* DefaultKeyVisibility, OmitDefaults.. what?

I am genuinely curious how did that happen. Design by committee? Some secret use cases that leaked into specification?

How many times have we invented this particular wheel already?

OpenAPI (formerly known as Swagger) is the actual standard in this problem space.

It's good enough and these bespoke solutions that add nothing but DSL syntactic sugar are dead on arrival.

https://www.servant.dev/

It’s an evergreen project. I’ve seen various incarnations of this since the 90s.

The xkcd about "standards" is from 2011, so a lot ? https://xkcd.com/927/

This came up a few months ago here: https://news.ycombinator.com/item?id=40206124

If I’m a lowly nerdling writing a backend in express and typescript, what do I use this for?

Generating client code to query your apis with function calls. Mostly useful when you have more than one client codebase.

This is part of the Api-First paradigm. Instead of your controllers/handlers being the authoritative "Truth", the API spec is.

You and your team spend time arguing/debating the API from the perspective of a user. "I need X data from Y service", etc. The document then becomes the "blueprint" for your system.

Think of it as TDD but viewed from a different angle. In a microservices system, this has a tremendous amount of advantages, including being able to codegen your handlers and models, maintain consistency across the entire API, unified api documentation, increase testability of your controller/handler interface, and more.

It’s a lot of language for a DSL to define services. Smithy[1] sounds more balanced and extendable

[1]: https://smithy.io/2.0/index.html

Is there a good UI for this? I want to love OpenAPI but for complex JSON i've found OpenAPI UI's to be unusable. At this point i'd hand write my API specifications if it meant i could have a useful UI.

TypeSpec is a specification document generator - it outputs OpenAPI specification files, which you can feed to any OpenAPI documentation generator, such as Swagger or Redocly.

Originally this project also advertised support for GraphQL, but never implemented it: https://github.com/microsoft/typespec/issues/1390

Would be compelling to have a way to represent both OpenAPI and GraphQL in a common upstream schema...

It is being worked on. The best place to follow the development is our discord, there's a channel for graphql.

Good to hear. Thanks!

Related April 2024:

Introducing TypeSpec: A New Language for API-Centric Development

https://typespec.io/blog/2024-04-25-introducing

(https://news.ycombinator.com/item?id=40206124)

Oh, so if I want to add a simple checkbox boolean field on a model on a proper best practices Clean Code Uncle Bob-approved code base in 2024, I have to:

- add it in the database model

- make a database migration for the field

- add it in the DTO for the API because we don't want to couple our persistence layer to our business logic or something

- add it to gRPC/Protobuf models so other services can call it

- add it to the new TypeSpec model thing

- update tests of all of the above

I love in tech 2024, it's full of people who talk about "DRY" who force you to repeat the same things over and over again, and this is "clean code", and if you don't like it, fuck you, you aren't a "culture fit". Utterly batshit insane.

I understand your frustration, but this is the price paid for schema compliance across systems.

One qualification: the TypeSpec model should help generate your API DTOs (OpenAPI, Protobuf) etc. So hopefully that saves a step or two.

As an aside, I have tried doing a full stack TypeScript application where database types trickle down to the client, it ended poorly, since the API affordances can and should evolve separately from the database design. Therefore, I do feel that separation of database and API types is necessary.

Now, let me tell you about microservices... (:

The syntax leaves a bad first impression. I'm getting flashbacks to Java EE/JAX-RS days.

What does this do that Protobuf doesn't?

Unions, generics, required fields, default values, enums that don't pollute the global namespace are things that immediately caught my eye. I assume it also doesn't repeat Protobuf's the mistake of not being able to distinguish between a missing string value and an empty string value.

Protobuf is old, and has some really strange warts that are only explainable historically (for example, by reference to the behavior of C++, which used to be Protobuf's primary target).

I have long used protobuf as the source of truth for API's, but it does have some weird idiosyncrasies since its primarily a binary spec, and doesn't always transfer to json well (e.g optionals, maps, etc).

That's totally fair feedback. Particularly optionality having been removed from proto2 to proto3 is confusing.

As someone who works on TypeSpec, my feeling is that they are mostly different things. TypeSpec is a general purpose DSL which supports "emitting" to protobuf and other things, but in and of itself doesn't prescribe any particular protocol or serialization format.

> TypeSpec's standard library includes support for OpenAPI 3.0, JSON Schema 2020-12 and Protobuf.

Gotcha. I think this might be where Protobuf falls short because you have to "source" the tooling for all its different outputs, but support for OpenAPI 3.0 spec generation has existed for over a year.

Protobuf is a binary spec isn’t it?

The default transport (gRPC) certainly is, but HTTP RPC translation/gateways are easily generated.

Microsoft NIHS (not-invented-here-syndrome)

yeah like when they uselessly reinvented flow with typescript

also reinventing atom with vscode.

To Microsoft's credit, both are better alternatives, with VS Code being _significantly_ superior to Atom.

I think that was the grandposter's sarcastic point.

yes sorry, i should be more explicit going forward

Superior in performance and easy-of-use, which for most people is all that matters. Atom still won in general "hackability", which was one of its main selling points. Unfortunately that didn't stick, and the kind of people that want a hackable-to-the-core editor are probably using Emacs. I know I am.

TypeScript wasn't better than Flow when it gained dominance. It happened because Microsoft created an out-of-the-box experience with VS Code that worked great with TypeScript but made Flow types look broken.

More generally Microsoft treated Typescript as a product - they built it based on feedback from outside users and worked hard to make it easily adoptable and to grow a community around it. They are also "pragmatic" - willing to have weird, unsound semantics if it's needed to help people adopt Typescript and model existing JS ecosystem patterns.

Flow has always been an inwardly-focused project that is for Facebook's needs first. The Flow team at FB made an explicit decision to focus more on compiler performance improvements (what Facebook's usage needed) over outside users & community.

The way I remember, when flow was introduced, you had to do small changes to 3rd party dependencies your code might have had to make them flow-compatible.

With typescript you could just write a type definition file for any 3rd party library, so you could essentially make any 3rd party dependency "typescript compatible" without needing to change its code.

This small difference made a huge impact for adoption. Eventually flow also got that feature but by then the adoption difference was already too big.

From what I remember TypeScript was a superset of Javascript, so you could just rename your files and enable TypeScript and it all worked, and then gradually move stuff over. That probably helped a lot.

Not just to ruin a fun joke with silly facts, but key parts of VS Code predated Atom.

not the part where they actually released it and not electron aka atom shell

It was released. It was on a growing number of webpages and an important part of the Dev Tools of IE9+ (also giving them a massive install base from before Atom existed). If Atom didn't build Electron what became the VS Code team might have built something similar on their own eventually (though it probably would have been IE-based and Windows-only in that alternate history). It truly seemed convergent evolution at work.

Looks nice!

Any recommendations for Python backend integration?

why should one use this if both thrift and protobuf solves 90% of the needs.

> list(@query filter: string): Store[];

I despise "hidden" languages smuggled in string types. Both Microsoft <https://learn.microsoft.com/en-us/graph/filter-query-paramet...> and Google <https://google.aip.dev/160> are terrible about these embedded languages

Since Microsoft is one of the offenders, how about any novel type system try and model their own API and only when that's possible should they taut their superiority over the existing, proven standards

Normally I'm happy with efforts like these, but do we really need another standard? Just use OpenAPI directly folks.

How often are people hand-writing OpenAPI specs? At least in my experience, such specs are generated from some "authoritative" implementation. This looks like it aims to move the contract-y bits into something less verbose than OpenAPI and less tied to a specific implementation.

I did. I cannot recommend this approach - you often gain little for a lot of pain for editing Yaml. Better just use DSL in your backend language and generate the spec.

Generating the spec from your code is only an option if you are deploying a monorepo.

Hand writing OpenAPI is horrible in my experience. Maybe it's particularly bad because we have a lot of small types that are nested into each other and get composed together a lot, but at the end of the day our OpenAPI YAML needs to be about 1.2MB and I just can't see maintaining that by hand in a text editor.

Handwriting OpenAPI for a bunch of REST APIs will destroy both your keyboard and your sanity. Prefer writing good old x86 assembly over OpenAPI specs. The OpenAPI folks designed the most verbose spec language possible. I guess they took inspiration from Cobol.

Isn't OpenAPI specific to REST? The page also mentions protobuf, for example. Being able to generate clients and servers for those things might be useful, although how well it integrates with the client/server technologies will be the hard bit.

No, OpenAPI has nothing to do with REST. (In fact REST API's are an extra pain in the ass to desribe properly in OpenAPI.)

Agreed, OpenAPI is battle tested and has all the tooling I could ever dream of and then some. It doesn't matter who needs to consume it, there's tools for any and every language.

AWS also has it’s own implementation of this with smithy

Reply on news.ycombinator.com