Jsonnet

Jsonnet programs are composed entirely of expressions. There are no statements or special top-level declarations. Common constructs like import, if/else conditionals, function, object, and local are all expressions.

• Evaluation: Every expression evaluates to a value. Evaluation is side-effect free.
• Program Structure: A valid Jsonnet program does not need to be a top-level object; any expression is a valid program (e.g., 2+2 or "foo").
• Environment: The value of an expression depends on its environment (the values of the variables it refers to).

The Java implementation uses auxiliary framework classes to replicate Jsonnet's implicit behaviors:

• Test class: Responsible for selecting a specific object and manifesting it to stdout.
• JsonnetValue class: Implements manifestation using a visitor pattern over possible JSON values to build JSON strings. For objects, it iterates over nonHiddenFields and manifests each value by reflectively calling the corresponding method.

The C++ implementation of Jsonnet is not hardened for processing untrusted inputs (untrusted Jsonnet code). It is intended for evaluating code that you or your organization has written and trusts.

Risks:

• The import, importstr, and importbin language constructs can be used to exfiltrate sensitive data.
• By default, these constructs can import from any path accessible to the interpreter process.

If you must process untrusted code, consider using go-jsonnet or implementing a sandbox to restrict the interpreter's access.

Strings are sequences of Unicode codepoints. While they behave similarly to arrays in some contexts, they are distinct types.

• Array-like behavior: You can use std.length() or the [] operator to treat a string as an array of single-codepoint strings. Comparison operators (<, <=, >, >=, ==, !=) perform lexicographical comparison of codepoints.
• Strictness: Unlike arrays, strings are strict; evaluating a string requires calculating all its contents immediately.
• Construction: Strings can be created via literals, slices, concatenations, or by converting an array of Unicode codepoint numbers.

// String as array-like
"foo"[0] // "f"
std.length("foo") // 3

// Comparison
"a" < "b" // true

Jsonnet distinguishes between Equality (==) and Equivalence.

Equality (==)

• Values of different types are never equal (no implicit casting).
• a == b evaluates to true or false.
• Note: Functions cannot be checked for equality. Consequently, arrays or objects containing functions may be neither equal nor unequal (they cannot be compared).

Equivalence

Two values are equivalent if they are indistinguishable by any Jsonnet function. Equivalent values may have different internal representations but will behave identically in all contexts.

Key distinction: All equal values are equivalent, but not all equivalent values are equal (e.g., { a: 1, b: 1} and {a: 1, b: self.a} are equivalent but not equal).

Jsonnet supports seven fundamental value types. All values in Jsonnet are immutable; you cannot modify an existing object or array, you can only create a new one with the desired changes applied.

Supported Types:

• null: A single value, null.
• boolean: true and false.
• string: Unicode sequences.
• number: IEEE754 64-bit floating point numbers.
• function: Pure functions that take arguments and return a value.
• array: Finite-length sequences of values.
• object: Key-value mappings (a superset of JSON objects) with inheritance support.

You can determine the type of any value using std.type(value).

std.type(true) // "boolean"
std.type("hello") // "string"

Jsonnet numbers are IEEE754 64-bit floating point numbers.

• Constraints: nan and inf are not supported. Operations that would result in infinity or NaN will trigger an error.
• Safe Integers: Integers are safe within the range [-2^53 + 1, 2^53 - 1].
• Bitwise Operations: In C++ and Go implementations, bitwise operators (<<, >>, &, |, ^) are restricted to the safe integer range.

Jsonnet programs are pure computations. This means they have no side-effects and depend only on values explicitly passed to them. The behavior of a program is independent of the host system's environment (operating system, environment variables, or filesystem).

This hermeticity ensures:

• Predictability: Behavior won't change based on system setup.
• Portability: Programs run identically on development machines and CI/CD.
• Longevity: Code remains valid even as external technologies evolve.

Data from the environment can only be introduced to a program through explicit abstractions like Top-Level Arguments or External Variables.