Getting Started

Welcome to JSSON! Let’s get you writing cleaner, more readable JSON in just a few minutes. 🚀

Why JSSON? ✨

JSSON makes writing JSON feel natural. No more wrestling with quotes, commas, and brackets. Write configuration files the way you think about them — clean, readable, and human-friendly.

What makes JSSON special:

• No quotes needed for simple values
• Variables:
  • Global scope: Declared at root level, accessible everywhere
  • Local scope: Declared inside objects, scoped to that object
  • Shadowing: Inner scopes can override outer variables
  • Not in output: Variables are internal-only, never appear in final JSON
• Template arrays turn spreadsheet-like data into structured JSON
• Nested Arrays Map transformations can now be nested inside other maps for multi-level data pipelines
• Map transformations for powerful data manipulation
• Ranges generate sequences automatically
• Includes split large configs into manageable files
• Expressions compute values on the fly
• Multi-Format Output (JSON, YAML, TOML, TypeScript)

What You’ll Learn

By the end of this guide, you’ll:

• Install the JSSON CLI
• Write your first JSSON file
• Transpile it to JSON
• Understand the basics of JSSON syntax

Installation

1. Download the JSSON binary

   Head to the GitHub releases page and download the latest version for your platform.

2. Make it executable (Linux/macOS)

   chmod +x jsson

3. Move to your PATH (optional but recommended)

   # Linux/macOS
   sudo mv jsson /usr/local/bin/
   
   # Windows: Add the directory to your PATH environment variable

4. Verify installation

   jsson --version

Building from source? If you have Go installed, you can build JSSON yourself:

git clone https://github.com/carlosedujs/jsson
cd jsson
go build -o jsson cmd/jsson/main.go

Your First JSSON File

Let’s create a simple configuration file. Create a new file called config.jsson:

// My first JSSON file
app {
name = "My Awesome App"
version = "1.0.0"
debug = true
}

server {
host = "localhost"
port = 8080
}

Transpile It

Run the CLI to convert it to JSON:

jsson -i config.jsson > config.json

Open config.json and see the result:

{
  "app": {
    "name": "My Awesome App",
    "version": "1.0.0",
    "debug": true
  },
  "server": {
    "host": "localhost",
    "port": 8080
  }
}

Core Concepts

1. No Quotes Needed

JSSON

name = João
city = "São Paulo"  // Use quotes for spaces
age = 25

JSON

{
"name": "João",
"city": "São Paulo",
"age": 25
}

Rule of thumb: Use quotes when your value has spaces or special characters. Otherwise, skip them!

2. Objects Are Clean

JSSON

user {
name = João
email = joao@example.com
}

JSON

{
"user": {
  "name": "João",
  "email": "joao@example.com"
}
}

3. Arrays Are Simple

JSSON

colors = [ red, blue, green ]
numbers = [ 1, 2, 3, 4, 5 ]
mixed = [ João, 25, true ]

JSON

{
"colors": ["red", "blue", "green"],
"numbers": [1, 2, 3, 4, 5],
"mixed": ["João", 25, true]
}

4. Comments Work!

// This is a comment
name = João  // Inline comments too!
age = 25

Comments are ignored during transpilation — use them to document your configs!

5. Variables for Reuse

Declare variables with := to avoid repetition. Variables don’t appear in the final JSON:

JSSON

// Define once
api_url := "https://api.example.com"
timeout := 5000

// Use everywhere
production {
url = api_url
timeout = timeout
}

staging {
url = api_url
timeout = timeout
}

JSON

{
"production": {
  "url": "https://api.example.com",
  "timeout": 5000
},
"staging": {
  "url": "https://api.example.com",
  "timeout": 5000
}
}

Pro Tip: Variables are perfect for configuration constants that you use in multiple places!

Common First-Time Mistakes

❌ Forgetting Quotes for Multi-Word Values

// Wrong
title = Software Engineer

// Right
title = "Software Engineer"

❌ Using Commas Between Fields

// Wrong
name = João,
age = 25,

// Right
name = João
age = 25

JSSON doesn’t need commas! Just put each field on a new line.

❌ Mixing Syntax Styles

// Wrong - mixing object styles
user {
  name = João
  config = { theme: "dark" }  // Don't use JSON syntax inside JSSON
}

// Right
user {
  name = João
  config {
    theme = dark
  }
}

Quick Reference

Feature	JSSON	JSON
Keys	name = value	"name": value
Strings	João or "João"	"João"
Objects	obj { ... }	"obj": { ... }
Arrays	[ a, b, c ]	["a", "b", "c"]
Comments	// comment	❌ Not supported

Try It Yourself!

Create a file called practice.jsson and try this:

// Your personal info
person {
name = "Your Name"
age = 25
hobbies = [ coding, reading, gaming ]

address {
  city = "Your City"
  country = Brazil
}
}

// Your favorite numbers
luckyNumbers = [ 7, 13, 42 ]

Then transpile it:

jsson -i practice.jsson > practice.json

Open practice.json and see the beautiful JSON output!

What’s Next?

Now that you’ve got the basics down, here’s where to go:

• Basic Syntax Guide — Learn all the syntax features in detail
• Templates Guide — Discover the power of template arrays for structured data
• Multi-Format Guide — Learn how to output YAML, TOML, and TypeScript
• Syntax Reference — Complete reference with all features and examples

Ready to dive deeper? Let’s go! 🎯