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.
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.
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.
There are a few emitters in our standard library - OpenAPI 3.0, JSON Schema 2020-12, and Protobuf. REST client and service emitters for a few languages are coming online now and should be ready in the next couple months.
Moreover, compiling an IDL to N languages is substantially easier than compiling implementation code across N languages, especially when generating idiomatic code is a requirement. A language purpose-built for this task is going to produce better results while having substantially lower complexity.
Sorry, could you elaborate? If I'm creating an API using, say, ASP.NET Core or Go, I can generate OpenAPI spec out of actual implementation. How this "IDL" fits into the workflow? Is this another output in addition to OpenAPI spec?
TypeSpec is designed primarily as an API first tool as opposed to being an output. In the context of ASP.NET and HTTP/REST APIs, our goal is that you can write your spec and generate much of the service implementation and clients. From this same source of truth you could also emit clients or service implementations in other API definition formats like OpenAPI, schemas like JSON Schema, and other things besides.
In my (limited) experience so far with TypeSpec - it really shines in an API first approach, so you define your API before you implement it, but not so much the other way around.
I would have expected a bit more than type specifications, maybe some behavior specifications also? Something like Daan’s type states. But I get why we are still splitting hairs over data types.
I've been working on an API spec language where state changes can be modeled with linear logic: https://apilog.net/docs/why/ It doesn't have "schemas" yet though. Which may seem odd given they are a crucial part of this type of languages. :-) But it is because I am experimenting with different designs on that front.
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.
The graphql spec does include a DSL to describe the api though, so this is similar to that specific piece. The DSL powers a lot of what people like about grapqhql, like auto-generating a client sdk with type safety. This library does seem to cover a subset of the graphql benefits that aren’t baked into REST by default.
Yup, similar to that specific piece, and I definitely agree that GraphQL's DSL shows how much the DX of the description language itself matters, and how codegen is a productivity multiplier. I think gRPC also demonstrates this. You can think of TypeSpec as an attempt to bring these benefits to any protocol, schema vocabulary, or programming language.
I think it can be, but it can also be used with OpenAPI to great effect as well. We're not trying to replace OpenAPI, OpenAPI is great in many ways and is useful for many people. In general we believe strongly in being interoperable with the existing API description ecosystem.
This gives me an excuse to revisit smithy. Curious if editor support is still poor in VSCode. Last time I cracked it open, I found that (1) there was no AST introspection and (2) existing language support tooling was lacking modern features (click to definition, autocomplete of ambient/imported smithy types). (2) made me attempt to write a language server and I stopped when I realized there was no easy way to hook into the parser.
Grats on the release! It will be awesome to see how far y'all can push codegen quality from an OpenAPI source of truth.
I worked on this extensively inside Azure and I know it is not an easy problem (and with more JSON Schema coming in 3.1/4.0, it is only getting harder). There are a lot of API patterns that you want to expose purpose built client abstractions for. Pagination is a big example. If you stick to OpenAPI, you have to ensure your specs use the patterns your client generator recognizes, and it's not always trivial for authors to know how to express that pattern and for your codegen to infer that pattern. In Azure we tended to rely more on custom extensions to OpenAPI because it made the contract a lot clearer and less error prone, but then you lose interoperability.
One thing to consider - I work on TypeSpec[1], and one of the main reasons we built it is to allow encapsulation and reuse of patterns in a first-class way. So, rather than the contract being "endpoints which declare parameters and/or return types with these shapes are inferred to be paginated endpoints", the contract can be "use Page<T>" and the emitted OpenAPI conforms to the contract without effort. It would be fun to see a Stainless TypeSpec library for all the patterns your codegen supports!
