xcproj JSON de Xcode: el nuevo formato de proyecto en Xcode 27.2

Todo proyecto de Xcode tiene un archivo que casi nadie lee a propósito: project.pbxproj. Es de donde salen los conflictos de merge cuando dos personas añaden archivos en ramas distintas. Xcode 27.2 lo sustituye. El formato xcproj JSON de Xcode, un archivo llamado project.xcproj, guarda la misma configuración del proyecto como JSON jerárquico con el que las personas, las herramientas de diff y los agentes de programación pueden trabajar de verdad.

Esta guía explica qué es el nuevo archivo, por qué lo cambió Apple, qué aspecto tiene, cómo convertir un proyecto y qué comprobar antes de cambiar: versiones anteriores de Xcode, CI y herramientas de terceros. Se basa en la documentación y las notas de la versión de Apple, en el paquete de código abierto de Apple para el formato y en artículos de @sarunw y Artem Novichkov. El formato es nuevo en Xcode 27.2, y los detalles pueden cambiar entre versiones.

¿Qué es el nuevo formato .xcproj en JSON de Xcode 27.2?

Un .xcodeproj es una carpeta. Dentro está el archivo de configuración del proyecto, junto con otros archivos como los esquemas compartidos. El artículo de Apple Updating your Xcode project configuration file format explica el cambio: en versiones anteriores ese archivo es una property list con la extensión .pbxproj, y en Xcode 27.2 y posteriores el formato predeterminado es «un archivo JSON más pequeño, jerárquico y autodescriptivo con la extensión .xcproj».

Tres hechos enmarcan todo lo demás:

• Los proyectos nuevos usan JSON por defecto. Los proyectos que creas en Xcode 27.2 y posteriores usan project.xcproj.
• Los proyectos existentes no cambian solos. Xcode 27 y posteriores admiten ambos formatos, y tú eliges cuándo cambiar.
• El formato es de código abierto. Apple lo publica como xcode-project-format, un paquete de Swift que modela el archivo como valores con tipo.

Las notas de la versión de Xcode 27.2 lo resumen en una línea: el formato basado en JSON es «más legible, más fácil de fusionar y más fácil de editar para los agentes de programación». Como dijo @sarunw cuando llegó la 27.2, Xcode 27.2 sustituye .pbxproj por un nuevo formato .xcproj en JSON.

¿Por qué sustituye Apple project.pbxproj?

El formato antiguo guarda el proyecto como una lista plana de objetos, cada uno identificado por un ID hexadecimal opaco de 24 caracteres. Los objetos se referencian entre sí mediante esos ID. Añadir un archivo Swift a un target suele tocar varias secciones a la vez: una referencia de archivo, su lugar en un grupo, una entrada de build file y la fase de compilación Sources del target. @sarunw describe el resultado conocido como un cambio «reescrito en tres secciones de project.pbxproj». Cuando dos ramas añaden un archivo cada una, esas ediciones dispersas chocan, y resolverlas a mano implica emparejar ID entre secciones.

Los ajustes de compilación tenían un problema parecido. Cada configuración, como Debug y Release, tenía su propio bloque completo de ajustes, así que un mismo ajuste podía aparecer en varios sitios con valores distintos.

La documentación de Apple da tres razones para el nuevo formato:

1. Diffs fáciles de revisar. Los cambios en la vista de comparación corresponden a tus acciones en Xcode.
2. Menos conflictos de merge. El formato JSON aísla los cambios de configuración, así que es menos probable que ediciones sin relación toquen las mismas líneas.
3. Pensado para agentes. A los agentes de programación les resulta más fácil editar el archivo por ti.

Las carpetas sincronizadas de Xcode 16 ya eliminaron las entradas por archivo para los archivos de esas carpetas. El artículo de @sarunw señala que el formato JSON va más allá, porque los targets, las fases de compilación, las configuraciones y las referencias a paquetes seguían usando ID en la property list.

¿Qué aspecto tiene un archivo project.xcproj?

