Every slice of JSON and YAML need a JYam spread

JYam REPL: The Complete Guide

For Every JSON YAML Slice, Spread Sweet JYam 🍯

Table of Contents

1. Introduction
2. Quick Start 3.Command Reference
3. Query Language
4. Scripting & Automation
5. Architecture & Performance
6. Advanced Features
7. Examples
8. Installation

— -

Introduction

JYam is a zero-dependency, cloud-native REPL toolkit for working with JSON and YAML. It provides an interactive shell experience similar to a database CLI, but for structured data files.

During my many years working as a Digital Modernaization and Transformation Architect; I have always wanted a tool which would allow me to work seamlessly with json/yaml.When one is working with modernizing onprem kubernetes clusters and workloads to cloud infrastructure a tool like jq or yq is invaluable but these tools have inherent problems because for every change yuo need to start the jq/yq instance and then drop it. this cycle occurs thousands of times.

Why JYam?

Large files cause memory issues : JYam uses Intelligent streaming & off-heap parsing Complex queries require heavy tools: JYam uses simple dot notation + JSONPath Cloud schemas are hard to navigate: JYam has builtin AWS/Azure/GCP support (ongoing work) Repetitive queries waste time : JYam allows creating| Variables, functions, loops, conditionals and logical operators

Quick Start

Installation

Download from releases

https://github.com/messages-one/jyam-repl/releases/download/1.0.0/jyam.exe

First Steps: example config.yaml

{
  "contexts": {
    "source": {
      "cluster": {
        "name": {
          "okd311-cluster": 8443
        }
      },
      "name": {
        "blogging-app/okd311-cluster": "8443/melreader"
      },
      "region": "us-west1",
      "zones": [
        "us-west1-b"
      ],
      "repo": {
        "url": {
          "https": "//abc.com/melvinmarshal.perei/boutique-openshift-3.11-api-resources.git"
        }
      }
    },
    "target": {
      "cluster": {
        "name": "gke-saas-env_us-central1-a_gke-migration-target-cluster"
      },
      "name": "gke",
      "region": "us-central3",
      "zones": [
        "us-central1-a"
      ]
    }
  },
  "project": {
    "gcp": {
      "bucket": {
        "name": "velero-guestbook-apigee-saas-labenv",
        "id": "default"
      },
      "name": "apigee-saas-labenv"
    },
    "os": {
      "name": "boutique-app"
    }
  }
}

download the windows executable or the self executing versions appropriate to your jdk.

c:> jyam.exe

or

c:> java -jar jyam-java8–1.0.0.jar

jyam> load d:\config.yaml jyam> .contexts.source.region “us-west1” jyam> .contexts.source.zones [“us-west1-b”, “us-west1-c”]

Command Reference

File Operations

Command: load <file>

Description: Load JSON/YAML file

Example: load d:\config.yaml

