Templates Guide

Template arrays are JSSON’s superpower! 💪 They let you write data like a spreadsheet and get structured JSON objects. Perfect for seed data, mock APIs, and any tabular information.

The Problem Templates Solve

Imagine you need to create an array of user objects. In JSON:

{
"users": [
  {
    "name": "João",
    "age": 19,
    "job": "Student",
    "height": 1.75
  },
  {
    "name": "Maria",
    "age": 25,
    "job": "Teacher",
    "height": 1.65
  },
  {
    "name": "Pedro",
    "age": 30,
    "job": "Doctor",
    "height": 1.80
  }
]
}

That’s a LOT of repetition! 😫 Every object repeats the same keys.

The JSSON Way

With template arrays, you define the structure once, then just list the data:

JSSON
JSON Output

users [
template { name, age, job, height }
João, 19, Student, 1.75
Maria, 25, Teacher, 1.65
Pedro, 30, Doctor, 1.80
]

{
"users": [
  {
    "name": "João",
    "age": 19,
    "job": "Student",
    "height": 1.75
  },
  {
    "name": "Maria",
    "age": 25,
    "job": "Teacher",
    "height": 1.65
  },
  {
    "name": "Pedro",
    "age": 30,
    "job": "Doctor",
    "height": 1.80
  }
]
}

Think of it like a CSV: Define your columns once, then focus on the data!

Basic Syntax

The template syntax has two parts:

Template definition: template { field1, field2, field3 }
Data rows: One row per object, values separated by commas

arrayName [
template { column1, column2, column3 }
value1, value2, value3
value4, value5, value6
]

Real-World Examples

products [
template { id, name, price, inStock }
1, "Laptop", 999.99, true
2, "Mouse", 29.99, true
3, "Keyboard", 79.99, false
4, "Monitor", 299.99, true
5, "Webcam", 89.99, true
]

{
"products": [
  { "id": 1, "name": "Laptop", "price": 999.99, "inStock": true },
  { "id": 2, "name": "Mouse", "price": 29.99, "inStock": true },
  { "id": 3, "name": "Keyboard", "price": 79.99, "inStock": false },
  { "id": 4, "name": "Monitor", "price": 299.99, "inStock": true },
  { "id": 5, "name": "Webcam", "price": 89.99, "inStock": true }
]
}

API Routes

JSSON
JSON Output

routes [
template { path, method, auth }
"/users", GET, true
"/users/:id", GET, true
"/users", POST, true
"/posts", GET, false
"/posts/:id", GET, false
]

{
"routes": [
  { "path": "/users", "method": "GET", "auth": true },
  { "path": "/users/:id", "method": "GET", "auth": true },
  { "path": "/users", "method": "POST", "auth": true },
  { "path": "/posts", "method": "GET", "auth": false },
  { "path": "/posts/:id", "method": "GET", "auth": false }
]
}

Test Data

testUsers [
template { email, password, role, active }
"admin@test.com", "admin123", admin, true
"user@test.com", "user123", user, true
"guest@test.com", "guest123", guest, false
]

Perfect for seeding databases or creating mock data!

Map Clause: Transform Your Data

The map clause lets you transform each row into a richer object. This is where templates become REALLY powerful! 🔥

Basic Map

JSSON
JSON Output

routes [
template { path, method }

map (item) = {
  path = "/api/" + item.path
  method = item.method
}

users, GET
posts, POST
comments, DELETE
]

{
"routes": [
  { "path": "/api/users", "method": "GET" },
  { "path": "/api/posts", "method": "POST" },
  { "path": "/api/comments", "method": "DELETE" }
]
}

Adding Computed Fields

JSSON
JSON Output

users [
template { name, age, role }

map (user) = {
  name = user.name
  age = user.age
  role = user.role
  active = true
  createdAt = "2025-11-23"
  isAdmin = user.role
}

João, 25, admin
Maria, 30, editor
Pedro, 28, viewer
]

