Basketry Roadmap

0.2.0 – July 2025 (in progress)​

Theme: Basketry on Basketry​

We’re redefining the Intermediate Representation (IR) by expressing it in JSON Schema. This formalizes the IR as a machine-readable contract, enabling consistent tooling across languages and environments. With this schema-first approach, we can now use Basketry itself to generate TypeScript definitions, documentation, and language-agnostic representations from the IR spec. (Dogfooding FTW! 🎉)

This work lays the foundation for a truly polyglot Basketry ecosystem. Today, Basketry can generate code in any language, but all generators must be implemented as TypeScript modules. By formally defining the IR in JSON Schema, we move toward a future where generators, rules, and other components can be built in any language, without relying on TypeScript or Node.js. This opens the door to broader community contributions, especially from developers who specialize in ecosystems like Python, Go, or Rust, and removes a key barrier to adoption and collaboration outside the TypeScript world.

Key Features​

• Redesigned Intermediate Representation (IR): The IR is defined using JSON Schema, providing a precise, versionable contract for all Basketry tooling.

• IR Structural Changes: Major refactors to the IR structure, including removal of sourcePath, replacement of the generic Scalar type, and addition of new IR features like nullable and map properties.

• Formal IR Specification Generation: The IR schema and its accompanying documentation are auto-generated for use by plugin developers and external tools.

• Plugin and Generator Upgrades: All core generators, validators, rules, and utilities have been updated to consume the new IR format. The generator interface has also been updated to support asynchronous (promise-based) behavior.

• Multi-source Input Support: Basketry components can parse and merge multiple SDL/IDL documents in a single codegen run.

• Improved Parser Metadata: Interface descriptions can be extracted from OpenAPI tags, enhancing generated documentation.

• CLI Improvements: New --version command, renamed --validate to --dry-run.

0.3.0 – September 2025 (planned)​

Theme: Plugins via stdio​

Currently, Basketry loads plugins (generators, rules, etc.) by requiring them as Node.js modules. While this works well for Node-based workflows, it creates a major blocker for developers working in other ecosystems. Non-Node environments, such as Go, Python, or Rust, shouldn't need to install Node.js and manage npm packages just to use or build Basketry components.

To address this, we're introducing stdio-based component execution, allowing plugins to be run as standalone executables that communicate via standard input and output. Basketry core will attempt to invoke plugins via stdio, and fall back to Node module loading for backwards compatibility. All standard plugins will be updated to support the new protocol. Node module loading will be deprecated and removed entirely in a future release (tentatively v1.0.0).

This milestone is a major step toward making Basketry truly language-agnostic — not just in what it generates, but in what it's built with.

Key Features​

• stdio-based plugin execution: Generators, rules, and other plugins can be implemented as standalone executables that communicate via stdin/stdout, decoupling them from the Node.js runtime.

• Plugin fallback logic: Basketry will attempt to invoke plugins via stdio, and fall back to legacy Node module loading if needed (with deprecation warnings).

• Standard plugin updates: All first-party plugins (e.g., TypeScript generators, OpenAPI parser, rules) will be updated to support stdio interop.

• Component protocol specification: The communication protocol for stdio components will be formally defined and versioned to ensure forward compatibility and tooling support.

1.0.0 – 2026 (planned)​

Theme: Port Core to Rust​

Basketry graduates to stable 1.0 by moving its core from TypeScript to Rust and distributing pre-compiled binaries for all major platforms. This change eliminates Node.js as a runtime dependency, delivers significant performance and memory-footprint gains, and makes installation friction-free for every ecosystem.

Each language community will install Basketry the way they expect, npm, pip, gem, nuget, Homebrew, Chocolatey, direct tarballs, etc.—all of which wrap the same signed Rust binary. TypeScript-specific conveniences (helpers, typings, ESLint rules, etc.) will live in a separate @basketry/helpers package, keeping the core lean and language-agnostic. Similar helpers can be built for other languages and distributed as needed.

With binaries in place, we can finish deprecating the legacy Node-module plugin pathway introduced in 0.x and rely solely on the stdio component protocol. Parsers and rulesets (e.g., OpenAPI v3) are inherently language-agnostic and will be ported to Rust for portability and performance; generators remain free to be authored in their target languages.

Key Features​

