Validación de Nullables y Listas en GradQL

GraphQL permite definir tipos escalares como string o int, pero por defecto acepta valores nulos en cualquier campo. Si quieres construir APIs robustas, necesitas aprender a usar el operador non-null y manejar listas con validación estricta. Esta guía está pensada para developers que ya entienden los tipos básicos y quieren reforzar la seguridad de sus schemas.

¿Por qué GraphQL permite valores null por defecto?

Cuando defines una query que retorna un string o un int, GraphQL acepta sin problema que devuelvas null. Es parte del comportamiento estándar del sistema de tipos.

Imagina una query hello que devuelve un string. Si tu resolver retorna null, el playground no lanza error. Lo mismo pasa con getInt: aunque el tipo sea entero, puedes enviar y recibir null sin que el sistema reclame.

Y aquí viene lo interesante: ese permiso por defecto puede romper tu frontend si esperas siempre un valor. Por eso existe la sintaxis para marcar campos como obligatorios.

¿Qué significa non-null en GraphQL? Es una validación que obliga a que un campo nunca sea null, ni en la respuesta del servidor ni en los argumentos enviados desde el cliente. Se marca con un signo de exclamación al final del tipo.

¿Cómo aplicar non-null con el signo de exclamación?

Para prohibir valores nulos, agrega un ! después del tipo en tu definición. Esa pequeña marca convierte al campo en obligatorio [2:00].

Si defines hello: String!, tu resolver ya no puede devolver null. Y si defines getInt(age: Int!): Int!, tampoco puedes pasar un argumento nulo desde el cliente. El playground responderá con un error claro indicando qué campo violó la regla.

graphql type Query { hello: String! getInt(age: Int!): Int! }

Cuando intentas enviar null donde se espera un valor obligatorio, GraphQL detiene la ejecución antes de llegar al resolver. Esa validación temprana es la que hace que tu API sea predecible.

¿Cómo se definen listas en GraphQL?

Las listas se declaran encerrando el tipo entre corchetes. Es la forma estándar de decirle al schema que esperas múltiples valores del mismo tipo [3:30].

Por ejemplo, [String] representa una lista de strings y [Int] una lista de enteros. Puedes usarla tanto en argumentos como en valores de retorno.

Un resolver llamado getNumbers ilustra el caso típico:

graphql type Query { getNumbers(numbers: [Int]): [Int] }

Este resolver recibe un array de enteros y devuelve ese mismo array. Si intentas pasar un string dentro de la lista, GraphQL lo rechaza porque viola el tipo declarado.

¿Qué casos permite una lista sin restricciones?

Una lista declarada como [Int] acepta cuatro escenarios diferentes, y conviene tenerlos claros antes de aplicar restricciones.

• Un array con valores enteros, como [1, 2, 3].
• Un array vacío [].
• Un valor null directo en lugar del array.
• Un array que contiene null entre sus elementos, como [1, null, 3].

Los cuatro casos pasan la validación. Si tu lógica de negocio no tolera alguno de estos escenarios, necesitas combinar el operador non-null con las listas.

¿Dónde se coloca el signo de exclamación en una lista? Puede ir fuera de los corchetes, dentro, o en ambos lugares. Cada posición controla un tipo diferente de validación: el valor completo, los elementos internos, o los dos a la vez.

¿Cómo combinar non-null con listas en GraphQL?

La posición del ! cambia completamente el comportamiento de la validación. Es uno de los detalles más confusos al empezar, pero la lógica es consistente.

Exclamación externa: [Int]!

Con [Int]! impides que el array completo sea null, pero permites que existan null entre sus elementos [6:30].

• Pasar [1, 2, 3] funciona.
• Pasar [] funciona.
• Pasar null directo falla.
• Pasar [1, null, 3] funciona.

Exclamación interna: [Int!]

Con [Int!] permites que el array completo sea null, pero prohíbes valores null dentro de la lista.

Exclamación doble: [Int!]!

Con [Int!]! aplicas ambas reglas a la vez. Ni el array puede ser null, ni sus elementos internos.

• Pasar [1, 2, 3] funciona.
• Pasar [] funciona.
• Pasar null falla.
• Pasar [1, null, 3] falla.

Esta combinación doble es la más estricta y la que usarás cuando necesites garantizar integridad total en los datos. El array vacío sigue siendo válido porque no contiene elementos null, simplemente no contiene nada.

¿Qué sigue después de dominar non-null y listas?

Con estas dos herramientas ya puedes construir schemas mucho más seguros y expresivos. El siguiente paso es crear tus propios tipos de datos y trabajar con objetos personalizados, donde la complejidad aumenta y las validaciones se vuelven aún más relevantes.

¿Qué combinación de non-null y listas usarías en tu próxima API? Cuéntame en los comentarios cómo planeas aplicarlo.