The metadata region holds the disk’s settings as items named by GUIDs. It starts with a 64 KiB metadata table; the items follow, at offsets the table gives from the start of the region. All numbers are little-endian. This page follows [MS-VHDX] revision 8.0, section 2.6.
Metadata table
| Offset | Size | Type | Name | Description |
|---|---|---|---|---|
0 | 8 | text | Signature | metadata. |
8 | 2 | – | Reserved | 0. |
10 | 2 | uint16 | Entry count | At most 2,047. |
12 | 20 | – | Reserved | Zeros. |
32 | 32 each | entries | Entries | See below. |
| Offset | Size | Type | Name | Description |
|---|---|---|---|---|
0 | 16 | GUID | Item ID | What the item is. |
16 | 4 | uint32 | Offset | From the start of the metadata region, at least 64 KiB (past the table). Items must not overlap. 0 when the length is 0 (an empty item that is present). |
20 | 4 | uint32 | Length | Bytes, at most 1 MiB. |
24 | 4 | bits | Flags | Bit 0 IsUser: user metadata (at most 1,024 such entries); clear for system metadata. Bit 1 IsVirtualDisk: virtual disk metadata rather than file metadata; when a differencing file is made from this one these items are copied to it, and when a child is merged into its parent they replace the parent’s. Bit 2 IsRequired: a reader that does not recognise the item must fail to open the file. Bits 3–31 reserved. |
28 | 4 | – | Reserved | 0. |
System metadata items
| Item | GUID | Flags (user, virtual disk, required) | Size | Value |
|---|---|---|---|---|
| File parameters | CAA16737-FA36-4D43-B3B6-33F0AA44E76B | no, no, yes | 8 | uint32 block size: a power of two from 1 MiB to 256 MiB. Then uint32 flags: bit 0 LeaveBlockAllocated (blocks are not released and the file is not shrunk: a fully provisioned fixed disk; ignored with HasParent), bit 1 HasParent (a differencing disk); bits 2–31 reserved. |
| Virtual disk size | 2FA54224-CD1B-4876-B211-5DBED83BF4B8 | no, yes, yes | 8 | uint64: the disk size in bytes, a multiple of the logical sector size, at most 64 TB. |
| Virtual disk ID | BECA12AB-B2E6-4523-93EF-C309E000C746 | no, yes, yes | 16 | A GUID identifying the disk. |
| Logical sector size | 8141BF1D-A96F-4709-BA47-F233A8FAAB5F | no, yes, yes | 4 | uint32: 512 or 4,096; the same for parent and child. It also sets the chunk size. |
| Physical sector size | CDA348C7-445D-4471-9CC9-E9885251C556 | no, yes, yes | 4 | uint32: 512 or 4,096. |
| Parent locator | A8D35F2D-B30B-454D-ABF7-D3D84834AB0C | no, no, yes | varies | Required when HasParent is set: see parent locator. |
Parent locator
A header, then key/value entries; keys and values are UTF-16LE strings without a terminator, stored elsewhere in the item.
| Offset | Size | Type | Name | Description |
|---|---|---|---|---|
0 | 16 | GUID | Locator type | B04AEFB7-D19E-4A81-B789-25B8E9445913 for a VHDX parent. |
16 | 2 | – | Reserved | 0. |
18 | 2 | uint16 | Key/value count | Number of entries. |
20 | 12 each | entries | Entries | Each: key offset (uint32), value offset (uint32), key length (uint16), value length (uint16). Offsets count from the start of the locator; lengths are in bytes. |
| Key | Value |
|---|---|
parent_linkage | The parent’s data write GUID when the child was made, as a string in braces. Must be present. |
parent_linkage2 | A second possible value of the parent’s identity, in the same form. The specification says the parent’s data write GUID must match one of the two, while also saying this key “can’t be present”; that contradiction is in the text. |
relative_path | Path of the parent relative to this file, with \ separators and .. for the parent folder. |
volume_path | Absolute path using the volume’s GUID, such as \\?\Volume{26A21BDA-…}\path2\sub3\parent.vhdx. |
absolute_win32_path | Extended-length absolute path starting \\?\, then a drive letter or a UNC share. |
At least one of the three paths must be present. A reader tries them in the order
relative_path, volume_path, absolute_win32_path,
checks the parent’s data write GUID against the linkage, and updates stale paths once the
chain opens. Keys are case-sensitive and unique, with no NUL characters.