FAQ

Frequently Asked Questions about JSSON - syntax, features, and common use cases.

Getting Started

What is JSSON?

JSSON (JavaScript Simplified Object Notation) is a human-friendly syntax that transpiles to JSON. It removes the ceremony of JSON while maintaining 100% compatibility.

Think of it as: You write JSSON → Transpiler outputs JSON

Why use JSSON instead of JSON?

JSON:

{
  "user": {
    "name": "João",
    "age": 25,
    "admin": true
  }
}

JSSON:

user {
  name = João
  age = 25
  admin = true
}

JSSON is cleaner, more readable, and supports comments!

How do I install JSSON?

Download the binary from GitHub Releases or build from source:

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

See the Getting Started guide for details.

Is JSSON production-ready?

Yes! JSSON transpiles to standard JSON, so the output is always valid and safe to use in production.

Syntax Questions

When do I need quotes?

Use quotes when:

Values have spaces: title = "Software Engineer"
Values have special characters: email = "user@example.com"
You want to force a string: version = "1.0.0"

Skip quotes when:

Simple identifiers: name = João
Numbers: age = 25
Booleans: active = true

Rule of thumb: When in doubt, use quotes!

Can I use comments?

Yes! Single-line comments with //:

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

Do I need commas between fields?

No! JSSON doesn't use commas between object fields:

// Correct ✅
user {
  name = João
  age = 25
}

// Wrong ❌
user {
  name = João,
  age = 25,
}

Can I reuse values?

Yes! Use variables (:=) to define values once and reuse them. Variables are not included in the output JSON.

// Define once
api_version := "v1"

// Reuse everywhere
service_a {
  version = api_version
}

service_b {
  version = api_version
}

How do I create nested objects?

Just nest them naturally:

user {
  name = João
  config {
    theme = dark
    notifications {
      email = true
      push = false
    }
  }
}

Can I mix JSSON and JSON syntax?

No. Choose one or the other. JSSON files should use JSSON syntax throughout.

Features

What are template arrays?

Template arrays let you define structure once, then list data rows:

users [
  template { name, age, job }
  João, 25, Developer
  Maria, 30, Designer
  Pedro, 28, Manager
]

See the Templates Guide for details!

What is the map clause?

The map clause transforms template data:

routes [
  template { path, method }
  
  map (item) = {
    path = "/api/" + item.path
    method = item.method
    version = "v1"
  }
  
  users, GET
  posts, POST
]

It adds computed fields and transforms values!

What are ranges?

Ranges generate numeric sequences using the .. operator.

Since v0.0.5, ranges work everywhere expressions are allowed!

// Basic ranges
ports = [ 8080..8085 ]
// Output: [8080, 8081, 8082, 8083, 8084, 8085]

// With step
evens = [ 0..10 step 2 ]
// Output: [0, 2, 4, 6, 8, 10]

// Inside map transformations (v0.0.5+)
data = (0..99 map (x) = {
  id = x
  value = x * 2
})

// Large-scale generation
bigData = 0..9999 // Generates 10,000 items!

// Combined ranges
numbers = [ 1..5, 10..15, 20..25 ]

Pro Tip: Ranges + map transformations = powerful data generation!

Can I nest map transformations?

Yes! Since v0.0.5, you can nest map() inside other map() transformations:

// Generate a multiplication table
table = (1..5 map (row) = (1..5 map (col) = row * col))

// Combinatorial data (all combinations)
combos = (["A", "B", "C"] map (letter) = (
  [1, 2, 3] map (num) = letter + num
))
// Output: [["A1","A2","A3"], ["B1","B2","B3"], ["C1","C2","C3"]]

// Product variants
products = (["S", "M", "L"] map (size) = (
  ["red", "blue"] map (color) = {
    size = size
    color = color
    sku = size + "-" + color
  }
))

This enables multi-level pipelines and complex data generation!

Can I use nested arrays?

Absolutely! Since v0.0.5, JSSON fully supports nested arrays:

// Matrix / 2D arrays
matrix = [
  [ 1, 2, 3 ],
  [ 4, 5, 6 ],
  [ 7, 8, 9 ]
]

// Nested arrays in objects
config {
  permissions = [
    [ read, write ],
    [ admin, sudo ]
  ]
}

// Generated with nested maps
grid = (0..2 map (y) = (0..2 map (x) = [x, y]))

Nested arrays work in templates, maps, objects, and as direct values!

