v0.2.1

---

Important

clap_schema is deprecated in favor of Argx (crates.io). This repository is archived.

Argx includes schema discovery as part of a broader derive-first command-line parsing and configuration framework. clap_schema will no longer receive new features, bug fixes, or security fixes. New projects should use Argx instead.

---

Full Changelog: v0.2.0...v0.2.1

v0.2.0

clap_schema 0.2.0 is a breaking redesign of its machine-readable CLI contract.

The 0.1 model exposed useful Clap metadata, but still mixed parser representation, rendered-help concepts, and machine-facing invocation semantics. 0.2 defines the contract around a more concrete goal: given structured data, provide enough information to construct a canonical CLI invocation while keeping Clap authoritative for parsing and validation.

Canonical invocation contracts

Command documents now expose the semantics needed to construct valid invocations, including:

• canonical command paths and ancestor invocation context;
• positional arguments and options;
• value arity, lexical defaults, possible values, and repeatability;
• conflicts, overrides, conditional requirements, and conditional defaults;
• argument groups;
• token-placement and parsing requirements;
• command and subcommand routing semantics.

Nested commands retain the relevant context of their ancestors, so selecting a leaf command still provides the parent-level constraints required to construct the complete invocation.

Keep Clap authoritative

CLI inputs are now represented as lexical values rather than inferred Rust scalar types.

clap_schema no longer attempts to infer simplified types such as strings, integers, numbers, or booleans from Clap's erased value parsers. The contract describes how values are supplied; the configured Clap parser remains responsible for interpreting and validating them.

The same principle applies throughout the contract: clap_schema reflects semantics exposed by Clap rather than attempting to reconstruct parser behavior through synthetic parsing or heuristics.

Parser semantics, not help presentation

Machine discovery is now independent of Clap's presentation settings.

Hidden commands, arguments, defaults, and possible values remain part of the contract when Clap still accepts them. Generated help and version actions remain excluded because they are parser control surface rather than application inputs.

Aliases may still be accepted by Clap, but the contract exposes canonical command paths rather than alternate alias paths.

New wire format

0.2 introduces a breaking wire-format revision.

Notable changes include:

• executable is replaced by invocable;
• rendered usage is removed;
• clap_schema-owned JSON properties use lower camel case;
• command, argument, relationship, group, and syntax structures more directly represent invocation semantics;
• successful handler results continue to be represented using JSON Schema.

invocable is now a meaningful guarantee: a command path marked invocable can terminate as a valid invocation rather than requiring another subcommand.

Application-defined extensions

Applications can attach their own typed metadata schemas at the CLI or command level without clap_schema defining the meaning of that metadata.

Application-wide and command-specific schemas compose through JSON Schema allOf, while concrete extension values remain application-owned.

This keeps the core contract focused on CLI invocation semantics while allowing applications to layer their own machine-facing vocabulary on top.

Derive and builder parity

Both derive-based and builder-style Clap applications produce the same contract model.

Derived discovery follows nested and flattened Clap command structures automatically. Builder users explicitly associate canonical command paths with typed handlers and can attach application metadata where needed.

Conformance

0.2 substantially expands the semantic conformance suite around the Clap behavior the contract depends on.

Coverage now includes command topology, arguments and values, relationships, groups, hierarchy and global arguments, routing semantics, canonical paths, token syntax, discovery depth, wire vocabulary, parser boundaries, and derive/builder parity.

Where contract fields describe invocation validity, Clap itself is used as the behavioral reference.

Upgrading from 0.1

This is intentionally a breaking release. Consumers of the serialized contract should treat the 0.2 schema as a new version rather than expecting 0.1 documents to deserialize unchanged.

The result is a smaller conceptual boundary: clap_schema describes how to invoke the CLI and what typed result to expect; Clap remains responsible for parsing the invocation.

---

Full Changelog: v0.1.0...v0.2.0

v0.1.0

clap_schema 0.1.0

Initial public release of clap_schema.

clap_schema turns Clap commands and typed Rust results into machine-readable contracts. It provides command discovery, argument metadata, and JSON Schemas for handler output types, with command registration and output types checked at compile time.

Installation

Add the crate:

cargo add clap_schema

clap_schema requires Rust 1.95+.

Notes

This is the first public release, so there is no upgrade procedure from an earlier version.

Clap remains the source of truth for command inputs, while typed Rust results define output schemas. clap_schema connects the two without introducing a parallel command or type system.

The crate is dual licensed under Apache-2.0 OR MIT.

---

Full Changelog: https://github.com/selemis-com/clap_schema/commits/v0.1.0