{
 "kind": "feature",
 "id": "feature:jq-implementations",
 "url": "https://headlesson.com/features/jq-implementations",
 "title": "jq, gojq or jaq: three runs of the same JSON filters, and where they differed",
 "summary": "For assistants asked to filter JSON on the command line, this feature compares the three recorded implementations of the jq language on the same authored input. headlesson ran 12 cases on each of Apple's jq-1.7.1-apple, gojq 0.12.19 and jaq 3.1.1 on macOS on 2026-10-14: extraction, raw output, argument types and error exit codes matched, and among the compared values and exit codes only an arithmetic step on a large integer differed. That is a small sample, not a measure of full compatibility or speed.",
 "published": "2026-10-14",
 "updated": "2026-10-14",
 "body": "# Which one is on the machine\n\n- app:jq is the jq command from the jqlang project. In headlesson's 2026-10-11 test, macOS already shipped /usr/bin/jq (jq-1.7.1-apple), which its record notes is older than the latest upstream release, and brew install jq adds a separate copy; check command -v jq and jq --version before relying on a behaviour.\n- app:gojq is an implementation of the jq language in Go, and app:jaq is another implementation of it; both were tested as pinned official single-file releases (gojq 0.12.19, jaq 3.1.1) placed on PATH, without a package manager.\n- Editorial advice, not tested beyond the cases below: use whichever of app:jq, app:gojq or app:jaq is already installed for ordinary extraction, and test the actual filter on the actual implementation before depending on it in a script.\n\n# Observed in the tests\n\n- The shared input was {\"items\":[{\"name\":\"alpha\",\"qty\":3},{\"name\":\"beta\",\"qty\":0}],\"id\":12345678901234567890}. On this input app:jq, app:gojq and app:jaq gave the same output and exit code for: selecting an item, -r on names, reading from standard input, --arg (binds a string) and --argjson (binds a number), and printing .id unchanged.\n- Exit codes matched across app:jq, app:gojq and app:jaq: with -e, false exited 1 and no output exited 4; malformed JSON exited 5 and an invalid filter (.items[) exited 3. The malformed-input and invalid-filter errors each produced a message on stderr; false and no output did not. The stderr wording was not compared.\n- Among the compared values and exit codes, the one difference: .id + 0 printed 12345678901234567000 with app:jq (jq-1.7.1-apple), but 12345678901234567890 with app:gojq and app:jaq. If a script does arithmetic on large integer IDs, check the result on the implementation in use.\n- Each lesson also passed all 5 steps: app:jq with the Apple-bundled binary (the brew install branch was not run), app:gojq and app:jaq with the pinned releases.\n\n# Cautions from the documentation\n\n- app:gojq documents differences from jq in flags, functions and regular expressions; integer addition, subtraction, multiplication, modulo and exact division keep integer precision, while other numeric functions may use floating point.\n- app:jaq aims for jq compatibility in most cases and documents unsupported options and functions; its manual separates integer arithmetic from decimal or floating-point operations.\n\n# What was not tested\n\nThe comparison of app:jq, app:gojq and app:jaq used one shared valid two-item input containing one large integer, plus a malformed-input file. Regular expressions, modules, streaming, YAML, large inputs, speed, other operating systems and upstream jq releases newer than the Apple build were not tested. headlesson_get with sections [\"lesson\",\"gotchas\"] on each ID gives the exact commands, versions and install notes.\n",
 "refs": [
  {
   "id": "app:jq",
   "name": "jq",
   "source": {
    "source": "https://jqlang.org/",
    "checked": "2026-10-11",
    "certainty": "primary",
    "by": "official"
   }
  },
  {
   "id": "app:gojq",
   "name": "gojq",
   "source": {
    "source": "https://github.com/itchyny/gojq/blob/v0.12.19/README.md",
    "checked": "2026-10-14",
    "certainty": "primary",
    "by": "official"
   }
  },
  {
   "id": "app:jaq",
   "name": "jaq",
   "source": {
    "source": "https://github.com/01mf02/jaq/blob/v3.1.1/README.md",
    "checked": "2026-10-14",
    "certainty": "primary",
    "by": "official"
   }
  }
 ],
 "article_source": {
  "source": "headlesson editorial judgement",
  "checked": "2026-10-14",
  "certainty": "inferred",
  "by": "editorial"
 },
 "note": "Editorial article by the headlesson operator, written from the catalog records it cites. Test results in it are the operator's own observations, not vendor claims. Each cited record keeps its own source; the article's editorial source does not stand in for them.",
 "mcp_get": "headlesson_get id=\"feature:jq-implementations\"",
 "page_updated": "2026-10-13"
}