Input File Format

Overview of AlphaFold 3 input JSON format and specifications

Overview

AlphaFold 3 uses a custom JSON input format that provides extensive control over structure prediction. You can provide inputs in two ways:

Single Input

Use --json_path flag with a single JSON file

Multiple Inputs

Use --input_dir flag with a directory of JSON files

Key Capabilities

The AlphaFold 3 JSON format allows you to:

• Specify protein, RNA, and DNA chains with modified residues
• Provide custom multiple sequence alignments (MSA) for proteins and RNA
• Include custom structural templates for proteins
• Define ligands using CCD codes, SMILES, or custom definitions
• Specify covalent bonds between entities
• Control predictions with multiple random seeds

Top-Level Structure

Every AlphaFold 3 input JSON file follows this structure:

{
  "name": "Job name goes here",
  "modelSeeds": [1, 2],
  "sequences": [
    {"protein": {...}},
    {"rna": {...}},
    {"dna": {...}},
    {"ligand": {...}}
  ],
  "bondedAtomPairs": [...],
  "userCCD": "...",
  "dialect": "alphafold3",
  "version": 4
}

Required Fields

name · string · required

The name of the job. A sanitized version is used for output file naming.

modelSeeds · array<integer> · required

List of integer random seeds. You must provide at least one seed. Each seed generates one predicted structure.

sequences · array · required

List of molecular entities (proteins, RNA, DNA, ligands). See detailed specifications in the JSON Specification guide.

dialect · string · required

Must be set to "alphafold3"

version · integer · required

Must be set to 1, 2, 3, or 4. Version 4 is the latest.

Optional Fields

bondedAtomPairs · array

Specifies covalent bonds between entities. Used for covalent ligands and multi-CCD ligands like glycans.

userCCD · string

User-provided chemical components dictionary in CCD mmCIF format (inline). Mutually exclusive with userCCDPath.

userCCDPath · string

Path to file containing user-provided CCD. Mutually exclusive with userCCD.

Format Versions

The input format has evolved across versions:

1. Version 1

   Initial AlphaFold 3 input format with basic entity definitions

2. Version 2

   Added unpairedMsaPath, pairedMsaPath, and mmcifPath fields for external MSA and templates

3. Version 3

   Added userCCDPath field for external user-provided CCD

4. Version 4

   Added description field for textual descriptions of chains and ligands

AlphaFold Server Compatibility

The AlphaFold 3 codebase uses a different JSON format from AlphaFold Server. However, run_alphafold.py includes an automatic converter that detects and translates AlphaFold Server JSON format.

Key Differences

Feature	AlphaFold Server	AlphaFold 3
Multiple inputs	List at top level	One input per file
Ions	Separate entity type	Treated as ligands
Entity IDs	Auto-assigned	User-specified (required)
Glycans	Supported	Must convert manually

Multiple Inputs

The AlphaFold Server format allows multiple inputs in a single JSON (top-level list). The AlphaFold 3 format requires one input per file. The converter handles this automatically.

Random Seeds

If AlphaFold Server JSON specifies "modelSeeds": [], the converter randomly chooses a seed. AlphaFold 3 format always requires explicit seeds.

Entity IDs

AlphaFold Server doesn’t require entity IDs. The converter auto-assigns IDs in “reverse spreadsheet style”:

A, B, ..., Z, AA, BA, CA, ..., ZA, AB, BB, CB, ..., ZB, ...

Quick Example

Here’s a minimal valid input for a homodimer protein:

fold_input.json

{
  "name": "2PV7",
  "sequences": [
    {
      "protein": {
        "id": ["A", "B"],
        "sequence": "GMRESYANENQFGFKTINSDIHKIVIVGGYGKLGGLFARYLRASGYPISILDREDWAVAESILANADVVIVSVPINLTLETIERLKPYLTENMLLADLTSVKREPLAKMLEVHTGAVLGLHPMFGADIASMAKQVVVRCDGRFPERYEWLLEQIQIWGAKIYQTNATEHDHNMTYIQALRHFSTFANGLHLSKQPINLANLLALSSPIYRLELAMIGRLFAQDAELYADIIMDKSENLAVIETLKQTYDEALTFFENNDRQGFIDAFHKVRDWFGDYSEQFLKESRQLLQQANDLKQG"
      }
    }
  ],
  "modelSeeds": [1],
  "dialect": "alphafold3",
  "version": 1
}

Next Steps

JSON Specification

Detailed entity definitions and examples

Running Docker

Execute AlphaFold 3 with your input files