JSON Best Practices

JSON is deceptively simple. Four data types, two structures, done. But the difference between good JSON and bad JSON can mean the difference between a smooth conversion and a debugging nightmare.

1. Use Consistent Naming Conventions

Pick a naming convention and stick with it. camelCase is the JavaScript standard, but snake_case works better for SQL conversions. Whatever you choose, be consistent.

{
  "firstName": "John",
  "last_name": "Doe",
  "EmailAddress": "john@example.com"
}

{
  "firstName": "John",
  "lastName": "Doe",
  "emailAddress": "john@example.com"
}

2. Use Proper Data Types

Don't stringify everything. Numbers should be numbers, booleans should be booleans. This enables proper type inference during conversion.

{
  "age": "25",
  "isActive": "true",
  "price": "19.99"
}

{
  "age": 25,
  "isActive": true,
  "price": 19.99
}

3. Use ISO 8601 for Dates

The converter automatically detects ISO 8601 dates and converts them to proper TIMESTAMP or DATETIME types. Using other formats means you'll get plain strings.

{
  "date": "01/07/2026",
  "time": "3:30 PM"
}

{
  "date": "2026-01-07",
  "datetime": "2026-01-07T15:30:00Z"
}

4. Use Arrays of Objects for Tabular Data

For data that will become rows in a spreadsheet or database, use arrays of objects with consistent keys. This is the ideal structure for CSV and SQL conversion.

[
  { "id": 1, "name": "Alice", "role": "Admin" },
  { "id": 2, "name": "Bob", "role": "User" },
  { "id": 3, "name": "Charlie", "role": "User" }
]

5. Name Your ID Fields Properly

Fields named 'id', ending in '_id', or ending in 'Id' are automatically recognized as identifiers. In GraphQL, they become ID types. In SQL, they become primary keys with auto-increment.

{
  "identifier": 1,
  "userRef": 42
}

{
  "id": 1,
  "userId": 42
}

6. Use null, Not Empty Strings

When a value is absent, use null instead of an empty string. This properly marks fields as nullable in TypeScript and SQL schemas.

{
  "middleName": "",
  "nickname": ""
}

{
  "middleName": null,
  "nickname": null
}

7. Avoid Deeply Nested Structures for CSV

CSV is inherently flat. The converter will flatten nested objects using dot notation (user.address.city), but deeply nested structures become unwieldy. For CSV exports, keep nesting to 2-3 levels max.

8. Validate Before Converting

Always ensure your JSON is valid before conversion. A missing comma or unclosed bracket will cause the entire conversion to fail. Use a JSON validator if you're manually editing.