How-to guides
How-to guides assume that the goal is settled and the missing piece is a procedure. A first encounter with panproto belongs in the tutorials; an exact flag, signature, or grammar belongs in the reference.
First working path
A reader starting from an existing schema file can follow one short sequence: install a surface, define or load a schema, construct a migration with the migration guide, and convert data. Each guide includes a verification step before the next operation changes data or repository state.
Intermediate entry points
These guides assume that you can already load and validate a schema.
| Goal | Start here | Continue with |
|---|---|---|
| Control an inferred span | Find a span between two schemas | Apply field transforms |
| Run a lens in both directions | Use lenses | Write lenses in the lens DSL |
| Inspect or select records | Query instances | Expression-language reference |
| Preserve source formatting | Round-trip with format preservation | Decorate an abstract schema |
| Put schema changes under version control | Initialize and commit | Branch and merge |
| Reject incompatible changes automatically | Create a breaking-change gate | Run it in GitHub Actions |
Advanced entry points
These guides cover reusable transformations, language tooling, and protocol extension.
| Goal | Start here | Related contract |
|---|---|---|
| Reuse one lens across a family of schemas | Use protolenses | Lens combinators |
| Select an optic from schema structure | Use dependent optics | Lens combinators |
| Parse and migrate syntax trees | Parse full ASTs | Rust SDK |
| Translate between schema languages | Translate across protocols | Protocol catalog |
| Add a schema language | Build a custom protocol | Crate map |
| Version data with its schema | Version data alongside schemas | CLI reference |
Tasks by area
Setup and schema creation are collected under Install panproto and Define a schema. Migration work begins with Build a migration and extends through field transforms, lenses, protolenses, dependent optics, and the lens DSL.
Data tasks cover conversion, queries, format-preserving round trips, full-AST parsing, and schema decoration. Repository tasks are grouped under Schema version control and Continuous integration; Translate across protocols and Build a custom protocol cover extension across protocol boundaries.