JSON de introspección

GraphQL SDL

¿Qué es el conversor de JSON de introspección a SDL?

Cuando obtienes un esquema desde Apollo Studio, Postman, Insomnia, o ejecutas get-graphql-schema contra un endpoint en vivo, lo que recibes no es el SDL amigable que escribiste — es el resultado de query { __schema { ... } }: más de 600 líneas de JSON anidado describiendo cada tipo, cada campo y cada modificador en un árbol de objetos kind / name / ofType. Útil para una herramienta, ilegible para una persona. Este conversor toma ese JSON y lo imprime de vuelta como el SDL que realmente subirías a un repositorio, siguiendo las reglas de introspección de la spec de GraphQL de octubre de 2021.

Todo ocurre en tu navegador — no se sube nada, no hay IA, ningún esquema se envía a ningún sitio. La lógica de conversión refleja lo que graphql-js hace internamente con buildClientSchema y printSchema: recorrer el árbol __schema, omitir los tipos exclusivos de introspección (__Schema, __Type, __Field, …) y los escalares incorporados, y emitir cada definición restante con su descripción, campos, argumentos, valores por defecto y razones de deprecación intactos. Tanto si pegas el sobre completo { "data": { "__schema": ... } }, solo { "__schema": ... }, o incluso el valor de __schema directamente, la página gestiona los tres casos.

La salida agrupa primero los escalares, luego los enums, interfaces, uniones, tipos de entrada y, por último, los tipos objeto — alfabético dentro de cada grupo, con indentación de dos espacios y una línea en blanco entre definiciones. Lo bastante idempotente como para soltarlo directamente en un archivo <code>.graphql</code> de tu repo.

Cómo usar el conversor

Tres pasos. Los botones de abajo son los botones reales de esta página.

Pega, sube o carga un ejemplo

Pega tu JSON de introspección en el panel Entrada de la izquierda — la conversión sucede automáticamente una fracción de segundo después de que dejes de teclear, así que no hay ningún botón Convertir que buscar. Pulsa Subir para un archivo .json exportado desde Apollo Studio o Postman, o pulsa Ejemplo para cargar un resultado de introspección realista de Order/Customer/Money. Un pegado típico empieza así:

{
  "data": {
    "__schema": {
      "queryType": { "name": "Query" },
      "types": [
        { "kind": "OBJECT", "name": "Order", "fields": [...] },
        ...
      ]
    }
  }
}

También puedes pegar el valor interno { "__schema": ... } o el objeto __schema directamente — la página prueba las tres formas. Herramientas como get-graphql-schema y el endpoint de introspección de Apollo Server producen una de estas formas por defecto.

Lee la salida SDL

El panel Salida de la derecha renderiza el esquema como SDL. Cada tipo aparece en su propia definición con indentación de dos espacios, los campos uno por línea, las descripciones se mantienen encima del tipo o campo como cadenas de bloque entre triple comilla, y las razones de deprecación se renderizan como @deprecated(reason: "..."). Los escalares incorporados y los tipos de introspección __ se filtran — lo que obtienes es exactamente el esquema que publica tu servidor, tal y como recomienda documentar la spec de GraphQL de Relay. Si el JSON está mal formado o le falta el campo __schema, recibes un mensaje en línea claro en lugar de una traza de pila.

Copia o descarga

Pulsa Copiar para llevarte el SDL a una descripción de PR, un documento o un chat. Pulsa Descargar para guardarlo como schema.graphql — déjalo caer directo en tu repo. El botón de limpiar del panel de entrada te devuelve a un estado en blanco. La conversión es totalmente del lado cliente; el resultado de introspección no abandona la página.

Cuándo lo usarías de verdad

Capturar un esquema desde un endpoint en vivo

Heredas un servicio GraphQL que no tiene archivo de esquema en el repo — solo el servidor en marcha. Lanza una consulta de introspección, pega el JSON aquí y tienes un schema.graphql inicial commiteado en cinco minutos. Más fácil que cablear buildClientSchema y printSchema de graphql-js solo para hacerlo una vez.

Leer una exportación de Apollo Studio o Postman

La exportación de esquema de Apollo Studio es el JSON de introspección. Lo mismo con el botón "Save schema" de Postman en una request GraphQL. Conviértelo aquí y podrás de verdad ojear el esquema en un editor de código en lugar de entrecerrar los ojos mirando JSON.

Comparar dos snapshots de un esquema en vivo

Lanza introspección contra staging y producción, convierte cada uno a SDL, y haz diff entre los dos archivos. Detectar un campo que falta o un valor de enum renombrado es trivial en SDL y básicamente imposible en JSON de introspección crudo.

Generar stubs de tipos de un servicio que no es tuyo

¿Necesitas tipos TypeScript o React hooks para una API GraphQL de terceros? La mayoría de generadores de código quieren SDL, no JSON de introspección. Conviértelo aquí y luego mete el SDL en tu pipeline de codegen — graphql-react, graphql-codegen, o lo que use tu stack.

Preguntas habituales

¿Necesita el sobre completo { "data": { "__schema": ... } }?

No. La página acepta tres formas: el sobre completo de respuesta GraphQL, solo { "__schema": ... }, o incluso el objeto __schema directamente. Sea cual sea la que pegues, encuentra la raíz __schema y trabaja desde ahí.

¿Y si mi JSON no tiene el campo __schema?

Recibes un mensaje claro: "Expected an introspection result. Couldn't find __schema field. Paste the JSON returned by the GraphQL introspection query." Sin crash, sin traza de pila.

¿Se conservan las descripciones y razones de deprecación?

Sí. Las descripciones de tipos y campos se emiten como cadenas de bloque con triple comilla encima de la definición. Los campos y valores de enum deprecados llevan @deprecated(reason: "...") en la misma línea. Esto coincide con la salida de printSchema de graphql-js.

¿Qué pasa con los escalares incorporados y los tipos de introspección __?

Se filtran. String, Int, Float, Boolean e ID son implícitos en SDL — solo aparecen en tipos de campo, no como definiciones de nivel superior. Lo mismo para __Schema, __Type, __Field y el resto de meta-tipos de introspección.

¿Está garantizado que la salida vuelva exactamente al mismo resultado de introspección?

Semánticamente, sí — el SDL describe el mismo esquema. Byte por byte, no, porque el orden de los tipos y campos puede diferir de tu archivo fuente original. La salida está alfabetizada dentro de cada grupo de definiciones para diffs estables.

¿Se envía mi resultado de introspección a un servidor?

No. La conversión se ejecuta enteramente en tu navegador. No se sube nada, no se registra nada. Es seguro pegar esquemas de servicios internos o sin lanzar.

Otras herramientas GraphQL

Una vez que tengas el SDL, estas se ocupan del resto:

JSON de introspección a GraphQL SDL