Fundamentos de la sintaxis y la estructura JSON

1. Recordando JSON

JSON significa JavaScript Object Notation. A pesar de la palabra JavaScript en el nombre, este formato es completamente agnóstico al lenguaje y amigable con todos (bueno, casi todos) los lenguajes de programación, incluido C#. Se inventó para describir datos de forma clara y práctica — objetos, arrays, listas y diccionarios — usando texto plano.

En el mundo actual, donde casi cada programa se comunica con otros, JSON se ha convertido de facto en el estándar para serializar e intercambiar datos estructurados. Se usa por todas partes: desde REST API hasta almacenamiento de configuraciones de usuario e incluso para comunicación interna entre microservicios. Y hay una buena razón — es legible por humanos (si no temen a las llaves), fácil de parsear y está soportado por todos los lenguajes modernos y bibliotecas.

¿Por qué no XML?

JSON es más sencillo, más corto y más legible que XML. Además, tiene menos ruido y etiquetas y encaja de forma más lógica con las estructuras de datos de la mayoría de los lenguajes. Y no necesitas pelear con etiquetas de cierre, comillas y otra burocracia XML. En resumen — JSON va de más rápido, más simple, más cómodo.

2. Elementos básicos de la sintaxis JSON

Imagina que JSON es un árbol simple (o una matrioshka), formado por objetos, arrays y datos primitivos. Estos son los "ladrillos" que tenemos:

Objetos (Objects)

Un objeto JSON es un conjunto de pares «clave: valor», rodeado por llaves { }.

Ejemplo:

{
  "name": "Alice",
  "age": 23
}

En C# esa estructura se puede representar como una clase o un diccionario.

Arrays (Arrays)

Un array JSON es una lista ordenada de elementos (valores de cualquier tipo), encerrada entre corchetes [ ].

Ejemplo:

[1, 2, 3, 42]

O así:

[
  {"name": "Ivan"},
  {"name": "Olga"}
]

En C# — esto corresponde a List<T>, T[] y colecciones similares.

Pares «clave-valor»

Las claves siempre son strings (¡entre comillas dobles!), y los valores pueden ser de cualquiera de los tipos permitidos en JSON.

Ejemplo:

{
  "id": 123,
  "login": "student",
  "isActive": true
}

Tipos de datos en JSON

10, -5, 3.14

"hello"

true, false

null

{"a":1}

[1,2,3]

Ejemplo — todo junto:

{
  "id": 1,
  "name": "Bob",
  "scores": [10, 20, 30],
  "profile": {
    "email": "bob@mail.com",
    "phone": null
  },
  "isAdmin": false
}

Mira cómo de forma compacta y lógica se puede describir todo un objeto de usuario.

3. Reglas de formato de JSON

Las cadenas siempre con comillas dobles

Aunque tengas ganas de usar comillas simples, JSON no lo permite. Así está bien:

{ "name": "Vera" }

Así — error:

{ 'name': 'Vera' }

Las claves — solo strings

A diferencia de C#, donde la clave de un diccionario puede ser int o incluso enum, en JSON la clave es siempre una cadena:

{ "2025": "Year of C#", "favorite": true }

No hay comas finales

A diferencia de algunas construcciones en C#, una coma extra antes de la llave de cierre es un error de sintaxis en JSON.

// ¡ERROR! (no se permite la coma final)
{
  "id": 10,
  "name": "Oleg",
}

Correcto:

{
  "id": 10,
  "name": "Oleg"
}

Espacios y saltos de línea

Puedes usarlos para que sea bonito; los parsers los ignoran. Normalmente para formato "para humanos" se usa JSON pretty-printed (formateado), para enviar por la red — minified (en una línea, sin espacios).

4. Cómo se convierten los objetos C# a JSON

Si serializas un objeto con System.Text.Json.JsonSerializer.Serialize(), los campos y propiedades del objeto se convierten en pares «clave-valor».

Ejemplo de clase C# y serialización

public class Book
{
    public string Title { get; set; }
    public int Pages { get; set; }
}
var book = new Book { Title = "CLR via C#", Pages = 900 };
string json = JsonSerializer.Serialize(book);
Console.WriteLine(json); // {"Title":"CLR via C#","Pages":900}

Colecciones

• List<int> se convierte en [1,2,3]
• string[] se convierte en ["hi", "wow"]
• List<Person> — en un array de objetos

Diccionarios

Un diccionario del tipo Dictionary<string, int> se convierte en un objeto:

var dict = new Dictionary<string, int>
{
    ["apples"] = 5, ["bananas"] = 10
};
string json = JsonSerializer.Serialize(dict);
// {"apples":5,"bananas":10}

5. Esquema visual: cómo se construye JSON

Anidamiento — como una matrioshka

Objeto
│
├── Par: "name": "Alex"
├── Par: "hobbies": array
│               │
│               ├── "skiing"
│               └── "programming"
└── Par: "profile": objeto
                 │
                 ├── "age": 42
                 └── "city": "Basel"

Como resultado:

{
  "name": "Alex",
  "hobbies": ["skiing", "programming"],
  "profile": {
    "age": 42,
    "city": "Basel"
  }
}

6. Errores típicos y particularidades de la sintaxis

En programación no existe un mundo perfecto — ¡incluso en JSON hay trampas! Si intentas enviar JSON con comillas incorrectas, comas extra o claves sin comillas — el parser lanzará un error.

Otra "trampa" son los números con ceros a la izquierda. En JSON eso está prohibido (por ejemplo, 0123 — es un error).

Bueno saber: Algunos parsers (por ejemplo, el JavaScript JSON.parse) son más permisivos y pueden "perdonar" pequeñas infracciones. Pero la mayoría de los parsers estrictos (por ejemplo, en C# y .NET) se quejarán ante la mínima violación de sintaxis.

7. Ejemplos de conversión de datos C# a JSON

Vamos a serializar una estructura más compleja en la práctica. Nuestra app de estudio evoluciona: supongamos que ahora tenemos una lista de estudiantes y queremos guardarla en un archivo JSON.

Definimos la clase:

public class Student
{
    public string Name { get; set; }
    public int Age { get; set; }
}

Rellenamos la lista:

var students = new List<Student>
{
    new Student { Name = "Anna", Age = 20 },
    new Student { Name = "Nikita", Age = 22 }
};

Serialización:

using System.Text.Json;

// Serializamos la lista de estudiantes a una cadena JSON
string json = JsonSerializer.Serialize(students, new JsonSerializerOptions { WriteIndented = true });
Console.WriteLine(json);

/*
[
  {
    "Name": "Anna",
    "Age": 20
  },
  {
    "Name": "Nikita",
    "Age": 22
  }
]
*/

¿Ves qué cómodo? Cada estudiante es un objeto dentro del array JSON.

8. Mini-generador: cómo escribir JSON "a mano"

A veces toca escribir JSON a mano, por ejemplo para crear datos de prueba. Aquí tienes una lista de verificación:

1. Llaves externas — para un objeto, corchetes externos — para un array.
2. La clave siempre es una cadena entre comillas dobles.
3. Los valores — cadenas (entre comillas dobles), números, true, false, null, objeto ({}), array ([]).
4. Solo comas entre elementos, ¡nunca después del último!
5. Indentación y espacios para legibilidad (pero no obligatorios).