Compatibility notes

JQ::Lite implements a useful jq-like language, but it is not a drop-in implementation of every jq runtime semantic. This document records the currently known semantic differences: cases where a filter is accepted by both tools but its result or failure behaviour differs. It is a snapshot of the 2.x behaviour, not a claim that unsupported jq syntax is supported.

The examples in the jq column describe jq 1.7 behaviour. The JQ::Lite results are protected by t/jq_semantic_differences.t; the regression suite does not require a jq executable.

Decision statuses

Every inventoried item has one of the decision statuses requested for the v3 planning process:

• preserve — keep the JQ::Lite meaning, even though jq differs;
• change in v3 — retain it throughout 2.x, but make jq compatibility the target of a separately reviewed v3 change;
• undecided — no v3 decision has been made. The 2.x behaviour remains regression-protected until that decision is made.

The status is a roadmap classification, not a runtime change in the 2.x series. “Follow-up” deliberately uses topic names rather than inventing issue numbers; it can be replaced by a concrete issue link when that work is filed.

Inventory

A. Preserved 2.x compatibility behaviour

These differences are observable existing behaviour on which 2.x callers may rely. Changing them requires an explicit compatibility decision rather than an incidental parser or filter refactor.

Area	Example	jq	JQ::Lite 2.x	v3 status	Follow-up
Array contains	[1,2,3] | contains([1,3])	true (recursive subset containment)	false (looks for one element equal to the complete argument)	change in v3	containment semantics
Nested object contains	{"a":{"b":1,"c":2}} | contains({"a":{"b":1}})	true	false (nested values must be equal)	change in v3	containment semantics
Alternative operator	false // 9	9	false (only null, missing, or empty output selects the fallback)	change in v3	null and fallback semantics
Jagged transpose	[[1,2],[3]] | transpose	[[1,3],[2,null]]	[[1,3]] (truncates to the shortest row)	preserve	none

For recursive, order-insensitive array containment, JQ::Lite provides the explicit contains_subset(value) alternative. It avoids changing the established meaning of contains(value) in the 2.x series, but it is not a drop-in implementation of jq's contains: it uses multiset counting, whereas jq can satisfy repeated needles with one matching value, and it compares scalars by their string forms, whereas jq keeps JSON scalar types distinct. For example, [1] | contains_subset([1,1]) is false although jq's contains([1,1]) is true; ["1"] | contains_subset([1]) is true although jq's contains([1]) is false.

B. Arithmetic and type coercion

JQ::Lite commonly favours lossless pipeline processing and Perl scalar coercion where jq reports a type error or applies a different overloaded operation.

Area	Example	jq	JQ::Lite 2.x	v3 status	Follow-up
Numeric coercion	"1e3" * 1	"1e3" (string repetition)	1000	undecided	arithmetic/coercion
Boolean arithmetic	true + 1	type error	2	change in v3	arithmetic/coercion
Vectorised rounding	[1.2,"2.8","x"] | floor	type error	[1,2,"x"]	preserve	none
Lossless JSON parsing	["1","true","bad"] | fromjson	type error (input is not a string)	[1,true,"bad"] (element-wise, invalid text passes through)	preserve	none
Regex scalar coercion	42 | match("2")	type error	a match object for the string form "42"	undecided	type coercion

This category is especially important when moving filters between the tools: successful JQ::Lite output does not imply that jq will accept the same input types. Conversely, jq operator overloading must not be assumed to use Perl's numeric coercion in JQ::Lite.

C. Comparison

Area	Example	jq	JQ::Lite 2.x	v3 status	Follow-up
Equality across types	"10" == 10	false	true (numeric-looking strings compare numerically)	change in v3	comparison semantics
Ordering across JSON types	false < 0	true	true	preserve	none; regression parity guard
Array ordering	[1,2] < [1,3]	true (lexicographic ordering)	false	change in v3	comparison semantics
Missing-value comparison	.missing == null	true	true	preserve	none; regression parity guard

Parity rows are included intentionally: they mark adjacent behaviour that was checked during the inventory and prevent a future coercion fix from changing a currently jq-compatible case by accident.