• Rust-based Core CLI: The Basketry core is rewritten in Rust to enable a single, portable binary that runs consistently across all major platforms—no Node.js or runtime setup required.

• Native Binary Distribution: Basketry will be available through ecosystem-native channels like Homebrew, Chocolatey, apt, and as language-specific wrappers (e.g., npm, pip, gem, nuget), making installation seamless for every kind of developer.

• Typed Helper Packages Extracted: TypeScript-specific functionality will be moved into a separate @basketry/helpers package, allowing the core CLI to remain language-neutral while still supporting strong ergonomics where needed.

• Parsers & Rules Ported to Rust: Core components like OpenAPI and JSON Schema parsers, along with common rule engines, will be implemented in Rust to ensure they're accessible and consistent regardless of the developer’s language environment.

• Unified Plugin Execution via stdio: All plugins will use the cross-language stdio protocol, removing the final dependency on Node.js and ensuring that any plugin, written in any language, can integrate cleanly into the Basketry pipeline.

• Ecosystem-Native Installability: Developers can install and use Basketry with the tools they already know, whether that’s npm install basketry, pip install basketry, or downloading a platform-specific binary—no extra runtimes or bootstrapping required.

• Stable, Language-Agnostic Interfaces: The IR schema and stdio protocol will be versioned and stable throughout the 1.x lifecycle, enabling reliable integration with tools, plugins, and pipelines across language boundaries.

Beyond 1.0​

With the 1.0 release, Basketry will deliver a stable, portable, and language-agnostic foundation for code generation pipelines. The core will be ready for wide adoption across diverse development environments—but the real opportunity lies in what comes next.

🌟 Core Principles​

Basketry will always be a locally installable, open-source toolchain—built for CI, offline development, and long-term stability. Whether you’re running it on your laptop or inside a build pipeline, Basketry is designed to work without requiring a hosted service, API token, or vendor login. The entire ecosystem is packaged and versioned in a way that puts ownership in the hands of the end user. No phone-home behavior, no hidden dependencies, and no cloud lock-in.

Because Basketry is distributed as installable binaries and packages—licensed under MIT—you can rely on it indefinitely. You’ll always be able to install, fork, pin, or run a specific version of the CLI and its plugins, even if the project changes direction in the future. While breaking changes will happen as the ecosystem evolves, everything is semantically versioned and intentionally pluggable, so teams can adopt updates on their own schedule.

Commitments​

• Open & Forkable: Published under the MIT license, with no proprietary core. The community can always fork, extend, or self-publish without restriction.

• Installable & Offline-Capable: Distributed as binaries and language-specific packages (npm, pip, etc.) that run locally or in CI—no internet connection or central service required.

• No Lock-In: No mandatory accounts, SaaS dependencies, or hosted-only features. The CLI and plugin system are designed for full autonomy and portability.

• Composable by Design: Every plugin follows a documented, language-agnostic interface (stdio) and is versioned independently to support selective upgrades and ecosystem stability.

• Transparent Change Process: Breaking changes are intentional, versioned, and documented. You’re never forced to upgrade until you're ready.

🚀 Optional Cloud Experiences​

While the core stays local, some workflows thrive in the cloud. We’re doing discovery for an optional Basketry Studio: a hosted environment for designing, linting, and generating APIs with collaborative editing and AI-assisted authoring (think Basketry Copilot). Studio would likely include paid add-ons, but would never be a requirement, and would always export the exact same artifacts the CLI produces locally.

🧩 Ecosystem & Integrations​

IDE Extensions – Expanding beyond the existing VS Code plug-in to editors such as Neovim, Eclipse, JetBrains, and more, so every developer gets in-editor validation and code-gen.

Plugin Registry – A public catalog where maintainers can publish generators, parsers, and rules, discoverable via metadata and semantic version ranges.

Composable Engine for Niche Tools – Basketry aims to be the stable, language-agnostic engine that specialty API-automation products can embed. By offloading SDL parsing and cross-language code-gen to Basketry, small teams can focus on their unique value while reaching a broader set of service-definition languages—without giving up control of their own roadmaps.

🔭 Expanding Technical Scope​

Basketry’s roots are in REST. Future milestones will extend first-class support to event-driven architectures, xRPC/Connect-style contracts, and eventual-consistency patterns—all expressed through the same IR and plugin ecosystem.