Apple no publica un archivo de ejemplo completo en su documentación, pero su paquete de código abierto define las claves de nivel superior. Entre ellas están default-configuration, configurations, localizations, files, targets, packages y build-settings. Este es un extracto recortado que usa esas claves, con valores del proyecto de demostración de @sarunw. No es un archivo completo.

{
  "default-configuration": "Debug",
  "build-settings": {
    "DEBUG_INFORMATION_FORMAT[config=Debug]": "dwarf",
    "DEBUG_INFORMATION_FORMAT[config=Release]": "dwarf-with-dsym"
  }
}

Un ajuste de compilación se escribe una sola vez. Cuando las configuraciones necesitan valores distintos, la condición va en la clave, como [config=Debug] en el ejemplo. Los archivos son entradas del árbol files, y cada uno lleva su propia pertenencia a targets en lugar de estar referenciado desde una lista de fase de compilación aparte. En el ejemplo de @sarunw, un archivo ocupa una sola línea:

{ "path": "CatalogView.swift", "target-membership": [ "ToolbarPlacements/compile-sources" ] }

La diferencia de tamaño se nota. En el proyecto de demostración de @sarunw, una property list de 300 líneas se convirtió en 123 líneas de JSON. La comparación de Artem Novichkov mostró que añadir el mismo paquete de Swift ocupaba 24 líneas en cinco sitios en project.pbxproj y 12 líneas en dos sitios en project.xcproj. Los resultados variarán según tu proyecto, pero la tendencia es constante.

¿Cómo convierto un proyecto de Xcode a xcproj en JSON?

Haz commit de tu trabajo primero, para que la conversión sea un cambio limpio y separado. Después, en Xcode 27.2:

1. Selecciona el proyecto en la parte superior del navegador de proyectos.
2. Abre el inspector de archivos.
3. Bajo Project Document, elige JSON en el menú desplegable Project Format.
4. Si aparece un cuadro de diálogo, haz clic en Continue.

Dentro de la carpeta .xcodeproj, se elimina project.pbxproj y se añade project.xcproj. Apple señala que, si usas control de versiones, puedes deshacer el cambio descartando esos dos cambios de archivo. Los esquemas y los demás archivos del paquete no forman parte del cambio.

Para scripts y repositorios grandes, Artem Novichkov informa de que xcodebuild en Xcode 27.2 puede convertir en ambas direcciones. También comprobó que el archivo convertido sustituye al original, otra razón para hacer commit antes. Consulta xcodebuild -help en tu equipo, ya que esto no aparece en el artículo de Apple.

xcodebuild -project Weather.xcodeproj -convert-project xcproj
xcodebuild -project Weather.xcodeproj -convert-project pbxproj

¿Qué versiones de Xcode y qué herramientas pueden leer .xcproj?

La documentación de Apple dice que el formato .xcproj es compatible con Xcode 27 y posteriores, y las notas de la versión indican que los proyectos que lo usan también se abren en versiones anteriores de Xcode 27. Así que un equipo con Xcode 27.0 o 27.1 puede abrir un proyecto convertido, pero la opción de conversión está en la 27.2. Quien use Xcode 26 o anterior necesita el formato de property list, que según el artículo de @sarunw sigue siendo la opción para versiones antiguas de Xcode.

La compatibilidad de terceros todavía está llegando. La biblioteca XcodeProj de Tuist, sobre la que se construyen muchas herramientas, añadió «[Experimental] support Xcode 27.2's JSON project format (project.xcproj)» en su versión 9.17.0. No hemos podido confirmar la compatibilidad en XcodeGen ni en la gema xcodeproj de CocoaPods, así que considera no compatible cualquier herramienta que edite project.pbxproj hasta que sus propias notas de la versión digan lo contrario. Si generas tu proyecto a partir de una especificación y no haces commit de él, el formato importa menos, siempre que el generador siga funcionando.