{
"users": [
  {
    "name": "João",
    "age": 25,
    "role": "admin",
    "active": true,
    "createdAt": "2025-11-23",
    "isAdmin": "admin"
  },
  {
    "name": "Maria",
    "age": 30,
    "role": "editor",
    "active": true,
    "createdAt": "2025-11-23",
    "isAdmin": "editor"
  },
  {
    "name": "Pedro",
    "age": 28,
    "role": "viewer",
    "active": true,
    "createdAt": "2025-11-23",
    "isAdmin": "viewer"
  }
]
}

String Concatenation

employees [
template { firstName, lastName, department }

map (emp) = {
  fullName = emp.firstName + " " + emp.lastName
  department = emp.department
  email = emp.firstName + "@company.com"
}

João, Silva, Engineering
Maria, Santos, Marketing
Pedro, Costa, Sales
]

Common Use Cases

1. Database Seed Data

users [
template { email, name, role, verified }
"admin@app.com", "Admin User", admin, true
"john@app.com", "John Doe", user, true
"jane@app.com", "Jane Smith", user, false
"test@app.com", "Test User", user, false
]

2. Mock API Responses

products [
template { id, name, category, price, stock }

map (p) = {
  id = p.id
  name = p.name
  category = p.category
  price = p.price
  stock = p.stock
  available = p.stock
  url = "/products/" + p.id
}

1, "Laptop Pro", electronics, 1299.99, 15
2, "Wireless Mouse", accessories, 29.99, 50
3, "USB-C Cable", accessories, 12.99, 100
]

3. Configuration Lists

environments [
template { name, url, apiKey }
development, "http://localhost:3000", "dev-key-123"
staging, "https://staging.app.com", "staging-key-456"
production, "https://app.com", "prod-key-789"
]

4. Test Cases

loginTests [
template { email, password, shouldSucceed }
"valid@test.com", "correct123", true
"invalid@test.com", "wrong", false
"admin@test.com", "admin123", true
"", "password", false
"user@test.com", "", false
]

Tips & Best Practices

1. Use Quotes for Multi-Word Values

users [
template { name, title, city }
João, "Software Engineer", "São Paulo"  // Quotes for spaces
Maria, Developer, Tokyo                  // No quotes needed
]

2. Keep Templates Simple

// Good ✅ - Simple template, complex logic in map
users [
template { name, age }
map (u) = {
  name = u.name
  age = u.age
  category = "adult"
  verified = true
}
João, 25
]

// Bad ❌ - Too many fields in template
users [
template { name, age, category, verified, createdAt, updatedAt }
João, 25, adult, true, "2025-11-23", "2025-11-23"
]

3. Use Map for Defaults

products [
template { name, price }

map (p) = {
  name = p.name
  price = p.price
  currency = "USD"      // Default value
  inStock = true        // Default value
  featured = false      // Default value
}

Laptop, 999.99
Mouse, 29.99
]

4. Combine with Includes

users [
template { name, email, role }
João, "joao@app.com", admin
Maria, "maria@app.com", user
]

// main.jsson
include "users.jsson"

app {
name = "My App"
}

When to Use Templates

Use templates when:

✅ You have multiple objects with the same structure
✅ You’re creating seed data or fixtures
✅ You’re defining lists of similar items (routes, products, users)
✅ You want to avoid repetitive JSON

Don’t use templates when:

❌ You only have 1-2 objects (just use regular objects)
❌ Each object has a completely different structure
❌ The data is highly nested (use regular objects instead)

Troubleshooting

Wrong Number of Values

Error: template expects 3 fields, got 2

Solution: Make sure each row has the same number of values as the template:

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

Missing Quotes

Error: unexpected token

Solution: Use quotes for values with spaces or special characters:

users [
template { name, title }
João, Software Engineer      // ❌ Space in "Software Engineer"
João, "Software Engineer"    // ✅ Quoted
]

What’s Next?

You’ve mastered templates! Here’s what to explore next:

Syntax Reference — Learn about ranges, expressions, and more
Include Modules — Organize large configs
CLI Guide — Master the command-line tool

Templates are one of JSSON’s most powerful features. Use them well! 🚀