Apple’s Icon Composer saves each .icon file as a package containing artwork assets and an icon.json manifest.

That JSON controls things like:

  • Layers and groups
  • Light, dark, and tinted appearances
  • Liquid Glass blur and translucency
  • Shadows and specular effects
  • Blend modes
  • Layer positioning and visibility
  • Solid, automatic, and oriented gradient fills
  • Platform support for square and circular icons

The problem is that Apple doesn’t appear to publish the complete icon.json schema as a public API. The format also has details that aren’t obvious from using the UI—for example, specialization values can be "automatic", null, or a concrete value, while an explicit null can mean something different from an omitted property.

I created IconComposerModel to reverse-document the format from real files produced by Icon Composer:

https://github.com/peterpoliwoda/icon-composer-template

The repository currently contains:

  • A Swift Package with reusable Codable models
  • A detailed Markdown attribute reference
  • Real icon.json fixtures from several icons
  • Decode/encode round-trip tests to make sure values aren’t lost
  • Forward-compatible string-backed types for values Apple may extend later
  • Explicit preservation of missing, null, and concrete JSON values
  • Support for appearance specializations, named system fills, gradient orientation, group and layer properties, and the Liquid Glass settings observed so far

The reasoning behind the project is simple: if apps and developer tools are going to inspect, generate, migrate, or modify Icon Composer files, they need a shared model that doesn’t rely on scattered guesses about the format.

I’m treating the JSON produced by Icon Composer as the source of truth. Every new sample is added as a fixture, documented, and used to improve the model through regression tests.

The format is still empirical rather than an official Apple API, so I’d love more samples—especially files created with different Icon Composer/Xcode versions or icons using attributes not already covered. If you share one, it helps to include the complete icon.json, the tool version, and what you changed in the UI.