El paquete de Apple es el mejor camino para tus propias herramientas. Requiere Swift 6.1 o posterior, compila en macOS 14 y posteriores y en otras plataformas, y tiene licencia Apache 2.0 con Runtime Library Exception. Su README muestra cómo leer un proyecto con XCSchema.Project:

import XcodeProjectFormat

func listTargets(in projectURL: URL) throws {
    let projectData = try Data(contentsOf: projectURL)
    let project = try XCSchema.Project(jsonRepresentation: projectData)
    for target in project.targets {
        print(target.name)
    }
}

¿Cómo ayuda xcproj a los agentes de programación y al CI?

El resumen de @sarunw es que el formato JSON es más legible para las personas y más fácil de editar para los agentes de programación, lo que coincide con las palabras de la propia Apple. Un agente que añade un archivo o un paquete a una property list tiene que inventar ID válidos y actualizar todas las secciones que los referencian. Con JSON, la edición es un cambio pequeño y local que puedes revisar en una pull request.

El paquete de Apple también incluye xcprojformatter, una herramienta de línea de comandos construida sobre la biblioteca. Artem Novichkov describe cómo ejecutarla con xcrun xcprojformatter: imprime el archivo en una forma canónica, y --update lo reescribe en su sitio. Eso la convierte en una comprobación útil para el CI, porque un diff del formateador muestra cualquier edición manual o de un agente que no esté en forma canónica. Consulta xcrun xcprojformatter --help para ver los argumentos exactos que acepta tu versión.

xcrun xcprojformatter --update MyApp.xcodeproj/project.xcproj
git diff --exit-code -- MyApp.xcodeproj/project.xcproj

También comprobó que el formateador descarta sin avisar las claves que no reconoce, como una clave mal escrita, así que revisa lo que cambia en lugar de dar por hecho que lo valida todo. Lo mismo vale tras un conflicto de merge: resuelve el JSON, ejecuta el formateador y comprueba en Xcode que los targets y los paquetes siguen bien.

¿Importa el formato de proyecto JSON para las apps de iPhone Duo?

No para el funcionamiento de tu app. El formato de proyecto solo cambia cómo guarda Xcode tu configuración; la app que compilas para iPhone o iPhone Duo es la misma. Sí importa para el trabajo que la rodea. Adaptar una app para iPhone Duo implica volver a compilar con el SDK de iOS 27.1 y, a menudo, tocar ajustes del proyecto en varias ramas, que es justo cuando aparecen los conflictos de merge en project.pbxproj.

También encaja bien con las agent skills integradas en Xcode 27, que cubren buenas prácticas actuales y API nuevas. Como señala @sarunw, la antigua skill uikit-app-modernization ahora es app-resizability y añade compatibilidad con iPhone Duo. Si dejas que un agente te ayude con ese trabajo, un archivo de proyecto en JSON mantiene sus cambios lo bastante pequeños para revisarlos. Nuestra guía sobre cómo exportar las agent skills de Xcode 27 cubre esa parte, y la checklist para preparar tu app para iPhone Duo enumera los cambios en la propia app.

Puntos clave

• Xcode 27.2 sustituye project.pbxproj por project.xcproj, un archivo JSON más pequeño y jerárquico, por defecto en los proyectos nuevos.
• El formato JSON hace que los diffs reflejen tus acciones, aísla los cambios para reducir los conflictos de merge y es más fácil de editar para los agentes de programación.
• Convierte los proyectos existentes en el inspector de archivos, bajo Project Document; haz commit antes para poder deshacerlo.
• .xcproj se abre en Xcode 27 y posteriores. Mantén la property list si alguien, o alguna máquina de CI, usa Xcode 26.
• Revisa los generadores, scripts y gestores de dependencias que analizan project.pbxproj antes de cambiar; el paquete de código abierto de Apple y xcprojformatter te ayudan con tus propias herramientas.

Cuando tu proyecto esté en orden, ponlo a trabajar en el dispositivo: empieza por la checklist para preparar tu app para iPhone Duo y descubre lo que otros desarrolladores ya han publicado en Built for the fold.