Xcode 27.2 Introduces an Agent- and Merge-Friendly JSON Format for Project Configuration

Apple is introducing a new JSON-based format for Xcode project configuration files, replacing the traditional property-list-based format. Available in Xcode 27.2, the new format aims to improve readability, simplify maintenance, and make project configuration easier for AI coding agents to understand and modify.

The open source JSON file format (xcode-project-format) makes verifying project configuration changes easier when committing the project configuration file to your source code repository because changes in the comparison view correspond to your actions in Xcode.

A major advantage of the new format is that it reduces the likelihood of merge conflicts by providing a more stable and predictable representation of project configuration. The JSON format also makes the project structure more accessible to automated development tools, including AI coding agents, simplifying the inspection and modification of project settings.

To help developers work with the new format, Apple has also released a Swift package for encoding and decoding the new format. For example, this is how you list all targets defined in a 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)
}
}

At the top-level, JSON schema defines not only targets but also the file tree, build configurations, build settings, and external dependencies. It also supports relationships between nodes in different subtrees. For example, a file specifies the build phases and targets it belongs to. Importantly, the formats avoid opaque identifiers wherever possible, favoring human-readable names and paths instead. Targets and build products are notable exceptions, as they use identifiers to support references from external files.

Commenting the announcement, senior iOS developer Nikita Dyachkov notes that

The issue of merging project files has been a long-standing problem since project files were introduced and was familiar to anyone who's worked in an iOS development team with more than one developer.

In the same thread, senior iOS engineer Khushal Jhalani described the new, more readable format as a "huge quality-of-life improvement". Others echoed the sentiment that the change was long overdue, with senior iOS developer Moumita China remarking that it could have saved "years of merge conflicts".

Existing projects can be migrated easily, as the new format changes only how the project is represented on disk, not its underlying model. Converting a project replaces the traditional project.pbxproj file with project.xcproj. Before migrating, however, ensure that any tools you are using, including fastlane, CocoaPods, Tuist, and others, support the new format.