D. Null, missing values, and paths

Area	Example	jq	JQ::Lite 2.x	v3 status	Follow-up
Missing object field	{} with .missing	one null result	no results	change in v3	null/missing/path semantics
Path through a missing field	{} with .missing.value	one null result	no results	change in v3	null/missing/path semantics
Invalid array field path	{"a":[]} with .a.value	type error	no results	undecided	path error policy
Numeric index on an object	{} with .[5]	type error	one null result	change in v3	path error policy

JQ::Lite therefore distinguishes a missing traversal (an empty result stream) from an explicit JSON null in direct path output, even though comparisons such as .missing == null currently treat them alike.

E. Iterators and pipelines

Area	Example	jq	JQ::Lite 2.x	v3 status	Follow-up
Array path projection	[{"x":1},{"x":2}] | .x	type error	1, 2	preserve	none
Projection after mixed iteration	{"a":[{"x":1}],"n":3} | .[] | .x	type error on the array	1 (projects through the array and drops the scalar's missing value)	undecided	iterator/pipeline semantics
Iterator suffix	keys[]	same results as keys | .[]	same results as keys | .[]	preserve	none; regression parity guard
Comma plus iterator	0, [4,5][]	0, 4, 5	0, 4, 5	preserve	none; regression parity guard

F. Assignment and update

Area	Example	jq	JQ::Lite 2.x	v3 status	Follow-up
Plain assignment	{"a":1} | .a = 2	{"a":2}	{"a":2}	preserve	none; regression parity guard
Update assignment result	{"a":1} | .a |= . + 1	{"a":2}	2 (emits the updated value, not the root)	change in v3	assignment/update semantics
Missing update target	{"a":1} | .missing |= . + 1	object with "missing":1	no results	change in v3	assignment/update semantics
Multi-result assignment	{"a":0} | .a = (1,2)	two updated objects	no results	undecided	assignment/update stream semantics

G. Unsupported jq behaviour

Feature absence is distinct from a semantic conflict, but unsupported jq constructs affect portability and are therefore tracked here as required by the audit.

jq facility	Example	JQ::Lite 2.x	v3 status	Follow-up
User-defined functions	def inc: . + 1; inc	not implemented; currently evaluates to null	undecided	parser unsupported-syntax policy
Labels and break	label $out | break $out	not implemented	undecided	control-flow coverage
Modules/imports	import "x" as x; ...	not implemented	preserve	none; outside lightweight scope
jq streaming parser mode	--stream	CLI option not implemented	preserve	none; outside current CLI scope

H. Explicit JQ::Lite extensions and migration aids

These names do not represent a conflicting jq meaning; they make JQ::Lite's intent explicit or provide behaviours useful to existing pipelines.

Extension	Purpose	v3 status	Follow-up
contains_subset(value)	Recursive, order-insensitive multiset containment; unlike jq, duplicate needles require duplicate matches and scalar comparison coerces to strings	undecided	reconcile its semantics and name if contains changes in v3
to_number()	Lossless/vectorised numeric conversion, distinct from strict tonumber()	preserve	none
flatten_all(), flatten_depth(n)	Explicit flattening variants	preserve	none
Statistical and convenience helpers	avg, median, mode, percentile, variance, stddev, clamp, and the other extensions listed in the function reference	preserve	none

What this inventory does not cover

• The unsupported-behaviour table is representative rather than a complete list of every jq built-in or command-line option not implemented by JQ::Lite.
• CLI diagnostics are governed by the stable CLI contract; exact jq error text is not a JQ::Lite compatibility promise.
• Object key order is not compared because JSON object ordering is not a portable semantic guarantee.
• jq may evolve after 1.7. When this inventory is updated, jq-version changes and JQ::Lite behaviour changes should be reviewed separately.

When a new difference is found, add it to the appropriate category and add a dependency-free regression assertion for the current JQ::Lite behaviour. A future behaviour change should be proposed separately, with the relevant 2.x compatibility impact called out explicitly.