Command: save [file]`

—

Description: Save current data

Example: save output.json

Query & Display

| Command | Description | Example | | — — — — — | — — — — — — -| — — — — -| | <path> | Dot notation query | .contexts.source.region | | path <query> | JSONPath query | path $.contexts.*.region | | tree | Show paginated tree | tree -depth 3 | | tree -full | Full tree (no truncation) | tree -full | | tree -depth N | Set tree depth | tree -depth 5 | | more | Show preview again | more | | preview-depth N | Set preview depth (1–5) | preview-depth 3 | | pretty | Toggle pretty printing | pretty | | yaml / json | Switch output format | yaml |

Validation

| Command | Description | Example | | — — — — -| — — — — — — -| — — — — -| | validate <schema> | Validate against JSON Schema | validate schema.json | | openapi | Validate OpenAPI 3.1 | openapi |

Binary Operations

| Command | Description | Example | | — — — — -| — — — — — — -| — — — — -| | bin | Convert to MessagePack/CBOR | bin | | compress | Compress with GZIP | compress | | unpack <format> <file> | Unpack binary file | unpack msgpack data.msgpack |

Scripting

| Command | Description | Example | | — — — — -| — — — — — — -| — — — — -| | let <var>=<val> | Define variable | let env = “production” | | vars | Show variables | vars | | del <path> | Delete property | del .temp | | for <ext> | Loop over files | for json | | recurse <ext> | Recursive loop | recurse yaml | | if <condition> | Conditional statement | if .region == “us-west1” | | function <name> | Define function | function getRegion() | | call <name> | Call function | call getRegion() | | echo <message> | Print with variables | echo “Region is ${region}” | | exec <cmd> | Execute shell command | exec ls -la |

History & Utilities

| Command | Description | Example | | — — — — -| — — — — — — -| — — — — -| | history | Show command history | history | | !<number> | Repeat command | !3 | | !! | Repeat last command | !! | | trace | Toggle trace mode | trace | | strategy | Show loading strategy | strategy | | clear | Clear screen | clear | | help | Show help | help | | menu | Return to main menu | menu | | quit / exit | Exit JYam | quit |

Query Language

Dot Notation

Simple navigation

.contexts.source.region

Array access

.contexts.source.zones[0]

Keys with special characters (quoted)

.PropertyTypes.”AWS::ACMPCA::Certificate.ApiPassthrough”

Nested with special keys ensure special characters are enclosed in double quotes

.PropertyTypes.”AWS::ACMPCA::Certificate.ApiPassthrough”.Properties.Subject.Type

JSONPath

Basic query

path $.contexts.source.region

Array access

path $.contexts.source.zones[0]

Wildcards

path $.contexts.*.region

Recursive descent

path $..name

Filters

path “$.contexts[?(@.region == ‘us-west1’)]”

Keys with special characters

path “$.PropertyTypes[‘AWS::ACMPCA::Certificate.ApiPassthrough’]”

Key Rules

| Character | Dot Notation | JSONPath | | — — — — — -| — — — — — — — | — — — — — | | . in key | .”key.with.dots” | $[‘key.with.dots’] | | :: in key | .”AWS::EC2::Instance” | $[‘AWS::EC2::Instance’] | | / in key | .”key/with/slash” | $[‘key/with/slash’] | | Space in key | .”key with spaces” | $[‘key with spaces’] |

— -

Scripting & Automation

Variables

Define a variable

let region = .contexts.source.region let env = “production” let zones = .contexts.source.zones

Use variables

echo “Region is ${region}” path $.PropertyTypes[$cert]

Show all variables

vars

Delete a variable

del $name

Functions

Define a function

function getRegion() Enter function body (type ‘endfunction’ to finish): .contexts.source.region endfunction

Define function with parameters

function sum(a, b) Enter function body: let result = ${a} + ${b} echo “Result: ${result}” endfunction

Call functions

call getRegion() call sum(5, 3)

For Loops

Process all JSON files in current directory

for json Enter loop body (type ‘end’ to finish): load ${file} echo “Processing: ${filename}” path .metadata.name end

Process all YAML files recursively

recurse yaml Enter loop body: load ${file} echo ${filename} end

Loop with conditionals

for json Enter loop body: load ${file} if .metadata.labels.environment == “production” echo “Found production config: ${filename}” validate schema.json endif end

If Statements

Simple if

if .contexts.source.region == “us-west1” Enter if body (type ‘endif’ to finish): echo “West Coast deployment” endif

If-else

if .contexts.source.region == “us-west1” Enter if body: echo “West Coast” else echo “Other region” endif

Complex conditions

if .contexts.source.region == “us-west1” && .contexts.source.zones[0] == “us-west1-b” echo “Specific zone” endif

if .contexts.source.region == “us-west1” || .contexts.source.region == “us-east1” echo “US region” endif

Contains

if .contexts.source.repo.url.https contains “boutique” echo “Boutique repository” endif

Combined Scripting

Complex automation script

let env = “production” let region = .contexts.source.region

function deploy(service) Enter function body: echo “Deploying ${service} to ${env} in ${region}” .contexts.target.name = ${service} .contexts.target.region = ${region} endfunction

call deploy(“api-service”)

Loop with function

for json load ${file} if .contexts.source.region == “us-west1” call deploy(.contexts.source.name) endif end

— -

Advanced Features

Preview & Pagination

# Load with preview
jyam> load latest.json
 Preview (showing first 10 keys, depth 2)
 {
 “PropertyTypes”: { … },
 “ResourceTypes”: { … }
 … (305970 more lines)
 }

# Tree with pagination
jyam> tree
 — — Page 1/47 (lines 1–50) — -
 [DIR] PropertyTypes:
 [DIR] AWS::ACMPCA::Certificate.ApiPassthrough:
 [VAL] Documentation: “[http://docs.aws.amazon.com/](http://docs.aws.amazon.com/)..."
 [DIR] Properties:
 …

[Enter] continue, [q] quit, [n] next page:

Strategy Display

jyam> strategy

• — — — — — — — — — — — — — — — — — — — — — — — — — — — — — — -+ | Current Strategy |
• — — — — — — — — — — — — — — — — — — — — — — — — — — — — — — -+ | File: latest.json | | Size: 15.72 MB | | Strategy: Heap parser | | Engine: JYamParser.parse() -> JYamPath.query() (heap) |
• — — — — — — — — — — — — — — — — — — — — — — — — — — — — — — -+

Binary Support

Convert to binary formats

jyam> bin MessagePack: 512 bytes CBOR: 480 bytes

Compress

jyam> compress GZIP+MsgPack: 320 bytes GZIP+CBOR: 300 bytes

Unpack

jyam> unpack msgpack data.msgpack ✓ Unpacked

Examples

Example 1: AWS CloudFormation Exploration

Load AWS schema

jyam> load ~/.jyam/schemas/aws/latest.json

Find EC2 Instance properties

jyam> .ResourceTypes.”AWS::EC2::Instance”.Properties { “InstanceType”: {“Type”: “String”, “Required”: true}, “ImageId”: {“Type”: “String”, “Required”: true}, “SubnetId”: {“Type”: “String”, “Required”: false} }

Get specific property details

jyam> .ResourceTypes.”AWS::EC2::Instance”.Properties.InstanceType.Type “String”

Example 2: Kubernetes Config Validation

Load k8s deployment

jyam> load deployment.yaml

Query pods

jyam> path $.spec.template.spec.containers[*].name [“api”, “db”, “cache”]

Validate with schema

jyam> validate k8s-schema.json ✅ Valid

Example 3: DevOps Pipeline Script

Script to validate all production configs

jyam> let env = “production” jyam> for yaml Enter loop body: load ${file} if .metadata.labels.environment == ${env} echo “Validating production config: ${filename}” validate schema.json endif end ✓ Processed 12 files

Example 4: Data Transformation

Extract and transform

jyam> load data.json jyam> let users = .users jyam> for item in $users echo “${item.name} is ${item.age} years old” end John is 30 years old Jane is 25 years old

Example 5: Binary Format Comparison

jyam> load data.json jyam> bin MessagePack: 512 bytes CBOR: 480 bytes jyam> compress GZIP+MsgPack: 320 bytes GZIP+CBOR: 300 bytes — -

Installation

Download Release

Download from GitHub releases

wget https://github.com/messages-one/jyam-repl/releases/download/1.0.0/jyam.exe

The release also has self executing jars for multiple jdk versions:

• jyam-java8–1.0.0.jar
• jyam-java11–1.0.0.jar
• jyam-java17–1.0.0.jar
• jyam-java20–1.0.0.jar
• jyam-java21–1.0.0.jar
• jyam-java22–1.0.0.jar
• jyam-java23–1.0.0.jar
• jyam-java25–1.0.0.jar
• jyam-java26–1.0.0.jar
• jyam.exe

install the appropriate jdk and you are good to go.

java -jar <the right jar>

For every JSON YAML slice, spread sweet JYam. 🍯