Basic Syntax

Ready to master JSSON? This guide covers all the fundamental syntax you need to know. Let’s build your JSSON skills from the ground up! 💪

Core Concepts

JSSON has just a few simple rules. Master these, and you’ll be writing clean configs in no time.

Assignments

The foundation of JSSON: key-value pairs.

name := João
age := 25
active := true

Rules:

• No quotes needed around keys
• Use = for assignment and := for variable declarations
• One assignment per line (no commas!)

When to Use Quotes

This is the #1 question! Here’s the simple rule:

No Quotes Needed

// Single words
name := João
city := Tokyo
status := active

// Numbers
age := 25
price := 19.99

// Booleans
admin := true
disabled := false

Quotes Required

// Values with spaces
title := "Software Engineer"
message := "Hello, World!"

// Values with special characters
email := "user@example.com"
url := "https://example.com"

// Empty strings
empty := ""

Pro Tip: When in doubt, use quotes! They always work. But skipping them makes your JSSON cleaner.

Data Types

JSSON supports all JSON data types with a friendlier syntax.

Strings

JSSON

// Without quotes (simple identifiers)
firstName = João
lastName = Silva

// With quotes (spaces or special chars)
fullName = "João Silva"
email = "joao@example.com"
bio = "Developer from Brazil 🇧🇷"

JSON Output

{
"firstName": "João",
"lastName": "Silva",
"fullName": "João Silva",
"email": "joao@example.com",
"bio": "Developer from Brazil 🇧🇷"
}

Numbers

JSSON

// Integers
age = 25
count = 100
negative = -42

// Floats
price = 19.99
temperature = 36.5
pi = 3.14159

JSON Output

{
"age": 25,
"count": 100,
"negative": -42,
"price": 19.99,
"temperature": 36.5,
"pi": 3.14159
}

Booleans

JSSON

active = true
disabled = false
isAdmin = true
hasAccess = false

JSON Output

{
"active": true,
"disabled": false,
"isAdmin": true,
"hasAccess": false
}

Objects

Objects in JSSON are beautifully simple — no colons, no commas, just clean nesting.

Simple Objects

JSSON

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

JSON Output

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

Nested Objects

JSSON

user {
name = João
contact {
  email = "joao@example.com"
  phone = "+55 11 99999-9999"
}
preferences {
  theme = dark
  language = pt-BR
  notifications {
    email = true
    push = false
  }
}
}

JSON Output

{
"user": {
  "name": "João",
  "contact": {
    "email": "joao@example.com",
    "phone": "+55 11 99999-9999"
  },
  "preferences": {
    "theme": "dark",
    "language": "pt-BR",
    "notifications": {
      "email": true,
      "push": false
    }
  }
}
}

Use Case: Objects are perfect for configuration files, API responses, and any hierarchical data.

Arrays

Arrays in JSSON are just like JSON, but cleaner — no quotes needed for simple values!

Simple Arrays

JSSON

// Numbers
numbers = [ 1, 2, 3, 4, 5 ]

// Strings (no quotes needed!)
colors = [ red, blue, green, yellow ]

// Mixed types
mixed = [ João, 25, true, 1.75 ]

// With quotes when needed
cities = [ "São Paulo", "Rio de Janeiro", Tokyo ]

JSON Output

{
"numbers": [1, 2, 3, 4, 5],
"colors": ["red", "blue", "green", "yellow"],
"mixed": ["João", 25, true, 1.75],
"cities": ["São Paulo", "Rio de Janeiro", "Tokyo"]
}

Arrays of Objects

JSSON

users = [
{ name = João, age = 25 },
{ name = Maria, age = 30 },
{ name = Pedro, age = 28 }
]

JSON Output

{
"users": [
  { "name": "João", "age": 25 },
  { "name": "Maria", "age": 30 },
  { "name": "Pedro", "age": 28 }
]
}

Arrays in Objects

You can use arrays directly as values for object properties:

JSSON

server {
host = localhost
port = 8080
allowedMethods = [ GET, POST, PUT, DELETE ]
features = [ logging, metrics, tracing ]
}

JSON Output

{
"server": {
  "host": "localhost",
  "port": 8080,
  "allowedMethods": ["GET", "POST", "PUT", "DELETE"],
  "features": ["logging", "metrics", "tracing"]
}
}

Better way: For arrays of objects, use template arrays — they’re much cleaner!

Comments

Document your configs with comments — they’re ignored during transpilation.

// This is a single-line comment

// Application settings
app {
name = "My App" // Inline comments work too!
version = "1.0.0"

// Server configuration
server {
port = 8080 // Default port
host = localhost
}
}

Pro Tip: Use comments to explain why a setting exists, not just what it is.

Variables

Declare variables with := to store values for reuse. Variables are not included in the final JSON output.

JSSON

// Declare variables
api_key := "sk-1234567890"
base_url := "https://api.example.com"
timeout := 5000

// Use them in configuration
production {
apiKey = api_key
endpoint = base_url + "/v1"
timeout = timeout
}

development {
apiKey = api_key
endpoint = base_url + "/dev"
timeout = timeout
}

JSON Output

{
"production": {
  "apiKey": "sk-1234567890",
  "endpoint": "https://api.example.com/v1",
  "timeout": 5000
},
"development": {
  "apiKey": "sk-1234567890",
  "endpoint": "https://api.example.com/dev",
  "timeout": 5000
}
}

Local Variables

Variables declared inside objects are local to that scope:

global := 100

obj {
local := 50
value = local // Uses local (50)
outer = global // Uses global (100)
}

// 'local' is not accessible here

Use Case: Variables are perfect for configuration constants, API keys, and any value you use multiple times.

Building from Simple to Complex

Let’s build a real-world example step by step.

Step 1: Basic Info

name = "My Application"
version = "1.0.0"
debug = true

Step 2: Add Objects

name = "My Application"
version = "1.0.0"
debug = true

server {
host = localhost
port = 8080
}

Step 3: Add Arrays

name = "My Application"
version = "1.0.0"
debug = true

server {
host = localhost
port = 8080
allowedOrigins = [ "http://localhost:3000", "https://example.com" ]
}

Step 4: Add Nesting

name = "My Application"
version = "1.0.0"
debug = true

server {
host = localhost
port = 8080
allowedOrigins = [ "http://localhost:3000", "https://example.com" ]
}

database {
connection {
host = localhost
port = 5432
name = myapp_db
}
pool {
min = 2
max = 10
}
}

See how natural it feels? No JSON ceremony, just clean configuration!

Multi-Format Output

Remember, JSSON isn’t just for JSON! You can transpile all of this to YAML, TOML, or TypeScript too.

See the Multi-Format Guide for details.

What’s Next?

You’ve mastered the basics! Here’s where to go from here:

• Templates Guide — Learn about template arrays for structured data
• Syntax Reference — Explore advanced features like ranges, expressions, and map clauses
• CLI Guide — Master the command-line tool

Ready for more power? Check out the Templates Guide to see how JSSON handles tabular data! 🚀