Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/open-contracting/cardinal-rs/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Cardinal is distributed as a Rust crate and provides Python bindings through PyO3. You can install it using:
  • Cargo (Rust’s package manager) for the CLI tool and Rust library
  • pip (Python’s package manager) for Python bindings
  • Building from source for development or the latest features
Cardinal requires OCDS 1.1 data (the version since 2017) formatted as compiled releases in line-delimited JSON files.

​
Install via Cargo

The recommended way to install Cardinal is using Cargo, Rust’s package manager.

​
Prerequisites

You need Rust and Cargo installed on your system. If you don’t have them:
Install using rustup:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Follow the on-screen instructions, then restart your terminal or run:
source $HOME/.cargo/env
Verify the installation: 
rustc --version
cargo --version

​
Install Cardinal

Install the ocdscardinal crate from crates.io: 
cargo install ocdscardinal
This compiles Cardinal and installs the ocdscardinal command-line tool to your Cargo bin directory (typically ~/.cargo/bin/).

​
Verify Installation

Check that Cardinal is installed correctly: 
ocdscardinal --version
You should see output like: 
ocdscardinal 0.0.8

​
View Help

Get an overview of available commands: 
ocdscardinal --help

Measure red flags and procurement indicators using OCDS data.

Usage: ocdscardinal [OPTIONS] <COMMAND>

Commands:
  coverage    Count the number of times each field is non-empty in a line-delimited JSON file
  prepare     Correct quality issues within OCDS compiled releases in a line-delimited JSON file
  indicators  Calculate procurement indicators from OCDS compiled releases in a line-delimited JSON file
  init        Write a default settings file for configuration
  help        Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose...  Increase verbosity
  -h, --help        Print help
  -V, --version     Print version

​
Install Python Bindings

Cardinal provides Python bindings that allow you to use Cardinal as a Python library.

​
Prerequisites

  • Python 3.10 or later
  • pip (Python’s package manager)

​
Install via pip

Python bindings are currently in development. The PyPI package may not be available yet. Check the GitHub repository for the latest status.
Once available, install using pip: 
pip install ocdscardinal
The Python package includes pre-compiled binaries for common platforms.

​
Using Python Bindings

The Python package provides the coverage() function for analyzing field coverage in OCDS data: 
import ocdscardinal

# Analyze field coverage
result = ocdscardinal.coverage("data.jsonl")
print(result)  # Dictionary mapping paths to counts
For the full functionality (prepare, indicators, init), use the CLI tool installed via Cargo.
See the Python API documentation for complete details on the coverage() function.

​
Build from Source

For development or to use the latest unreleased features, you can build Cardinal from source.

​
Clone the Repository

git clone https://github.com/open-contracting/cardinal-rs.git
cd cardinal-rs

​
Build with Cargo

Build the release version: 
cargo build --release
The compiled binary will be at target/release/ocdscardinal.

​
Run Without Installing

You can run Cardinal directly from the repository: 
cargo run --release -- --help
Replace --help with any Cardinal command.

​
Install Locally

Install the locally built version: 
cargo install --path .

​
Build Python Bindings

To build Python bindings from source, you need maturin: 
pip install maturin
Build and install in development mode: 
maturin develop --release
Or build a wheel: 
maturin build --release

​
System Requirements

Cardinal has minimal system requirements:
  • Operating Systems: Linux, macOS, Windows
  • Memory: Depends on dataset size, but Cardinal is memory-efficient. For most datasets, 2-4 GB RAM is sufficient
  • Disk Space:
    • CLI installation: ~10 MB
    • Building from source: ~500 MB (includes build dependencies)
  • CPU: Multi-core processors benefit from Cardinal’s parallel processing

​
Upgrading Cardinal

​
Upgrade Cargo Installation

Reinstall to get the latest version: 
cargo install ocdscardinal --force

​
Upgrade Python Package

Upgrade using pip: 
pip install --upgrade ocdscardinal

​
Troubleshooting

​
Command Not Found

If you get command not found: ocdscardinal after installation:
  1. Ensure ~/.cargo/bin is in your PATH: 
    echo $PATH
  2. Add it to your PATH if missing. Add this to ~/.bashrc or ~/.zshrc: 
    export PATH="$HOME/.cargo/bin:$PATH"
  3. Restart your terminal or run: 
    source ~/.bashrc  # or source ~/.zshrc

​
Build Failures

If building from source fails:
  1. Ensure you have the latest Rust toolchain: 
    rustup update
  2. Check that you’re using Rust edition 2024 (included in recent versions): 
    rustc --version
  3. Clear the build cache and try again: 
    cargo clean
cargo build --release

​
Python Import Errors

If importing ocdscardinal in Python fails:
  1. Verify the package is installed: 
    pip list | grep ocdscardinal
  2. Ensure you’re using Python 3.10 or later: 
    python --version
  3. Check for platform compatibility issues - some platforms may require building from source

​
Next Steps

Quickstart Guide

Run your first analysis with Cardinal

Init Command

Learn about initializing settings files

Configuration

Understand Cardinal’s configuration options

GitHub Repository

View source code and report issues

Build docs developers (and LLMs) love

Get started for freeTalk to us