1. Introducción
Una referencia cíclica (o circular) ocurre cuando un objeto directa o indirectamente contiene una referencia a otro objeto que acaba refiriéndose de nuevo al primero.
Ejemplo real
Hagamos un ejemplo práctico para nuestra librería de libros. Supongamos que tenemos la clase Book que tiene la propiedad Author, y la clase Author tiene la propiedad Books de tipo List<Book> para recordar todos sus libros.
public class Author
{
public string Name { get; set; }
public int BirthYear { get; set; }
public List<Book> Books { get; set; } = new List<Book>();
}
public class Book
{
public string Title { get; set; }
public Author Author { get; set; }
}
Ahora, si creamos un autor y un libro, establecemos las referencias, obtenemos un "círculo cerrado":
var author = new Author { Name = "Marcel Proust", BirthYear = 1871 };
var book = new Book { Title = "En busca del tiempo perdido", Author = author };
author.Books.Add(book);
// Listo, ahora author referencia a book, y book referencia a author!
¿Por qué es un problema?
Cuando serializas un objeto así a JSON, el serializador empieza a recorrer las propiedades. Ve que el autor tiene libros, dentro de los cuales otra vez está el autor... que otra vez contiene libros... que otra vez contienen autores... y así hasta el infinito.
author -> books[] -> author -> books[] ...
Es como mirarte en un espejo frente a otro espejo — los reflejos se repiten infinitamente. Pero en vez de reflejos bonitos obtienes un desbordamiento de pila (StackOverflowException).
2. ¿Cómo reacciona el serializador ante referencias cíclicas?
Error de serialización
Por defecto System.Text.Json no sabe manejar referencias cíclicas. Si intentas serializar esa estructura, obtendrás la excepción JsonException: "A possible object cycle was detected".
Ejemplo que provocará el error:
string json = JsonSerializer.Serialize(author); // ¡BUM! JsonException
Visualización:
graph TD;
Author --> Book;
Book --> Author;
3. ¿Cómo resolver el problema de referencias cíclicas?
Veamos varios enfoques reales, cada uno con sus pros y sus contras. Como habrás adivinado, no hay un "flag mágico" universal (qué pena).
Eliminar ciclos antes de serializar
Lo más simple: no mantener el ciclo. Antes de serializar, poner a null (o ignorar) las referencias que crean el ciclo.
Cómo se ve en la práctica:
// Temporalmente quitamos la referencia del autor a los libros
var authorToSerialize = new Author
{
Name = author.Name,
BirthYear = author.BirthYear,
Books = null // o puedes omitir la propiedad por completo
};
string json = JsonSerializer.Serialize(authorToSerialize);
// Ahora todo se serializa sin problemas!
Pros: simple, rápido, claro.
Contras: pierdes parte de los datos (al deserializar no tendrás las relaciones inversas).
Usar el atributo [JsonIgnore]
Puedes marcar la propiedad que participa en la referencia circular como ignorada:
public class Author
{
public string Name { get; set; }
public int BirthYear { get; set; }
[JsonIgnore]
public List<Book> Books { get; set; }
}
Ahora, al serializar al autor, sus libros no se incluirán. Es similar al enfoque anterior, pero declarativo y sin limpieza manual.
Pros: más sencillo, menos riesgo de olvidar limpiar la referencia.
Contras: la información sobre los libros del autor se pierde en el JSON.
Usar identificadores en lugar de objetos anidados
Si es importante conservar ambas direcciones de la relación (autor y libros), pero no quieres ciclos, usa identificadores únicos en lugar de objetos anidados:
public class Book
{
public string Title { get; set; }
public int AuthorId { get; set; } // en lugar de Author
}
public class Author
{
public int AuthorId { get; set; }
public string Name { get; set; }
// no guardamos los libros o guardamos la lista de sus Id
}
En el JSON ahora tendrás identificadores en vez de objetos completos. Es un enfoque común en bases de datos, REST API y sistemas con referencias unívocas.
Pros: no hay ciclos, JSON más compacto, las referencias se pueden reconstruir por Id.
Contras: rompe el modelo de objetos habitual, en la deserialización necesitas resolver por Id.
Mini-tabla comparativa:
| Enfoque | ¿Resuelve el problema del ciclo? | ¿Pérdida de datos? | Aplicabilidad |
|---|---|---|---|
| [JsonIgnore] | Sí | Sí | Cuando la anidación no es crítica |
| Eliminar referencia manualmente | Sí | Sí | Rápido antes de serializar |
| Almacenar Id en lugar del objeto | Sí | No* | REST, bases de datos, sistemas complejos |
* Los datos no se pierden, pero no están inmediatamente disponibles (hace falta resolución por Id).
4. ¿Cómo enseñar a System.Text.Json a serializar referencias cíclicas?
A partir de .NET 5, JsonSerializerOptions tiene un modo de referencias: options.ReferenceHandler = ReferenceHandler.Preserve.
Ese modo usa campos especiales $id y $ref para objetos repetidos.
Ejemplo
var options = new JsonSerializerOptions
{
WriteIndented = true,
ReferenceHandler = System.Text.Json.Serialization.ReferenceHandler.Preserve
};
string json = JsonSerializer.Serialize(author, options);
Console.WriteLine(json);
El JSON resultante se verá así:
{
"$id": "1",
"Name": "Marcel Proust",
"BirthYear": 1871,
"Books": {
"$id": "2",
"$values": [
{
"$id": "3",
"Title": "En busca del tiempo perdido",
"Author": {
"$ref": "1"
}
}
]
}
}
- $id — identificador único del objeto en el JSON
- $ref — referencia a un objeto ya serializado
Al deserializar todo se restaura correctamente (sin ciclos infinitos ni errores de pila).
Particularidades y limitaciones
- Ese JSON es extraño para frontend: la mayoría de clientes JS no entienden $id/$ref sin lógica adicional.
- El tamaño del JSON crece, y es más difícil de depurar a simple vista.
- Funciona solo si activas explícitamente ReferenceHandler.Preserve.
- No aplica a tipos-valor (no puede haber ciclos allí).
¿Cómo deserializar ese JSON?
Igual que uno normal, pero usa las mismas JsonSerializerOptions:
var deserializedAuthor = JsonSerializer.Deserialize<Author>(json, options);
5. ¿Y qué hay de Newtonsoft.Json (Json.NET)?
Históricamente Newtonsoft.Json supo manejar ciclos antes que System.Text.Json. Para ello existen el atributo [JsonObject(IsReference = true)] y ajustes globales de serialización.
Atributos para referencias
[JsonObject(IsReference = true)]
public class Author
{
public string Name { get; set; }
public List<Book> Books { get; set; }
}
[JsonObject(IsReference = true)]
public class Book
{
public string Title { get; set; }
public Author Author { get; set; }
}
Luego serializamos así:
var settings = new JsonSerializerSettings
{
PreserveReferencesHandling = PreserveReferencesHandling.Objects,
Formatting = Formatting.Indented
};
string json = JsonConvert.SerializeObject(author, settings);
Al final obtendrás JSON con $id y $ref, similar al modo ReferenceHandler.Preserve.
Conclusión rápida
- Si el intercambio es entre aplicaciones .NET — habilita la serialización por referencias (ReferenceHandler.Preserve o PreserveReferencesHandling).
- Si los datos van a JavaScript/u otros clientes — rompe los ciclos: [JsonIgnore], limpieza de referencias o pasar a Id.
6. Cómo evitar errores y dolores de cabeza
Muy a menudo los principiantes (y hasta los experimentados) se topan con caídas del serializador por ciclos. Recuerda: si colecciones/propiedades se refieren entre sí — revisa la arquitectura del modelo.
No dudes en usar [JsonIgnore] para propiedades que no son necesarias para el intercambio externo.
La trampa clásica es serializar relaciones "muchos a muchos" (por ejemplo, estudiantes ↔ cursos). Sin romper los ciclos o sin serialización por referencias esto no funciona.
En REST API lo habitual es enviar el objeto "en una dirección": por ejemplo, el libro conoce al autor, y el autor solo conoce el Id de los libros (o directamente no conoce sus libros en ese contrato).
GO TO FULL VERSION