Why it is worth attention

Apple does not publish the icon.json schema as a public API, so this community-driven, empirical reference fills a critical gap for developers working with Icon Composer files.

Who it is for

Developers creating tools to generate or inspect app icons
macOS/iOS developers integrating Icon Composer into their workflows
QA engineers verifying icon file compatibility across systems

Use cases

Parse and validate existing .icon packages for migration or testing
Generate new .icon packages programmatically for automated app icon creation
Edit composition attributes such as fills, gradients, layers, and appearance specializations

Strengths

Open string-backed values allow decoding of future blend modes, appearances, and platforms without waiting for package updates
Retains original color spaces and precision via IconColor instead of converting to platform-specific types
Supports complex specializations and multiple JSON representations (e.g., blur vs blur-material) based on real-world files

Considerations

Schema is empirical and may not cover all Icon Composer versions or edge cases
Unknown attributes are stored as JSONValue, requiring manual mapping for fully lossless round-trips
Future Icon Composer updates may introduce new attributes that need package updates to avoid data loss

README quick start

IconComposerModel

IconComposerModel is a Swift package and a living reference for the contents of Apple Icon Composer's icon.json file. It is intended for apps and tools that need to inspect, generate, or modify .icon packages.

[!IMPORTANT] Apple documents how to use Icon Composer, but does not currently publish the icon.json schema as a public API. This reference is empirical. It will be updated from real files produced by different Icon Composer versions.

Add the package

Add this repository as a Swift Package dependency, then import the library:

import IconComposerModel

let iconJSON = iconPackageURL.appending(path: "icon.json")
let icon = try IconComposerIcon.decode(contentsOf: iconJSON)

print(icon.groups.count)
print(icon.groups.flatMap(\.layers).map(\.name))

To encode a modified model:

let data = try icon.encoded()
try data.write(to: iconJSON, options: .atomic)

The package uses open, string-backed values for evolving options such as blend modes and appearances. A newer value can therefore be decoded without waiting for a package update.

Package layout

A saved .icon file is a package (a directory presented as one file in Finder):

AppIcon.icon/
├── icon.json
└── Assets/
    ├── Background.svg
    └── Symbol.png

icon.json describes composition and rendering. The Assets directory contains the SVG or bitmap artwork named by image-name.

Attribute reference

Unless noted otherwise, attributes are optional. Icon Composer commonly omits a property when it has its default value.

Top-level icon

JSON attribute	Swift property	Meaning
`fill`	`fill`	Background fill used when no appearance-specific fill overrides it.
`fill-specializations`	`fillSpecializations`	Background fills for particular appearances.
`color-space-for-untagged-svg-colors`	`colorSpaceForUntaggedSVGColors`	Interprets colors in imported SVGs that have no embedded color-space tag. Observed values: `srgb`, `display-p3`.
`groups`	`groups`	Ordered collection of Liquid Glass groups that make up the icon.
`supported-platforms`	`supportedPlatforms`	Declares which enclosure families/platforms the design supports.

Fill

A fill is normally an object with one of these attributes:

JSON form	Meaning
`{"solid": ""}`	One flat co

Related repositories

Similar projects matched by category, topics, and programming language.

Blaizzy

Featured

nativ

Nativ is a native macOS app that lets you run AI models locally on Apple silicon, offering chat, model management, performance analytics, and an OpenAI/Anthropic-compatible API server.

AI & Machine LearningAI Vision & Audio

985

uzairansaruzi

Featured

hermex

Hermex is a native SwiftUI iPhone app that lets you control a self-hosted Hermes AI agent directly from your phone, with no subscriptions, tracking, or third-party relay.

AI & Machine LearningLarge Language Models

941

simonw

Featured

speech-analyzer-cli

A macOS command-line tool that uses Apple's on-device speech APIs to transcribe prerecorded audio into plain text, JSON, JSONL, SRT, or WebVTT.

Developer ToolsCLI & Terminal