Images file format 2.0

images.json files provide details about images included in composes.

Changes from 1.1

• path, size, and checksums fields replaced by a single location object

• Location objects include url, size, checksum, local_path, and optional contents

• URLs may be HTTPS URLs, OCI registry references, or relative paths

• OCI images may include a contents array describing individual files as layers

• Checksums use algorithm:hexdigest format (e.g., sha256:abc123...)

• force_version parameter added to serialize() for version control

Location Object

Each image entry contains a location object instead of separate path, size, and checksums fields. The location.local_path preserves the v1.x relative path for backward-compatible filesystem layout.

For OCI images that bundle multiple files (e.g., boot images with kernel, initrd, efiboot.img), the contents array provides per-file metadata including the OCI layer digest. See FileEntry for details.

File Format

Compose images metadata is stored as a JSON serialized dictionary. It’s recommended to sort keys alphabetically and use 4 spaces for indentation in order to read and diff images.json files easily.

Image Identity

It is required that the combination of subvariant, type, format, arch and disc_number attributes is unique to each image in the compose. This is to ensure these attributes can be used to identify ‘the same’ image across composes. This may require including the variant string in the subvariant.

{
    "header": {
        "type": "productmd.images",                 # metadata type; "productmd.images" required
        "version": "2.0"                            # metadata version; format: $major<int>.$minor<int>
    },
    "payload": {
        "compose": {                                # see composeinfo for details
            "date": <str>,
            "id": <str>,
            "respin": <int>,
            "type": <str>
        },
        "images": {
            variant_uid<str>: {                     # compose variant UID
                arch<str>: [                        # compose variant arch
                    {
                        "arch": <str>,              # image arch
                        "bootable": <bool>,         # can the image be booted?
                        "disc_count": <int>,        # number of discs in media set
                        "disc_number": <int>,       # disc number
                        "format": <str>,            # see productmd.images.SUPPORTED_IMAGE_FORMATS
                        "implant_md5": <str|null>,  # md5 checksum implanted directly on media
                        "mtime": <int>,             # mtime as a decimal unix timestamp
                        "subvariant": <str>,        # image content (e.g. 'Workstation' or 'KDE')
                        "type": <str>,              # see productmd.images.SUPPORTED_IMAGE_TYPES
                        "volume_id": <str|null>,    # volume ID; null if not available/applicable
                        "location": {               # Location object [new in 2.0]
                            "url": <str>,           # HTTPS URL, OCI reference, or relative path
                            "size": <int>,          # file size in bytes
                            "checksum": <str>,      # "algorithm:hexdigest" format
                            "local_path": <str>,    # relative path for v1.x filesystem layout
                            "contents": [           # optional; for OCI images with multiple files
                                {
                                    "file": <str>,          # relative path within the image
                                    "size": <int>,          # file size in bytes
                                    "checksum": <str>,      # "algorithm:hexdigest" format
                                    "layer_digest": <str>   # OCI layer digest (sha256:...)
                                }
                            ]
                        }
                    }
                ]
            }
        }
    }
}

Examples

Fedora 41 Server images with HTTPS and OCI URLs:

{
    "header": {
        "type": "productmd.images",
        "version": "2.0"
    },
    "payload": {
        "compose": {
            "date": "20260204",
            "id": "Fedora-41-20260204.0",
            "respin": 0,
            "type": "production"
        },
        "images": {
            "Server": {
                "x86_64": [
                    {
                        "arch": "x86_64",
                        "bootable": true,
                        "disc_count": 1,
                        "disc_number": 1,
                        "format": "iso",
                        "implant_md5": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
                        "mtime": 1738627200,
                        "subvariant": "",
                        "type": "dvd",
                        "volume_id": "Fedora-S-41-x86_64",
                        "location": {
                            "url": "https://cdn.fedoraproject.org/.../Fedora-Server-dvd-x86_64-41-1.1.iso",
                            "size": 2465792000,
                            "checksum": "sha256:1a2b3c4d...",
                            "local_path": "Server/x86_64/iso/Fedora-Server-dvd-x86_64-41-1.1.iso"
                        }
                    },
                    {
                        "arch": "x86_64",
                        "bootable": false,
                        "format": "qcow2",
                        "mtime": 1738627200,
                        "subvariant": "",
                        "type": "qcow2",
                        "volume_id": null,
                        "location": {
                            "url": "oci://quay.io/fedora/server:41-x86_64@sha256:3c4d5e6f...",
                            "size": 512000000,
                            "checksum": "sha256:3c4d5e6f...",
                            "local_path": "Server/x86_64/images/Fedora-Server-41-1.1.x86_64.qcow2"
                        }
                    }
                ]
            }
        }
    }
}