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
• Template arrays turn spreadsheet-like data into structured JSON
• Map transformations for powerful data manipulation
• Ranges generate sequences automatically
• Includes split large configs into manageable files
• Expressions compute values on the fly

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
}

Notice how clean this is? No quotes around keys, no commas, no fuss!

Transpile to JSON

Now let’s convert this to JSON:

jsson -i config.jsson -o config.json

This creates config.json with perfect, valid JSON:

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

That’s it! You just wrote and transpiled your first JSSON file. 🎉

Understanding the Basics

Let’s break down what makes JSSON special:

1. No Quotes Needed (Usually)

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!

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 -o 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
• Syntax Reference — Complete reference with all features and examples

Ready to dive deeper? Let’s go! 🎯