Skip to main content
Builtins catalog / nika:convert

Data

Tool family from the canonical registry.

invoke

Call this builtin through the invoke verb.

​
Read this contract

This reference preserves the specification at the revision linked below. Source examples are fragments: their surrounding tasks, inputs and permissions are not supplied here. Consult engine status and nika catalog --tools --json for the installed implementation; a registry declaration is not a runtime qualification.

​
Usage and behavior

illustration
Universal format converter · 4 formats v0.1 (json · yaml · toml · csv) · 12 directions in scope (4×3 minus identity) · from == to is rejected (NIKA-BUILTIN-CONVERT-001 · validation_error · an identity conversion is an authoring bug). Throws · -002 (the input does not parse as from: · tool_error). CSV cells (normative) · reading CSV yields every cell as a string ("10", never 10): convert before arithmetic or ordering, e.g. map(.amount | tonumber) | add in nika:jq, since add over strings concatenates and max_by over strings orders text. The field separator is counted on the first line outside double quotes: a semicolon (a European spreadsheet export, whose decimals take the comma) or a tab that outnumbers the comma is the separator, otherwise the comma (RFC 4180). Emitting CSV writes a JSON null as an empty cell, as an absent key already is, never the text null. columns (CSV emit only) · an array of column names in the required order. JSON objects carry no key order: without columns, output keys are sorted alphabetically. Named columns come first (even for empty rows); any other keys follow sorted. To preserve a CSV header through filtering, pass its observed columns in their original order to the JSON→CSV conversion. Duplicate names retain their first position; a named column absent from every row is emitted with empty cells. A non-array or non-string member is a NIKA-BUILTIN-CONVERT-001 error, never a silent fallback to the default order. formula_guard still applies to the emitted headers and cells. formula_guard (CSV emit only · default false) · opt-in CSV formula-injection guard (CWE-1236). A spreadsheet (Excel · Sheets · LibreOffice) interprets a cell whose FIRST non-whitespace character is = + - @ (or a leading \t/\r control char) as a formula — so =HYPERLINK(…) or =cmd|… in untrusted data executes when the file is opened. With formula_guard: true, such a cell (data OR header key) is prefixed with a single quote ' — the OWASP mitigation those apps render as literal text. Opt-in because it ALTERS data: a legitimate negative number -5 becomes the text '-5. Enable it when the CSV carries untrusted data AND is destined for a spreadsheet; leave it off (the default) for clean machine round-trips — matching the Rust/Python csv ecosystem, where the spreadsheet is the consumer’s trust boundary. A non-boolean value is a loud -001 arg error (never silently read as false). Pattern · fetch+extract symmetry · single super-powerful builtin · from/to mode parameters · all bidirectional pairs canonical · no per-direction builtin slot. Replaces · legacy nika:csv_to_json (cut per ADR-086 · D-2026-05-27 Rams sweep · the « less but better » builtin-by-builtin review that cut the canonical set to 22). The reverse direction (JSON→CSV) is ALSO covered here · nika:convert is the canonical multi-format builtin for BOTH directions (the embedded jaq has no @csv/@tsv filter, so there is no in-jq alternative — nika:convert to: csv is the one path). Reference implementation · serde_transcode 1.1+ orchestrator (zero-allocation walk · serde-ecosystem canonical · 15M+ downloads · sfackler) + format-specific crates · serde_json (JSON · already nika dep) · serde_yaml_bw 2.5+ (YAML · modern + maintained 2026) · toml 1.1+ (TOML · spec 1.1.0 compliant) · csv 1.4+ (CSV · quoting-aware).

Arguments

Pass the values required by the tool contract.

Permissions

Understand authority before granting effects.

Errors and recovery

Read diagnostics and choose a recovery policy.

Workflow templates

Put the fragment inside a complete workflow.

​
Contract provenance

Read the pinned specification · Canonical registry. Tool identity: nika:convert. Specification revision: 5cd95cd25c0f.

Documentation

Guides, reference contracts and working examples.

Language spec

the nine-key envelope, Apache-2.0. The contract these docs explain.

Engine source

Rust, AGPL-3.0-or-later. Every commit public.

TypeScript SDK

Use one typed lifecycle locally or against authenticated nika serve HTTP.

Editor extension

The editor extension, frozen at 0.120 and not qualified with 0.124: use nika lsp and the JSON Schema.

Homebrew tap

brew install supernovae-st/tap/nika for the latest tagged CLI release.

SuperNovae

The Paris studio crafting Nika. 🦋