How do includes work?

Use include to split large configs:

database.jsson:

database {
  host = localhost
  port = 5432
}

main.jsson:

include "database.jsson"
host = localhost
port = 8080

Use Cases

What is JSSON good for?

Configuration files (app configs, server settings)
Seed data (database fixtures, test data)
Mock APIs (fake data for development)
Structured lists (products, users, routes)
Data templates (CSV-like data → JSON)
Matrix generation (grids, coordinates, combinatorial data) — New in v0.0.5!

When should I use nested maps?

Use nested maps when you need:

Matrix-like structures — Grids, coordinate systems, 2D/3D data
Combinatorial data — All combinations of product variants (sizes × colors)
Multi-level pipelines — Transform data at multiple nested levels
Large-scale generation — Create thousands of records with patterns

// Perfect for nested maps ✅
products = (["S", "M", "L"] map (size) = (
  ["red", "blue"] map (color) = {
    sku = size + "-" + color
  }
))

// Better with templates ✅
users [
  template { name, email }
  João, "joao@test.com"
  Maria, "maria@test.com"
]

Rule of thumb: Use nested maps for generated patterns, templates for explicit data.

How do I generate large datasets?

JSSON v0.0.5 makes large-scale data generation trivial:

// Generate 10,000 records
users = (0..9999 map (id) = {
  id = id
  username = "user_" + id
  email = "user_" + id + "@example.com"
  active = true
})

// Generate 1 million coordinates (1000x1000 grid)
grid = (0..999 map (y) = (0..999 map (x) = {
  x = x
  y = y
  id = y * 1000 + x
}))

Performance: JSSON can handle millions of records. The transpiler is fast!

Can I use JSSON for large files?

Yes! Use include to split large configs into modules:

config/
├── main.jsson
├── database.jsson
├── api.jsson
└── cache.jsson

Can I use JSSON with my build tool?

Yes! Integrate with npm scripts, Makefiles, or CI/CD:

package.json:

{
  "scripts": {
    "build:config": "jsson -i config.jsson -o dist/config.json"
  }
}

See the CLI Guide for integration examples!

Is JSSON faster than JSON?

JSSON adds a transpilation step, so it's slightly slower than parsing JSON directly. However:

Development: JSSON is faster to write and maintain
Production: Use transpiled JSON (no runtime overhead)

Can I validate JSSON files?

Yes! Run the transpiler to check for errors:

jsson -i config.jsson

// Wrong ❌
email = user@example.com

// Right ✅
email = "user@example.com"

My template has the wrong number of values

Each row must match the template:

users [
  template { name, age, email }
  João, 25, "joao@test.com"  // ✅ 3 values
  Maria, 30                   // ❌ Only 2 values
]

Include file not found

Check that:

The file exists
The path is correct (relative to the including file)
The extension is .jsson

Can't apply operator to range literal

Invalid operations on range literals produce errors:

// ❌ Wrong: Can't apply modulo to range literal
result = 0..10 % 5  // Error!

// ✅ Right: Apply modulo inside map
result = (0..10 map (x) = x % 5)

// ❌ Wrong: Can't multiply range directly
data = 0..10 * 2  // Error!

// ✅ Right: Use map transformation
data = (0..10 map (x) = x * 2)

Rule: Operations on ranges must be done inside map transformations.

Nested maps not working as expected

Make sure you're using parentheses correctly:

// ❌ Wrong: Missing parentheses
grid = 0..2 map (y) = 0..2 map (x) = x + y  // Error!

// ✅ Right: Proper parentheses
grid = (0..2 map (y) = (0..2 map (x) = x + y))

// ❌ Wrong: Incorrect nesting
data = (0..5 map (x) = 0..5 map (y) = x * y)  // Error!

// ✅ Right: Inner map also needs parentheses
data = (0..5 map (x) = (0..5 map (y) = x * y))

Tip: Each map expression needs its own parentheses when nested!

Where can I get help?

Errors & Debugging — Common errors and solutions
GitHub Issues — Report bugs or ask questions
Syntax Reference — Complete syntax guide

Contributing

Can I contribute to JSSON?

Yes! JSSON is open source. See the Contributing Guide for details.

How do I report a bug?

Open an issue on GitHub with:

Your JSSON code
The error message
Expected vs actual behavior

Can I request a feature?

Absolutely! Open a feature request on GitHub Issues.