This crate is very much experimental and is being developed as a personal learning exercise for getting acquainted with Rust and about parsing in general. It does not yet completely conform to the spec. There are likely more performant and stable libraries out there for parsing CDDL. This one should not be used in production in any form or fashion.
A Rust implementation of the Concise data definition language (CDDL). CDDL is an IETF standard that "proposes a notational convention to express CBOR and JSON data structures." As of 2019-06-12, it is published as RFC 8610 (Proposed Standard) at https://tools.ietf.org/html/rfc8610.
This crate includes a handwritten parser and lexer for CDDL and is heavily inspired by Thorsten Ball's book "Writing An Interpretor In Go". The AST has been built to closely match the rules defined by the ABNF grammar in Appendix B. of the spec. All CDDL must use UTF-8 for its encoding per the spec.
This crate supports validation of both CBOR and JSON data structures. An extremely basic REPL is included as well, along with a compiled WebAssembly target. This crate requires Rust v1.37.0+.
no_std support (lexing and parsing only)Rust is a systems programming language designed around safety and is ideally-suited for resource-constrained systems. CDDL and CBOR are designed around small code and message sizes and constrained nodes, scenarios that Rust has also been designed for.
A CLI has been made available for various platforms and as a Docker image. It can downloaded from the Releases tab. The tool supports parsing of .cddl files for verifying conformance against RFC 8610. It also supports validation of .cddl documents against .json files. Detailed information about the JSON validation functions can be found in the validating JSON section below. Instructions for using the tool can be viewed by executing the help subcommand:
$ cddl help
If using Docker:
Ensure your Docker client has been authenticated into GitHub Package Registry. Replace
<version>with an appropriate release tag. Requires use of the--volumeargument for mounting.cddland.jsondocuments into the container when executing the command. The command below assumes these documents are in your current working directory.
$ docker run -it --rm -v $PWD:/cddl -w /cddl docker.pkg.github.com/anweiss/cddl/cddl:<version> help
You can also find a simple RFC 8610 conformance tool at https://cddl.anweiss.tech. This same codebase has been compiled for use in the browser via WebAssembly.
Incomplete. Under development
This crate uses the Serde framework, and more specifically, the serdejson crate, for parsing and validating JSON. Serde was chosen due to its maturity in the ecosystem and its support for serializing and deserializing CBOR via the serdecbor crate.
As outlined in Appendix E. of the standard, only the JSON data model subset of CBOR can be used for validation. The limited prelude from the spec has been included below for brevity:
```cddl any = #
uint = #0 nint = #1 int = uint / nint
tstr = #3 text = tstr
number = int / float
float16 = #7.25 float32 = #7.26 float64 = #7.27 float16-32 = float16 / float32 float32-64 = float32 / float64 float = float16-32 / float64
false = #7.20 true = #7.21 bool = false / true nil = #7.22 null = nil ```
Furthermore, the following data types from the standard prelude can be used to validate JSON strings:
cddl
tdate = #6.0(tstr)
uri = #6.32(tstr)
The first non-group rule defined by a CDDL data structure definition determines the root type, which is subsequently used for validating the top-level JSON data type.
The following types and features of CDDL are supported by this crate for validating JSON:
| CDDL | JSON | | -------------------- | ----------------------------- | | structs | objects | | arrays | arrays1 | | text / tstr | string | | number / int / float | number2 | | bool / true / false | boolean | | null / nil | null | | any | any valid JSON |
Since JSON objects only support keys whose types are JSON strings, member keys defined in CDDL structs must use either the colon syntax (mykey: tstr) or the double arrow syntax with double quotes ("mykey" => tstr). Unquoted member keys used with the double arrow syntax must resolve to one of the supported data types that can be used to validate JSON strings (text or tstr). Occurrence indicators can be used to validate key/value pairs in a JSON object and the number of elements in a JSON array; depending on how the indicators are defined in a CDDL data definition. CDDL groups, generics, sockets/plugs and group-to-choice enumerations are all parsed and monomorphized into their full representations before being evaluated for JSON validation.
Below is the table of supported control operators and whether or not they've been implemented as of the current release:
| Control operator | Implementation status |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| .pcre | .regex | .pcre) |
| .size | Incomplete |
| .bits | Unsupported for JSON validation |
| .cbor | Unsupported for JSON validation |
| .cborseq | Unsupported for JSON validation |
| .within | Incomplete |
| .and | Incomplete |
| .lt | .le | .gt | .ge | .eq | Partial (text and numeric values) |
| .ne | Incomplete |
| .default | Incomplete |
1: When groups are used to validate arrays, group entries with occurrence indicators are ignored due to complexities involved with processing these ambiguities. For proper JSON validation, avoid writing CDDL that looks like the following: [ * a: int, b: tstr, ? c: int ].
2: While JSON itself does not distinguish between integers and floating-point numbers, this crate does provide the ability to validate numbers against a more specific numerical CBOR type, provided that its equivalent representation is allowed by JSON.
3: Due to Perl-Compatible Regular Expressions (PCREs) being more widely used than XSD regular expressions, this crate also provides support for the proposed .pcre control extension in place of the .regexp operator (see Discussion and CDDL-Freezer proposal). Ensure that your regex string is properly JSON escaped when using this control.
CDDL, JSON schema and JSON schema language can all be used to define JSON data structures. However, the approaches taken to develop each of these are vastly different. A good place to find past discussions on the differences between thse formats is the IETF mail archive, specifically in the JSON and CBOR lists. The purpose of this crate is not to argue for the use of CDDL over any one of these formats, but simply to provide an example implementation in Rust.
Incomplete. Under development. Less complete than JSON validation functions.
This crate also uses Serde and serde_cbor for validating CBOR data structures. Similary to the JSON validation implementation, CBOR validation is done via the loosely typed serde_cbor::Value enum. Unfortunately, due to a limitation of Serde, CBOR tags are ignored during deserialization.
no_std supportOnly the lexer and parser can be used in a no_std context provided that a heap allocator is available. This can be enabled by opting out of the default features in your Cargo.toml file as follows:
toml
[dependencies]
cddl = { version = "<version>", default-features = false }
Zero-copy parsing is implemented to the extent that is possible, with prefixed byte strings containing whitespace being one of the few exceptions where allocation is required. Allocation is also used for error handling and diagnostics.
Both JSON and CBOR validation are dependent on their respective heap allocated Value types, but since these types aren't supported in a no_std context, they subsequently aren't supported in a no_std context in this crate.