Unity YAML Guide
What Is Unity YAML? GUIDs, fileIDs & Prefabs
An introduction to Unity YAML and the GUID, fileID, hierarchy, reference, and prefab data stored inside serialized assets.
Unity YAML terms at a glance
Unity YAML is Unity's text serialization format for scenes, prefabs, and other native assets. It uses a custom YAML subset to store typed Unity objects, serialized properties, local fileIDs, cross-asset GUID references, hierarchy, and prefab relationships in files that version-control systems can inspect and merge.
| Term | What it represents | Scope |
|---|---|---|
| Class ID | The Unity object type declared by an object header, such as a GameObject or Transform. | Unity type system |
| fileID | A serialized object identifier used by object headers and references. | One asset file |
| GUID | The stable project identity of an asset, stored in that asset's .meta file. |
Unity project |
| type | Additional information Unity uses when resolving a reference to an external asset. | Cross-file reference |
| .meta file | Asset metadata containing the GUID and importer settings that must travel with the asset. | Associated asset |
Why Unity uses YAML in the first place
Unity stores many native assets, including scenes and prefabs, as text so they can work with version control and remain inspectable outside the Editor. Unity's text-based scene documentation describes the format as easier to merge and suitable for tools that generate or analyze scene data.
But there is a catch. Unity does not use the full YAML specification. It uses a custom-optimized subset called UnityYAML, with its own supported and unsupported features. Unity also warns that externally producing or editing UnityYAML files is not supported, so human readability should not be mistaken for a general-purpose authoring format.
For practical review, the important point is that Unity YAML is not just configuration. It is serialized Unity object structure: GameObjects, Components, serialized fields, references, and relationships that Unity reconstructs when the asset loads.
How object identity is encoded
Each object definition starts with a header shaped like --- !u!<ClassID> &<fileID>. That line carries two important signals.
!u!{Class ID}tells Unity which object class the entry belongs to.&{File ID}identifies the serialized object instance inside that file.
This is the first place where many review problems begin. Developers tend to read YAML as lines of property changes, but Unity is really storing a graph of typed objects with IDs and relationships. Once scenes or prefabs get large, that distinction matters.
Local references and cross-file references
Inside a file, Unity links objects through fileID. A Transform can reference its GameObject, components can reference sibling objects, and scripts can point at other objects in the same prefab or scene.
Across files, Unity needs more than fileID, because a File ID is only unique inside one asset. That is where .meta files and GUIDs come in. To reference an object outside the file, Unity combines:
- the asset GUID from the target file’s meta file
- the target object’s
fileID - a
typefield that helps Unity decide how the file is loaded
A small line edit can represent a changed dependency, a broken prefab reference, or a different object target elsewhere in the project.
What changes when nested prefabs enter the picture
Nested prefabs and prefab variants raise the complexity sharply. Unity does not simply inline every object from the nested source. Instead, it serializes a PrefabInstance, source-prefab references, and a set of modifications or overrides. It may also generate stripped placeholder objects that exist mostly to preserve reference structure.
That means a review is no longer just about local object changes. It is about understanding how one file encodes changes relative to another prefab, which overrides are intentional, and which placeholder objects exist only as structural glue.
Review Unity YAML by object and relationship
Raw YAML is useful evidence, but it distributes Unity meaning across IDs, objects, and files. A practical review should make these relationships explicit:
- the object and property behind each change
- the object's hierarchy path
- changed local and cross-file references
- nested prefab source and override context
- validation results before merge or apply
FAQ
What is Unity YAML?
Unity YAML is Unity's text serialization format for assets such as scenes and prefabs. It stores Unity objects, properties, references, and relationships in a YAML-like file.
Why does Unity use YAML?
Text serialization makes Unity scenes and prefabs easier to inspect, diff, merge, and process with version control tools than opaque binary files.
Is Unity YAML standard YAML?
No. Unity uses a subset of YAML and diverges from the full YAML specification in some edge cases.
What is the difference between File ID and GUID?
File ID identifies an object inside one asset file. GUID identifies the asset itself across the project through its meta file. Cross-file references commonly need both.
Why does raw Unity YAML feel harder than normal config files?
Because it encodes relationships, references, and prefab structure, not just standalone properties.
Try MergeSight
Review the Unity change, not the YAML noise
MergeSight converts serialized Unity YAML into objects, hierarchy, properties, GUID references, and prefab relationships you can review directly.