TOML schema proposal aims to bring Cargo.toml structure to editors

Editor tooling is the immediate win

If Cargo.toml could describe its own shape in a machine-readable way, the first people to feel it would be the ones editing manifests every day. Editors could suggest the right fields, warn when a section is out of place, and flag broken dependency entries before Cargo ever runs. That is the practical promise behind the TOML Schema proposal: not a new parser, but a clearer contract between Rust manifests and the tools that read them.

Cargo.toml is already the center of Rust project setup, and Cargo treats it as the package manifest written in TOML with the metadata needed to compile the package. The proposal takes that reality seriously. Rather than reimagining how Rust packages work, it asks a simpler question: what if tools could understand the structure of Cargo.toml as well as Cargo does?

What the proposal is trying to define

The core idea in toml-schema is straightforward, even if the implications are broad. It defines a TOML-native schema language, and the schema document itself is valid TOML. In the Cargo example, the author models manifest structure in a dedicated Cargo.tosd schema, using the same language that Rust developers already use for configuration.

That schema is aimed at the structural layer only. It describes which fields can appear, which ones are optional, and how value shapes should be represented, including unions such as a dependency written as a plain string or as an inline table. That distinction matters because Cargo has real semantic rules that a schema cannot fully replace, but editors do not need full package resolution to know that serde = "1" and regex = { version = "1", features = ["perf"] } are both valid shapes.

The proposal’s scope is deliberately practical. It is trying to make manifests easier for tooling to inspect, not to rewrite Cargo’s behavior or override Cargo’s parser. That makes the project less like a standards crusade and more like a tooling layer for everyday Rust work.

Why Cargo.toml is such a strong test case

Cargo’s own documentation makes the case for schema support by showing how much structure lives inside one manifest. The book lists sections such as [package], target tables like [lib] and [[bin]], dependency sections, features, profiles, patching, workspaces, metadata, and lints. In other words, Cargo.toml is not a flat bag of keys. It is a document with section-specific rules, nested tables, and values that change meaning depending on context.

Workspaces make that even more interesting. Cargo says a workspace is a collection of one or more packages, all sharing a common Cargo.lock file at the workspace root. It also says [patch], [replace], and [profile.*] are only recognized in the root manifest and ignored in member crates. That kind of context-sensitive behavior is exactly where editors tend to get fuzzy today, and exactly where a schema could provide a sharper signal.

Virtual workspaces add one more wrinkle: Cargo requires an explicit resolver setting there. That is a small detail, but it shows why manifest tooling benefits from more than syntax highlighting. A schema that knows the structure of workspace manifests could help catch the cases where a field is legal in one place and meaningless in another.

Cargo already has schema-like knowledge inside it

This proposal is not arriving in a vacuum. Cargo’s nightly documentation for cargo_util_schemas::manifest describes a manifest schema definition type that is used to deserialize Cargo.toml files. That means Cargo itself already carries structured knowledge about manifests, even if that knowledge is not exposed as a general-purpose schema for external tools.

Cargo’s nightly linting also points in the same direction. The manifest-related lints include non_kebab_case_features, redundant_homepage, redundant_readme, unused_dependencies, and unused_workspace_package_fields. Those checks show that the ecosystem already values machine-detectable manifest quality. A TOML schema layer would not replace that logic, but it could move some of the friction earlier, into editors and CI, where mistakes are cheaper to fix.

That is the real tooling story here: not one more validation system, but a shared structural map that other tools can use. Documentation generators could reflect actual manifest shapes, CI could validate configs before a developer runs Cargo, and package maintainers could spot bad structure without waiting for a full command to fail.

The broader TOML angle and the Rust community signal

The proposal also sits inside a larger TOML conversation. TOML itself, introduced by Tom Preston-Werner, was designed to be minimal, human-readable, and easy to parse across languages. TOML Schema builds on that same spirit by defining a TOML-based schema language for describing and validating the structure, names, and value types of TOML configuration files. In that sense, toml-schema is not trying to replace TOML’s simplicity. It is trying to add a machine-readable layer on top of it.

The public discussion around the project has been exploratory rather than final. The author says the project started in 2020 and notes reference implementations in Rust, Go, and Java, generated with agents in the last few days. That detail is striking because it shows how quickly AI-assisted code generation is moving from application code into infrastructure and tooling foundations.

There is also a wider Rust community appetite for this kind of manifest intelligence. A separate forum idea proposed a schema for documenting Cargo feature flags so IDEs and documentation tools could surface feature information while a crate’s Cargo.toml is open. Taken together, those efforts point to a clear pattern: Rust developers want manifests to be understood, not just parsed.

The unanswered question is not whether Cargo.toml has enough structure to justify schema support. Cargo’s own docs and its nightly internals already say it does. The question is whether the ecosystem wants to turn that structure into a shared tooling contract, so the next broken manifest is caught by the editor instead of by a failed command.