Jam | A cli for merging JSON and YAML files.

Jam is a simple, single (optional) dependency cli implemented in python which merges multiple JSON or YAML files into a single output document. It implements a local only $ref syntax inspired by JSON Schema that allows an input document to include other documents by path at merge time.

Table of Contents

• Quickstart
• Installing
• Usage

Quickstart

Install from PyPI with YAML support

pip install --user jam-tool[yaml]

~/jam > cat base.yaml
toplvlkey:
  midlvlkey:
    lowlvlkey: foo

~/jam > cat overlay01.yaml
toplvlkey:
  midlvlkey:
    lowlvlkey: bar

  midlvlkey2:
    $ref: ref01.yaml

toplvlkey2: foo

~/jam > cat ref01.yaml
lowlvlkey3: foobar

~/jam > jam -v base.yaml overlay01.yaml | tee > output.yaml
INFO::Merging document: base.yaml
INFO::Merging document: overlay01.yaml
INFO::Included reference: ref01.yaml
INFO::  in: overlay01.yaml
INFO::  resolved to: /home/jammy/jam/ref01.yaml
toplvlkey:
  midlvlkey:
    lowlvlkey: bar
  midlvlkey2:
    lowlvlkey3: foobar
toplvlkey2: foo

Installing

From PyPI

pip install --user jam-tool

If you need yaml support install the optional dependency PyYAML.

pip install --user jam-tool[yaml]

From Source

git clone https://github.com/tmacro/jam
cd jam
pip install --user .
# Or
pip install --user .[yaml]

Usage

usage: jam [-h] [--version] [-v] [-j] [-y] [ --array-strategy <strategy> ] [ -o OUTPUT ] input [ input ... ]

A cli for merging JSON and YAML files.

positional arguments:
  input                 Read input from one or more paths.

options:
  -h, --help            Show this help message and exit
  --version             Print program version information.
  -v, --verbose         Increase log verbosity. Can be passed multiple times.
  -j, --json            Force output in json format
  -y, --yaml            Force output in yaml format
  --array-strategy {replace,extend,merge}
                        Set merge strategy for arrays. One of "replace", "extend", or "merge".
                        Defaults to "replace"
  -o OUTPUT, --output OUTPUT
                        Write merged output to this path.