Generate and validate IPLD Schemas and the data they describe
ipld-schema can be used both as a command-line application and a Rust library.
The project is under active development and interfaces may change. Details are tracked in the changelog for each semver release.
For pre-1.0.0 releases any known breakage in the determinism of schema/data generation will incur a minor version bump. After the 1.0.0 release such breakage will incur major bumps. Version and seed information is included as comment headers in generated outputs.
IPLD's specification is continually evolving. To cope with this, at least during this early stage of development, an revision is pinned using a gitsubmodule at ./specs. In cases where the latest revision of the upstream repository and the pinned version are inconsistent this repository will generally prefer what's specified in the pinned version. As the project matures the pinned specification version may be bumped.
The public Rust API may not expose enough to be useful; however, this will be addressed after more core features are implemented.
For now the minimum supported Rust version (MSRV) is 1.40.0.
Versioned binary releases for Linux, macOS, and Windows are available here. The binary can also be installed using cargo, which can be conveniently installed and managed using rustup.
$ cargo install ipld-schema$ ipld-schema generate
##
## Deterministically generated with ipld-schema 0.3.2
##
## - reproduction seed: 'gHvBv/QtyFqCo5SeeAaIS7vGtomE1fRIl0O2HXAPH2Y='
##
type Kvq9__ bytes
...$ ipld-schema generate --seed gHvBv/QtyFqCo5SeeAaIS7vGtomE1fRIl0O2HXAPH2Y=
##
## Deterministically generated with ipld-schema 0.3.2
##
## - reproduction seed: 'gHvBv/QtyFqCo5SeeAaIS7vGtomE1fRIl0O2HXAPH2Y='
##
type Kvq9__ bytes
...No output means it's considered valid.
$ ipld-schema validate my-schema.ipldsch
$Beware, the validator does not yet check everything. If you encounter schema it classifies incorrectly please file a bug with a minimal schema demonstrating the problem along with relevant context from the pinned specification to support your case.
$ ipld-schema generate my-schema.ipldsch
thread 'main' panicked at 'not yet implemented: generate data using seed 'EHVBvPdE6tDWMdCGkHrsf6zZQqIHZbBLrKJSqtBgsG0=' and schema "my-schema.ipldsch"' ...
##
## Deterministically generated with ipld-schema 0.3.2
##
## - reproduction seed: 'EHVBvPdE6tDWMdCGkHrsf6zZQqIHZbBLrKJSqtBgsG0='
## - schema file: "my-schema.ipldsch"
##$ validate my-schema.ipldsch my-data.json
thread 'main' panicked at 'not yet implemented: validate data ("my-data.json") using schema ("my-schema.ipldsch")' ...- DSL
- Parse the schema-schema
- Reified Form
- Convert parsed schema-schema to its reified JSON form
- Convert reified form of the schema-schema back to its DSL representation (sans comments)
- Generate arbitrary IPLD schemas in reified form from the parsed schema-schema
- Validate IPLD schema in reified form against the schema-schema and additional constraints (e.g. "rules around valid characters for type names")
- Generate Rust types from a valid IPLD schema
- Test generated IPLD schemas against implementations in other languages
- Parse IPLD values into Rust types generated from a compatible schema
- Generate arbitrary IPLD values from the reified form of some IPLD schema
- Verify generated IPLD values roundtrip through parsing to Rust types which were generated from the IPLD schema
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
See CONTRIBUTING.md.