add pixi schema CLI

[bollwyvl]

As always, thanks for pixi!

elevator pitch

Add some pixi CLI features to emit JSON schema for key pixi files and other features.

references

• JSON schema for pyproject.toml [tool.pixi] #1089
• Verify pixi schema against CLI #2057
• Autogenerated manifest docs #3021
• Investigate JSON Schema for pixi build backends #3938
• Add pixi tree --json #4130
• feat(global): add --dry-run & --json to global update #4262
• feat(cli): add new pixi global tree command #4427

motivation

As the number of pixi features which provide --json output expands, it may
make sense for a user's installed pixi to be able to tell them exactly,
conclusively, what kind of JSON to expect.

This would make it far easier for external tools to predictably integrate with
pixi, and, crucially, detect when big changes happen.

design ideas

Some potential CLI experiences (not mutually exclusive):

• a top-level pixi schema subcommand:

  $ pixi schema
  
  No schema key given, please provide one of:
  
  Key         Describes
  lock        a pixi.lock file
  manifest    a pixi.toml file
  pyproject   a pyproject.toml file
  schema      output of `pixi schema --json`
  task-list   output of `pixi task list --json`
  tree        output of `pixi tree --json` 
  # ...

• a --schema, a neighbor to --json:

  pixi list --json --schema
  pixi task list --json --schema
  # ...

The generated schemata should have most of the properties of the existing, hand-made
manifest schema for downstreams over time:

• provide $schema (probably stick with draft7)
• provide $id which would resolve to a versioned URL on the docs site
• be sensibly sorted and indented between versions
• be self-contained and not references other URLs

A key enabler, mentioned in a few places, is schemars, already in Cargo.lock as a dependency of uv.

[baszalmstra]

The schema is already available through github through:

https://raw.githubusercontent.com/prefix-dev/pixi/v0.52.0/schema/schema.json

Does that help?

[bollwyvl]

That... kind of helps, but falls down for:

• as a user, I'm on a train and not connected to the internet, but would like completion in my IDE
• as a tool developer, I'd like to validate something that integrates with one of the pixi * --json outputs

The first case can be worked around by grabbing said file prior to getting on a train. Indeed, on some projects, we've gone further and taken the upstream schema and amended it to be more restrictive.

For the second, there is no schema at all, therefore no way to tell when pixi 0.x.y+1 changes its --json output format short of reading the source code. One can work around it with something like genson and a bunch of possible outputs, but this is a pretty underwhelming experience.

[baszalmstra]

We could just include the schema in pixi when we build it and expose a CLI command to print it. Would that suffice?

[bollwyvl]

the schema

The point is The Schema is not just "the schema for one variant of the manifest file," but the contract of things that non-rust packages can hope to get from pixi [whatever] --json. As a thought exercise: if pixi was a REST API, what would be the OpenAPI contract be?

Adding and then including hand-built schema for each of these would put an extra step in front of the rust build, but then wouldn't really have any guarantee that what rust says its doing would match what it does, as per #4324.

Alternatives would include:

• declaring JSON-compatible input (e.g. pixi.toml, pyproject.toml) and output (e.g. pixi task list --json) in the rust code with schemars
• continuing to maintain multiple hand-made schemata, including these in the binary, then generating rust types with e.g. typify

[bollwyvl]

Another rust vs schema PR: #4445