JSON Syntax Explained: Objects, Arrays, and the Mistakes That Break APIs

// io.thecodeforge — JavaScript tutorial

// The six legal JSON value types — know these cold.
// Every valid JSON document is built from exactly these primitives.

const validJsonValues = {
  // 1. String — MUST use double quotes. Single quotes = invalid JSON.
  productName: "Running Shoe",

  // 2. Number — integer or decimal, no quotes around it.
  priceInCents: 9999,
  weightKg: 0.85,

  // 3. Boolean — lowercase only. True/False with capitals = invalid JSON.
  inStock: true,
  onSale: false,

  // 4. Null — lowercase only. Represents intentional absence of a value.
  discountCode: null,

  // 5. Object — a nested collection of key-value pairs (covered next section).
  dimensions: {
    lengthCm: 30,
    widthCm: 12
  },

  // 6. Array — an ordered list of values (covered after objects).
  availableSizes: [7, 8, 9, 10, 11]
};

// Convert a JavaScript object to a JSON string — this is what gets sent over the wire.
const jsonString = JSON.stringify(validJsonValues, null, 2);
console.log(jsonString);

// Parse a JSON string back into a JavaScript object — this is what your API receives.
const parsedBack = JSON.parse(jsonString);
console.log(parsedBack.productName); // "Running Shoe"
console.log(typeof parsedBack.inStock); // "boolean" — not a string

// io.thecodeforge — JavaScript tutorial

// Real-world scenario: a checkout service returns this order confirmation
// payload to the frontend after a successful purchase.

const orderConfirmation = {
  "orderId": "ORD-2024-88421",
  "status": "confirmed",
  "totalAmountCents": 15498,
  "currency": "USD",

  // Nested object — customer info lives inside the order object.
  "customer": {
    "customerId": "USR-10042",
    "email": "alex.morgan@example.com",
    "loyaltyTier": "gold"
  },

  // Nested object with its own nested object — shipping details.
  "shippingAddress": {
    "street": "742 Evergreen Terrace",
    "city": "Springfield",
    "stateCode": "IL",
    "postalCode": "62701",
    // Nested geo coordinates for the delivery routing service.
    "geo": {
      "latitude": 39.7817,
      "longitude": -89.6501
    }
  },

  // Boolean flag the frontend uses to decide whether to show a gift message UI.
  "isGiftOrder": false,

  // Null means no promo was applied — explicitly stated, not just absent.
  "promoCode": null
  // ^^^ No trailing comma here. This is the last property. Add one and JSON.parse blows up.
};

// Access nested properties using dot notation after parsing.
const jsonPayload = JSON.stringify(orderConfirmation);
const parsed = JSON.parse(jsonPayload);

console.log(parsed.customer.email);              // "alex.morgan@example.com"
console.log(parsed.shippingAddress.geo.latitude); // 39.7817
console.log(parsed.promoCode);                   // null
console.log(parsed.promoCode === null);           // true — null is explicit, not undefined

// io.thecodeforge — JavaScript tutorial

// Real-world scenario: a product catalog API returns a page of results.
// This is the most common JSON shape you'll encounter — an array of objects.

const catalogPage = {
  "page": 1,
  "pageSize": 3,
  "totalResults": 1482,

  // Array of objects — each element is a complete product record.
  "products": [
    {
      "productId": "SKU-001",
      "name": "Trail Runner X9",
      "priceInCents": 12999,
      "categories": ["footwear", "outdoor", "running"], // Array inside an object inside an array.
      "available": true
    },
    {
      "productId": "SKU-002",
      "name": "Merino Wool Sock Pack",
      "priceInCents": 2499,
      "categories": ["footwear", "accessories"],
      "available": true
    },
    {
      "productId": "SKU-003",
      "name": "Compression Sleeve",
      "priceInCents": 1799,
      "categories": ["recovery"],
      "available": false
      // No trailing comma — this is the last property in the last object.
    }
    // No trailing comma after the last object in the array either.
  ]
};

const jsonString = JSON.stringify(catalogPage, null, 2);
const parsed = JSON.parse(jsonString);

// Iterate over the array of objects — the bread and butter of frontend development.
parsed.products.forEach((product, index) => {
  // Template literals for readable output — note the zero-based index.
  console.log(`[${index}] ${product.name} — $${(product.priceInCents / 100).toFixed(2)} — ${product.available ? 'In Stock' : 'Out of Stock'}`);
});

// Safely access a nested array inside an object inside an array.
console.log(parsed.products[0].categories[1]); // "outdoor" — zero-indexed all the way down

// io.thecodeforge — JavaScript tutorial

// Six real JSON mistakes with their exact error messages and fixes.
// Run each JSON.parse() call individually to see the error — they're isolated below.

// ─── MISTAKE 1: Trailing comma after the last property ───────────────────────
const trailingComma = '{"name": "Alice", "age": 30,}';
// SyntaxError: Unexpected token } in JSON at position 28
// Fix: Remove the comma after 30. JSON doesn't allow trailing commas. Ever.
try {
  JSON.parse(trailingComma);
} catch (e) {
  console.log('Mistake 1:', e.message);
}

// ─── MISTAKE 2: Single quotes instead of double quotes ───────────────────────
const singleQuotes = "{'name': 'Alice'}";
// SyntaxError: Unexpected token ' in JSON at position 1
// Fix: Replace all single quotes with double quotes.
try {
  JSON.parse(singleQuotes);
} catch (e) {
  console.log('Mistake 2:', e.message);
}

// ─── MISTAKE 3: Unquoted key ─────────────────────────────────────────────────
const unquotedKey = '{name: "Alice"}';
// SyntaxError: Unexpected token n in JSON at position 1
// Fix: Wrap the key in double quotes: {"name": "Alice"}
try {
  JSON.parse(unquotedKey);
} catch (e) {
  console.log('Mistake 3:', e.message);
}

// ─── MISTAKE 4: Comment inside JSON ──────────────────────────────────────────
const withComment = '{"name": "Alice" /* the admin user */}';
// SyntaxError: Unexpected token / in JSON at position 17
// Fix: JSON has no comment syntax. Strip all comments before parsing.
try {
  JSON.parse(withComment);
} catch (e) {
  console.log('Mistake 4:', e.message);
}

// ─── MISTAKE 5: undefined as a value ─────────────────────────────────────────
// undefined is a JavaScript concept — it doesn't exist in JSON.
// JSON.stringify() silently drops keys with undefined values.
const objectWithUndefined = {
  username: "alice",
  sessionToken: undefined // This key will vanish during serialisation.
};
const serialised = JSON.stringify(objectWithUndefined);
console.log('Mistake 5 — undefined silently dropped:', serialised);
// Output: {"username":"alice"} — sessionToken is GONE. No error. No warning.
// Fix: Use null for intentional absence. Use a default string like "" if the
// field must always be present.

// ─── MISTAKE 6: Type confusion — price as string instead of number ────────────
const orderA = JSON.parse('{"itemPriceCents": "1999"}'); // String — looks fine.
const orderB = JSON.parse('{"itemPriceCents": 499}');    // Number — correct.

// This is the silent killer. No parse error. Wrong result.
const wrongTotal = orderA.itemPriceCents + orderB.itemPriceCents;
console.log('Mistake 6 — string + number:', wrongTotal); // '1999499' — not 2498!

// Fix: Always validate and coerce types on ingestion.
const correctTotal = Number(orderA.itemPriceCents) + orderB.itemPriceCents;
console.log('Mistake 6 — fixed:', correctTotal); // 2498