TypeSpec: A new language for API-centric development

Original Article ↗ Hacker News Discussion ↗

Purpose and Role of TypeSpec

  • Positioned as an API‑first, language-agnostic DSL for describing APIs and data, then generating:
    • OpenAPI, JSON Schema, Protobuf, and (soon) REST clients/server stubs in multiple languages.
  • Intended as a single “source of truth” for schemas across services, platforms, and languages.
  • Emphasizes easier, more expressive authoring than raw OpenAPI YAML or JSON Schema.

Schema‑First vs Code‑First

  • Pro‑schema‑first:
    • Better for multi-team, multi-language systems where teams share contracts but not implementation languages.
    • Encourages deliberate API design, supports mocking and parallel client/server development.
    • One spec can generate multiple servers and clients; external consumers can propose schema changes.
  • Pro‑code‑first:
    • Many frameworks (ASP.NET, Go, FastAPI, NestJS, etc.) already generate OpenAPI from code.
    • Avoids maintaining spec and implementation separately; code is seen as the most accurate documentation.
    • Some see spec-first as extra process that can drift or become a “third artifact” to track.

Comparisons to Other Technologies

  • Compared to:
    • OpenAPI: more concise and modular; OpenAPI mainly becomes an emitter target.
    • GraphQL: similar in having a DSL and codegen, but GraphQL is opinionated about protocol/query semantics, whereas TypeSpec aims to be protocol-agnostic.
    • Smithy: seen as a close analogue; TypeSpec perceived as similar but without JVM/Gradle baggage.
    • Protobuf/gRPC, CORBA, Thrift, Avro RPC: viewed as another entry in the recurring “IDL every decade” pattern.
    • Cue, Pkl, Dhall: related configuration/schema languages; some see overlap and potential integration.

Tooling, Emitters, and Ecosystem

  • Current standard emitters: OpenAPI 3, JSON Schema 2020‑12, Protobuf.
  • REST client/server emitters for several languages are reportedly in progress.
  • Custom emitters can be written; at least one user reports successfully generating a TypeScript SDK and libraries.
  • Some ask for direct language bindings or core implementation in C for easier embedding, instead of requiring Node.

Critiques and Concerns

  • Skepticism about yet another bespoke language:
    • Learning overhead, need to build full language tooling stack, and fragmentation.
    • New languages may be disadvantaged with general-purpose LLMs lacking training data.
  • Some argue TypeScript itself (or subsets) already works well as a schema language with existing generators.
  • Worries that complex type systems or validation rules may not map idiomatically across target languages.
  • Questions raised about support for richer behavioral/state specifications and asynchronous/event-driven APIs (answers are unclear in the thread).