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). 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: f8c5df2127c7. The Lab language identity is language:tool:convert; the registry view is ecosystem:tool/nika:convert. They refer to this contract without merging their graph identities.