json_decode()

def json_decode(json_string)

Parse a JSON string into a Starlark value.

This function takes a JSON-formatted string and converts it into a Starlark value (dictionary, list, string, number, boolean, or None). The JSON must be valid or this function will raise an error.

Raises: Raises an error if the JSON string is malformed or invalid

Args

• json_string: string: A valid JSON-formatted string to parse

Returns

A Starlark value representing the parsed JSON data (dict, list, string, number, bool, or None)

json_dumps()

def json_dumps(value, is_pretty)

Dump a JSON object to a string

Args

• value: The JSON object to dump
• is_pretty: bool: Whether to pretty print the JSON

Returns

The JSON string

json_encode()

def json_encode(value, pretty)

Convert a dictionary or value into a JSON string.

This function serializes Starlark dictionaries and other values into JSON-formatted strings suitable for output, file storage, or network transmission. By default, the output is compact. Use pretty=True for human-readable formatting with indentation.

Raises: Raises an error if the value cannot be serialized to JSON

Args

• value: The dictionary or Starlark value to encode as JSON
• pretty: bool: If True, returns formatted JSON with indentation and newlines. If False (default), returns compact JSON.

Returns

A JSON-formatted string representation of the input value

json_encode_compact()

def json_encode_compact(value)

Convert a value into a compact JSON string without whitespace.

This is a convenience function for encoding with minimal whitespace, useful for efficient network transmission or compact file storage. Equivalent to calling json_encode(value, pretty=False).

Args

• value: The dictionary or Starlark value to encode

Returns

A compact JSON string with no extra whitespace

json_encode_indented()

def json_encode_indented(value, indent)

Convert a value into a formatted JSON string with a configurable indent width.

This is the flexible alternative to json_encode_pretty, giving you direct control over how many spaces are used for each indentation level. The indent must be between 0 and 16 (inclusive).

Raises: Raises an error if indent is outside the range 0–16, or if the value cannot be serialized to JSON (e.g. NaN, Infinity).

Args

• value: The dictionary or Starlark value to encode
• indent: int: Number of spaces per indentation level (0–16, default 2). 0 adds newlines without indentation; 4 is a common alternative to the default 2-space style.

Returns

A formatted JSON string using indent spaces per level

json_encode_pretty()

def json_encode_pretty(value)

Convert a value into a formatted JSON string with indentation.

This is a convenience function for creating human-readable JSON output with proper indentation and newlines. Equivalent to calling json_encode(value, pretty=True). Always uses 2-space indentation; use json_encode_indented if you need a different width.

Args

• value: The dictionary or Starlark value to encode

Returns

A formatted JSON string with 2-space indentation and newlines

json_is_string_json()

def json_is_string_json(value) -> bool

Check if a string is a JSON object

Args

• value: string: The string to check

Returns

True if the string is a JSON object, False otherwise

json_is_valid()

def json_is_valid(json_string)

Check whether a string is valid JSON.

This function validates a string without parsing it, useful for checking JSON validity before attempting to decode it. Returns True if the string is valid JSON, False otherwise. Does not raise an error for invalid JSON.

Args

• json_string: string: The string to validate

Returns

True if the string is valid JSON, False otherwise

json_loads()

def json_loads(value)

Load a JSON string

Args

• value: string: The JSON string to load

Returns

The parsed JSON object

json_merge()

def json_merge(dict1, dict2)

Merge two dictionaries, with values from dict2 overwriting dict1.

This utility function performs a shallow merge of two dictionaries. Values from dict2 override those in dict1. For deep merging of nested structures, consider using json_merge recursively.

Example: ```starlark defaults = { “host”: “localhost”, “port”: 8080, “debug”: False, }

user_config = {
    "port": 9000,
    "debug": True,
}

final_config = json_merge(defaults, user_config)
print(final_config)
# Output:
# {
#     "host": "localhost",
#     "port": 9000,
#     "debug": true
# }
```

Args

• dict1: The base dictionary.
• dict2: The dictionary to merge in. Its values override dict1’s values.

Returns

dict: A new dictionary with merged values.

json_read_file()

def json_read_file(path)

Read and parse a JSON file into a Starlark value.

This is a convenience wrapper around fs.read_json_to_dict. It reads the file at the given path (relative to the workspace root), parses its contents as JSON, and returns the resulting Starlark value. I/O errors and JSON parse errors are both propagated as exceptions with descriptive messages.

Raises: Error: If the file cannot be read (I/O error) or contains invalid JSON

Args

• path: string: Path to the JSON file, relative to the workspace root

Returns

The parsed JSON value (dict, list, string, number, bool, or None)

json_try_decode()

def json_try_decode(json_string, default)

Attempt to decode a JSON string, returning a default value on failure.

This function provides safe JSON parsing with graceful error handling. If the string is not valid JSON, it returns the default value instead of raising an exception.

Internally this calls json.try_string_to_dict with the supplied default, so the input is parsed only once. A non-None default lets callers distinguish a successfully decoded JSON null (returns None) from a parse failure (returns the custom default):

Args

• json_string: string: The JSON string to decode.
• default: The value to return if decoding fails. Default is None.

Returns

The decoded value if successful, or the default value if decoding fails.

json_write_file()

def json_write_file(path, value, pretty)

Serialize a Starlark value to JSON and write it to a file.

This is a convenience wrapper around fs.write_json_from_dict. It converts the given value to JSON and writes it to the specified file path (relative to the workspace root). By default the output is pretty-printed with indentation. I/O errors and serialization errors are propagated as exceptions with descriptive messages.

Raises: Error: If the value cannot be serialized or the file cannot be written

Args

• path: string: Destination file path, relative to the workspace root
• value: The Starlark value (dict, list, etc.) to serialize
• pretty: bool: If True (default), write formatted JSON with indentation. If False, write compact JSON with no extra whitespace.

Returns

None