Scalar Mock Server release notes
Schema-aware XML generation and AsyncAPI security hardening
Mock server XML responses now preserve attributes, namespaces, and proper element structure from OpenAPI schemas. AsyncAPI reference resolution is now restricted to safe locations.
- XML mock responses now serialize using schema metadata instead of json2xml, preserving attributes, namespaces, and root element names from your OpenAPI document.
- Mock server returns X-Scalar-XML-Error header when XML generation fails, helping you debug schema issues.
- AsyncAPI external references are now restricted to the source directory and public network addresses for improved security.
- Existing XML response snapshots may need updating to match the new schema-aware output format.
OpenAPI 3.2 querystring parameters and custom HTTP methods
This release adds support for OpenAPI 3.2 features including whole-query parameters and document-defined HTTP methods like PURGE or NOTIFY.
- Querystring parameters can now be validated and handled in custom request handlers, with full support for JSON, text, and form content from the entire query string.
- Custom HTTP methods defined in additionalOperations are now supported with case-sensitive routing and CORS preflight responses.
- The mock server preserves custom method capitalization when routing requests to your handlers.
- Boolean false schemas are now correctly preserved in validation, rejecting every value as specified in your OpenAPI document.
OpenAPI 3.2 streaming, OAuth device authorization, and WebSocket v2
This release adds OpenAPI 3.2 support across the mock server, including streaming responses with itemSchema and OAuth device authorization flows. WebSocket handling has been upgraded to Hono Node server v2.
- Generate finite SSE, JSON Lines, NDJSON, and JSON Sequence mock responses from OpenAPI 3.2 itemSchema definitions.
- Support OAuth device authorization flows with verification codes, token polling, and mock approval endpoints.
- Generate the correct primitive and array branches for anyOf and oneOf schemas, preserving the selected shape in mock HTTP responses.
- Upgrade to Hono Node server v2 for WebSocket support. AsyncAPI callers must pass websocket to serve() instead of calling injectWebSocket().
- Preserve semantics when upgrading to OpenAPI 3.2, with compatibility diagnostics for descriptions requiring author decisions.
Polish and bug fixes shipped
OAuth2 metadata discovery for local development
The mock server now serves OAuth2 authorization server metadata at the configured URL, advertising local mock endpoints and the grants and scopes you have defined.
- Serve OAuth2 metadata at the declared oauth2MetadataUrl with local mock endpoints and configured grants and scopes.
- Normalize absolute OAuth token URLs to route paths when registering mock authentication routes.
- Warn when OAuth2 metadata routes collide with declared API paths to help catch configuration issues early.
Mock server now serves deprecated response schemas and supports HTTP QUERY
The mock server no longer returns empty bodies for deprecated response schemas. It now correctly generates values for deprecated fields and message payloads, matching real API behavior. HTTP QUERY requests are now allowed in CORS preflight responses.
- Deprecated response schemas are now served with generated content instead of empty bodies.
- AsyncAPI deprecated message payloads generate realistic data instead of sending null.
- Response headers that generate no value are skipped rather than being deleted.
- HTTP QUERY method is now supported in default CORS preflight responses.
Custom handler and seed code now runs in a secure sandbox
This release hardens the mock server against security risks. Custom handler and seed code is now isolated in a WebAssembly sandbox, and OpenAPI references are protected from server-side request forgery and unauthorized file access.
- Custom x-handler and x-seed code now runs in a QuickJS WebAssembly sandbox with memory and time limits, preventing access to the Node.js host.
- OpenAPI $ref resolution is now hardened to block private networks, loopback addresses, and metadata endpoints.
- Local file references are confined to the document's own directory, preventing unauthorized file reads.
- The store, faker, req, res, schema, and seed APIs continue to work as before in the sandbox.
- Faker methods that take callbacks (like faker.helpers.multiple) are no longer supported due to sandbox boundaries.
Server-Sent Events support and improved error diagnostics
The mock server now streams text/event-stream responses as real Server-Sent Events, returns structured JSON errors that name the failed operation, and validates recursive schemas correctly.
- Server-Sent Events responses are now streamed with proper data: line framing instead of buffered as a single JSON body.
- Named examples in SSE responses are sent as a sequence of events in declaration order.
- Unhandled errors return structured JSON with the operation method, path, and operationId instead of plain-text 500 responses.
- Request validation now works for recursive schemas instead of silently falling open.
- Path keys with query strings or special routing characters are properly escaped and matched against incoming requests.
Package republished with npm trusted publishing
Updated README with refreshed Scalar platform overview
Fixed npm package README display
This release fixes a metadata collision that caused the package README to display incorrectly on the npm registry. The mock server now publishes with the updated README that includes the Scalar platform overview.
Mock AsyncAPI documents and validate all parameter styles
The mock server can now generate event-driven APIs from AsyncAPI 3.1 documents, serving channels over WebSocket and Server-Sent Events. Request validation has been extended to cover header and cookie parameters, and all OpenAPI serialization styles are now deserialized before validation.
- AsyncAPI 3.1 documents are mocked through a new createAsyncApiMockServer function that serves channels over WebSocket and SSE.
- Messages are generated from payload schemas using the same generator as REST endpoints, and custom transports can be added through an extension point.
- The Docker mock server auto-detects AsyncAPI documents and starts the event-driven engine automatically.
- Header and cookie parameters are validated against their schemas, with case-insensitive header matching and spec-compliant filtering of Accept, Content-Type, and Authorization.
- Array and object parameters are deserialized by their OpenAPI style (form, simple, deepObject, label, matrix, and delimiter styles) before validation, so complex query strings and path segments validate correctly.
Smarter response selection and format fixes
This release improves how the mock server chooses which response to return when your API defines multiple status codes, and fixes edge cases with line-delimited JSON formats and array responses.
- The mock server now prefers 2xx success responses over error codes when no specific status is requested, making default mocks more realistic
- JSONL and NDJSON responses are now correctly formatted as single-line records instead of pretty-printed JSON
- Singular examples are automatically wrapped in arrays when the response schema expects an array
Request validation and improved authentication
The mock server now validates incoming requests against your OpenAPI schema by default, returning detailed contract violations instead of mock responses when parameters or bodies do not match. Authentication evaluation has been corrected to follow the OpenAPI specification.
- Request validation is now on by default—path, query parameters, and JSON bodies are checked against the schema, returning 422 with violation details when they do not match
- Use the Prefer header to control mock responses: code=404 picks a specific status, example=bob selects a named example from the examples map
- Authentication now evaluates security requirements as OR-of-ANDs, inherits document-level security when operations define none, and validates credential shape for Basic and Bearer tokens
- Set validateRequest: false to restore previous behavior and always return mock responses
Improved OpenAPI reference resolution performance
The mock server now resolves OpenAPI $ref nodes on demand instead of processing the entire document upfront, improving startup time and memory usage for large specifications.
- References are now resolved lazily only when needed for generating responses
- Nested references (like a Planet referencing a User) now resolve correctly in examples
- Broken references are handled gracefully without failing document processing
OAuth refresh endpoints in mock authentication routes
Mock Server now generates authentication routes for OAuth refreshUrl endpoints defined in your OpenAPI security schemes.
Random data generation for mock responses
Mock Server can now generate random but schema-aware data for responses, making local testing feel closer to real API behavior.
