microsoft/typespec

Features

• API Definition Languages - Provides a dedicated language for defining cloud API shapes and generating OpenAPI, JSON Schema, and client/server code.
• Contract-First API Frameworks - Defines API shapes and endpoints in a single source-of-truth language before generating code and documentation.
• Decorator-Based - Attaches metadata to types and operations using decorators for generating documentation, schemas, and code.
• Inheritance-Based Model Extensions - Creates new models that inherit all properties from a parent model, adding or overriding fields.
• CRUD Operations - Defines create, read, update, and delete operations for resource models using HTTP verbs and route decorators.
• Automatic CRUD Route Derivations - Automatically derives RESTful CRUD routes and semantics from resource model declarations.
• Path and Query Parameter Declarations - Provides a decorator-based system for declaring path and query parameters in API definitions.
• Numeric Range Constraints - Defines integer and floating-point values with specific bit widths and signedness for data storage and serialization.
• Custom Scalars - Defines custom primitive types by extending existing scalars with specialized encoding rules.
• Type Definition Reuse Mechanisms - Provides templates, aliases, and spreads to reuse type definitions across API models and operations.
• Query Parameter Configurations - Provides a decorator-based system for configuring HTTP query parameter options in API definitions.
• Composable Schema Builders - Builds models by extending, composing, or spreading other models to define shared property sets.
• API Data Shapes - Describes the structure of entities and their properties using a model construct to represent API data shapes.
• API Payload Constraint Validators - Defines structured types with property constraints, string formats, and numeric limits for API payload validation.
• Named Field Schemas - Defines schemas with typed, named fields supporting optionality and default values for API data structures.
• Unified API Syntax Designers - Models REST, gRPC, and other API protocols using a unified, extensible syntax.
• API Code Generators - Writes emitters and decorators to produce client libraries, server stubs, or documentation in any target format.
• Multi-Protocol Code Generators - Compiles a single definition into multiple output formats like OpenAPI, JSON Schema, and Protobuf.
• Versioned Element Addition Tracking - Records the API version when models, properties, or operations were first introduced.
• API Evolution Tracking - Records changes to models, properties, and operations across API versions using decorators that track additions, removals, renames, and type changes.
• Custom Code Generators - Creates custom output formats by writing emitters that transform TypeSpec definitions into any target artifact.
• Multipart Part Configurations - Ships a decorator-based mechanism for configuring multipart HTTP part options in API definitions.
• OpenAPI Specification Generators - Compiles TypeSpec definitions into OpenAPI 3.0 specification files for standard API tooling.
• Automatic Route Generators - Automatically constructs REST API routes from resource models and operation decorators.
• HTTP-Verb Controller Generators - Assigns specific HTTP methods to operations using decorators like get, post, put, patch, or delete.
• Versioned Element Removal Tracking - Records the API version when models, properties, or operations were removed.
• PATCH Operation Configurations - Provides a decorator-based system for configuring HTTP PATCH operation options in API definitions.
• Rules - Defines naming rules for models, enums, operations, and properties in API definitions.
• Path Parameter Configurations - Provides a decorator-based system for configuring HTTP path parameter options in API definitions.
• API File Transfer Declarations - Provides a declarative mechanism for defining file transfer operations in API definitions.
• File Upload and Download Models - Provides a model-based system for defining file upload and download payloads in API definitions.
• Route Segment Configurations - Provides a decorator-based system for configuring URL path segments in API route definitions.
• Class Inheritance - Establishes explicit inheritance relationships between models for code generation in class-based languages.
• Code Definition Namespaces - Groups related models and operations into namespaces to keep API definitions manageable.
• Typed Function Declarations - Provides a typed function declaration system for defining API operations with typed inputs and outputs.
• Generic API Interfaces - Defines generic operations within interfaces that accept type parameters for flexible reuse across data types.
• Type Constraint Combinations - Combines two or more type definitions into a single type that must satisfy all constituent types simultaneously.
• Discriminated Unions - Provides a discriminated union type system for API definitions with serialized discriminator fields.
• Type Namespace Organization - Groups related type definitions under named scopes to avoid naming collisions and improve structure.
• Namespace Imports - Provides a mechanism to import all types from a namespace into the current scope for unqualified access.
• Decorator Annotations - Attaches metadata or behavior to a type by applying a decorator, optionally with arguments.
• Custom Decorator Definitions - TypeSpec defines a new decorator in JavaScript that can inspect or modify TypeSpec types during compilation.
• Structural - Validates type assignments based on structural compatibility and numeric widening rules.
• Constrained Template Parameters - Defines reusable types and operations with type parameters, constraints, defaults, and named arguments for flexible composition.
• Authentication Composition - Combines multiple authentication methods at service or operation level with optional scoping.
• API Authentication Schemes - Declares which security mechanism protects each API endpoint in the service definition.
• Property Spread Reuse - Copies properties between models using the spread operator for reuse without inheritance.
• Header Parameter Configurations - Provides a decorator-based system for configuring HTTP header parameter options in API definitions.
• Structured Error Responses - Defines structured error response models for resource operations.
• Version-Specific Model Tagging - Tags models and operations with their introduction version for versioned API evolution tracking.
• Data Schema Validation - Exports JSON Schema definitions from shared models to validate data consistency across services.
• HTTP Parameter Declarations - Provides a decorator-based system for declaring HTTP parameter locations in API operation definitions.
• API Metadata Decorators - Attaches metadata, validation rules, and lifecycle visibility to API models and operations using decorators.
• API Documentation Annotations - Attaches descriptive text to models, operations, and properties using decorators for generating external documentation.
• Server-Driven Pagination Configurations - Provides a decorator-based system for configuring server-driven pagination in API definitions.
• API Operation Composition - Defines operations with typed parameters and return values, supporting templates and interface composition for reusable endpoints.
• Resource Key Parameter Copies - Provides a mechanism for copying resource key parameters between models for nested API operations.
• OpenAPI Specification Generators - Compiles TypeSpec API definitions into OpenAPI 3.0 specifications and other artifacts.
• Named Constants - Declares sets of named constants with optional assigned string, integer, or float values.
• Authentication Requirements - Defines authentication requirements for services and specific operations in the API definition.
• Operation Metadata - Adds tags, summaries, descriptions, and security details to operations for documentation and tooling.
• Structured Type Declarations - Declares structured types with named fields, optional properties, and default values for API data modeling.
• Single Value Validators - Validates values against built-in constraints like minLength and maxValue using decorators.
• Namespace Scopes - Brings types from a different namespace into the current scope for convenient use without full qualification.
• HTTP Lifecycle Visibility - Controls which model properties appear in create, read, update, or delete operations by tagging them with lifecycle phases.
• Property Spreading Utilities - Ships a property spreading mechanism that copies all properties from one model into another.
• API Data Shapes - Defines data models and service interfaces using a concise language to serve as a single source of truth for API definitions.
• API Data Types - Defines primitive types and built-in models that map directly to OpenAPI schema types for API definitions.
• API Metadata - Provides title, description, version, license, and contact information for the API.
• API Server Definitions - Specifies one or more base URLs for the API using a decorator on the namespace.
• API Versioning - Declares supported API versions and associates models and operations with specific versions.
• API Version Change Trackers - Declares API versions and tracks changes to models, properties, and operations across releases.
• Versioned Change Trackers - Tracks additions, removals, renames, and type changes of models and operations across API versions.
• Versioned Namespace Declarations - Associates namespaces with version enums to declare multiple API versions.
• Versioned Operation Additions - Records the API version in which each operation was first introduced using decorators.
• Union Types - Defines a type that can be one of several specified types, optionally naming each variant.
• Intersection Types - Creates a type that must satisfy all specified constituent types simultaneously.
• HTTP Methods - Assigns an HTTP method to an operation using a decorator, defaulting to post or get.
• Standard HTTP Error Responses - Provides predefined models for standard HTTP error responses in API definitions.
• HTTP Status Code Management - Decorates a response property with a numeric status code, supporting literal types and discriminated unions for multiple response shapes.
• Operation Routes - Assigns URL paths to operations with path parameters and inheritance from parent namespaces or interfaces.
• Parameterized Operation Templates - Defines generic operation signatures with type parameters for instantiation with specific resource types.
• Request Body Definitions - Marks model properties as HTTP request body payloads for API operations.
• Resource Models - Defines resource models that automatically generate RESTful URL paths and CRUD operations from decorated types.
• Reusable Parameter Models - TypeSpec defines a shared model of parameters and applies it across multiple operations using the spread operator to reduce redundancy.
• Content Negotiation - Serves different response formats from the same endpoint based on the client's Accept header.
• Response Models - Defines structured HTTP response models with status code, headers, and body for API operations.
• REST API Services - Defines REST service endpoints with metadata like title and server URL using decorators on the API definition.
• Multi-Response Modeling - Provides a union-based mechanism for declaring multiple possible response bodies and status codes per operation.
• Route Prefixes - Groups API operations under common URL paths by decorating namespaces or interfaces with route prefixes.
• HTTP Routing - Declares URL paths, HTTP methods, status codes, headers, and query parameters for RESTful service endpoints.
• Schema-Driven API Generators - Generates API schemas, client code, and documentation from declarative data models.
• Service Endpoints - Declares API operations with typed parameters and return types to represent service endpoints.
• Interface Composition with Extends - Combines operations from multiple interfaces into one by using the extends keyword, enabling modular API design.
• Open Property Sets - Combines known fields with arbitrary additional properties using spread and extends operators.
• Type Alias Definitions - TypeSpec assigns a shorthand name to a type expression, such as a union, for reuse throughout the specification.
• Versioned Property Type Changes - Records property type changes across API versions, preserving old types for earlier versions.
• API Operation Groupings - Groups related API operations into reusable interfaces for modular API design.
• Scalar Value Generation - Defines factory methods on scalars that produce typed values from other inputs for emitter interpretation.
• Literal Value Definitions - Creates literal values for primitive types that can also function as literal type definitions.
• Scalar Constructors - Defines factory methods on scalar types that produce typed values from other inputs for emitter interpretation.
• Scalar Type Constructors - Defines primitive types with factory methods and encoding rules for dates, durations, and other scalars.
• Date and Time Libraries - Models calendar dates, clock times, UTC timestamps, offset-aware datetimes, and durations without prescribing serialization.
• Versioned - Records element renames across API versions, preserving old names for earlier versions.
• Custom Enum Value Assignments - Assigns custom string, integer, or float values to enum members using colon syntax.
• Enum Spread Composition - Combines enum members from one enum into another using the spread operator.
• Model Property Visibility Filters - Filters model properties based on custom visibility rules with all, any, or none constraints.
• Stream Protocol Models - Defines stream protocol models as a first-class concept in the API definition language.
• Versioned Property Requirement Tracking - Records the API version when an optional property became required.
• Versioned Property Optionality Changes - Records the API version when a required property changed to optional.
• Variant - Uses union variant references in value context to produce the variant's literal value.
• Versioned Property Optionality Tracking - Records the API version when a required property became optional.
• Paginated API Operations - Marks an operation with a decorator to return a collection split into pages, with page items annotated on the response property.
• Vendor Extensions - Attaches arbitrary key-value metadata to models, operations, or schema objects for vendor-specific use.
• Security Definition Generations - Generates security scheme definitions and operation-level security requirements in OpenAPI output.
• Versioned - Records property renames across API versions, preserving old names for earlier versions.
• Double-Quoted String Literals - Declares precise string constants using double quotes for use in API models, decorators, or type aliases.
• Multi-Line - Writes string literals spanning multiple lines using triple quotes, preserving whitespace and line breaks.
• Textual File Declarations - Provides a mechanism for declaring textual file types in API definitions for file transfer operations.
• Versioned Return Type Changes - Records return type changes across API versions, preserving old types for earlier versions.
• Versioned Library Dependency Declarations - Declares library version dependencies on namespaces or version enums using decorators.
• Versioned Package Dependency Declarations - Declares which version of a library a service depends on using decorators on namespaces or version enums.
• Shared Route Paths - TypeSpec marks an operation to share its route path with other operations.
• Response Streaming - Provides a model for describing how streamed data is encoded over the wire in HTTP responses.
• HTTP Cookie Parameter Configuration - Marks a property to be sent or received as an HTTP cookie.
• Predefined Response Shapes - Ships built-in response shapes for common HTTP status codes and body patterns.
• Declarative File Transfer Models - Models file uploads and downloads declaratively using types that extend Http.File.
• HTTP Link Headers - Ships a model for adding Link headers to HTTP responses, enabling related resource URL discovery.
• HTTP Location Headers - Provides a model for adding Location headers to HTTP responses, enabling long-running operation tracking.
• HTTP Status Code Models - Ships predefined models for standard HTTP status codes, including 301 Moved Permanently responses.
• Paginated Collection Models - Defines model structures for paginated API responses with value lists and next-link URLs.
• Custom Visibility Classes - Creates custom visibility enums with modifiers for API model lifecycle transformations.
• Boolean Literal Constants - Sets literal true or false values for flags or conditional model properties.
• Named Constant Declarations - Declares named constants with optional type annotations and type inference from initializers.
• Named Template Arguments - Supports passing template arguments by name for out-of-order and optional argument omission.
• Structural Type Spread and Inheritance - Combines model properties through spread, extends, and intersection operators for property reuse.
• Named Union Variants - Assigns explicit names to union type variants for emitter identification and decoration.
• Model Property References - Accesses specific model properties using dot notation to create aliases for reuse.
• Array Value Definitions - TypeSpec constructs an ordered list of values using the array syntax, with optional validation against min and max item constraints.
• String Interpolation - Embeds expressions inside string literals with ${} syntax to compose dynamic string values at definition time.
• Literal Type Definitions - Represents fixed values directly in code using string, integer, float, or boolean literal syntax.
• Type Aliases - Creates a shorthand name for a complex type expression, simplifying syntax without affecting the type graph.
• Basic Authentication - Declares HTTP Basic authentication requirements for API endpoints in the service definition.
• Authentication Scheme Compositions - Combines multiple authentication methods at service or operation level with logical operators.
• Bearer Token Authentication - Restricts access to API operations by requiring a valid bearer token in the Authorization header.
• File Type Validators - Constrains allowed media types of file payloads using a literal union of MIME types.
• API Key Authentications - Specifies that API endpoints require an API key passed via header, query, or cookie.
• OAuth2 Providers - Specifies OAuth2 authorization flows required for accessing API operations.
• OAuth2 Scope Requirements - Requires specific OAuth2 scopes on tokens for accessing API operations.
• OpenID Connect Support - Declares OpenID Connect authentication requirements using a discovery URL for API endpoints.
• Type-of Operators - Uses the typeof operator to obtain the declared or inferred type of a value reference.
• Resource Action Definitions - Marks operations as custom actions scoped to resource instances or collections with configurable route separators.
• ISO 8601 Parsers - Creates date, time, or duration scalar values by parsing standard ISO 8601 strings.
• Model Duplication - Creates exact copies of models including all attached decorators without nominal inheritance.
• API Error Documentation - Associates specific error models with each API operation so generated documentation and clients know which errors to expect.
• Lifecycle Phase Model Transformations - Generates derived models filtered by lifecycle phase for create, read, update, and delete operations.
• Authentication Overrides - Applies different authentication schemes to specific operations, overriding parent defaults.
• OpenAPI Extension Attachments - Attaches arbitrary key-value data to the generated OpenAPI element for a type, enabling vendor-specific extensions.
• Auto Decorators - TypeSpec creates decorators that attach metadata without custom logic, requiring no JavaScript implementation.
• Remote Decorator Applications - TypeSpec attaches a decorator to a type from a different location by referencing the target type with an @@ prefix statement.
• OpenAPI Tag Metadata - Provides additional OpenAPI info metadata for the service, complementing the title set by the service decorator.
• Enum Composition - Creates new enums by merging all members from another enum into the current definition.
• Enum Member References - Accesses enum members using dot notation for use in API models and decorators.
• Numeric Precision Serialization - Serializes int64, decimal128, and other large numeric types as JSON strings to avoid precision loss.
• Inline Object Literals - Constructs structured values with named properties using inline object literal syntax.
• Numeric Literal Constants - Specifies exact integer or decimal number literals for status codes, limits, or other numeric constraints.
• Reusable Response Components - References models and parameters by name to generate reusable schemas and parameters in the output.
• URI Template Expanders - Sets the relative URI template for an operation following RFC 6570.
• Array Element - Declares arrays where every element must be of the same specified type using shorthand syntax.
• Value Constraint Templates - TypeSpec declares template parameters that accept literal values using the valueof constraint for use in decorators and defaults.
• Content Type Specifications - Sets the content type for an operation by including a header parameter named contentType.
• Linting Rules - Creates reusable patterns and linting rules that guide API designers toward best practices and flag anti-patterns.
• HTTP Header Manipulators - Decorates a property with a header name so its value is sent or received in the HTTP header section.
• Collection Parameter Models - Defines models for parameters used in resource collection operations.
• Dynamic Response Statuses - Sets HTTP status codes on return types, defaulting to 200 or 204, and supports unions for multiple responses.
• Encoded Name Resolvers - Resolves per-MIME-type property name overrides, falling back to the original name.
• Multipart Request Definitions - Provides a model for defining multipart request bodies in API definitions, supporting file uploads and complex form submissions.
• HTTP Status Code Models - TypeSpec provides a model for a 409 Conflict HTTP response.
• Nested Body Property Models - Resolves the HTTP body from a nested property to co-locate metadata and payload.
• Nested Discriminator Chains - Applies multiple levels of discriminator properties to identify subtypes in a hierarchy.
• OpenAPI Operation ID Overrides - Sets custom operationId values on API operations, overriding default generated names.
• Operation Meta Type References - Provides syntax to access operation parameters and return types for further manipulation.
• Per-Format Property Renaming - Assigns alternative property names per MIME type for different wire representations.
• Query Parameter Binding - Marks a property to be sent as a query parameter in the URL.
• Default Content Type Selectors - Automatically selects content types for request and response bodies based on the body's type.
• JSON Merge-Patch Bodies - Provides a model template for generating RFC 7396 JSON Merge-Patch request bodies for partial resource updates.
• Request Body Definitions - Specifies the request body content and media type using a body parameter and content-type header.
• Structured Body Binding - Marks a property as the exact HTTP body, separating it from headers, query, and path parameters.
• Resource Creation Request Models - Defines models for the request body of resource creation or update operations.
• Resource Creation Response Models - Defines models for the response of successful resource creation operations.
• Created Resource Response Models - TypeSpec provides a model for a 201 Created HTTP response.
• Resource Deletion Response Models - Defines models for the response of successful resource deletion operations.
• Resource Hierarchy Models - Declares resource hierarchy models that nest child routes under parent paths.
• Resource Location Scalars - Defines a scalar type for representing resource URLs in API definitions.
• Resource Operation Parameter Models - Defines models for the parameters of individual resource operations.
• Response Structure Standardization - Defines structured response shapes that incorporate standard HTTP status codes and headers for consistent API outputs.
• Response Model Assignments - Assigns a custom response model to an API operation so the endpoint returns a predictable, reusable structure.
• String Format Validators - Restricts string values to known formats like URLs for consistent validation and code generation.

Star history