TypeSpec

Qué es

TypeSpec es un lenguaje creado por Microsoft para describir APIs y estructuras de datos de servicios en la nube. Su sintaxis está inspirada en TypeScript (modelos, interfaces, decoradores) y actúa como fuente de verdad única: defines la API una vez y un compilador (la CLI tsp) genera distintos artefactos a partir de ella. Es open source bajo licencia MIT y se mantiene de forma muy activa.

Para qué sirve

• Generar especificaciones OpenAPI 3.0 a partir de una definición declarativa de la API.
• Producir esquemas JSON Schema (2020-12) y definiciones Protobuf desde el mismo origen.
• Generar código de cliente y servidor, así como documentación, evitando ficheros escritos a mano.
• Aplicar reglas y buenas prácticas mediante su framework de linter y crear salidas a medida con su framework de emitters.

Cuándo usarlo

Encaja cuando trabajas con APIs grandes o múltiples protocolos (REST/OpenAPI, gRPC, JSON Schema) y quieres una única fuente de verdad en lugar de mantener a mano varios ficheros de especificación. Frente a escribir OpenAPI YAML directamente, TypeSpec ofrece tipado, reutilización y herramientas de editor. Alternativas como Smithy de AWS o el propio OpenAPI a mano resuelven necesidades parecidas con otro enfoque.

Ejemplo

Instalación de la CLI y arranque de un proyecto REST:

npm install -g @typespec/compiler
tsp init
tsp compile .

Definición básica de un modelo y una operación:

import "@typespec/http";
using Http;

model Pet {
  id: int32;
  name: string;
}

@route("/pets")
interface Pets {
  @get list(): Pet[];
}

Puntos clave

• Sintaxis inspirada en TypeScript con modelos, interfaces y decoradores como @route, @get o @path.
• Multiprotocolo: una misma definición emite OpenAPI, JSON Schema, Protobuf y más.
• Altamente extensible mediante emitters y decoradores personalizados.
• Soporte de editor en VS Code y Visual Studio: resaltado, autocompletado y validación.

Ten en cuenta

Es un lenguaje y un compilador adicionales que el equipo debe aprender y mantener en el flujo de trabajo, lo que añade un paso de build (tsp compile) respecto a editar OpenAPI directamente. Requiere Node.js para la CLI. Para proyectos pequeños con una API sencilla puede resultar excesivo frente a escribir la especificación a mano.