The ACF Block.json Migration Matrix Nobody Published

Search "acf_register_block_type to block.json mapping" and you get tutorials. Each one converts a single testimonial block and calls it done. None of them hand you the full key-by-key table: every legacy PHP argument, its block.json destination, and the handful of settings that have no destination at all. I migrated forty-plus blocks across two client themes this year. Some keys moved with zero friction. Others sat in gray areas I only resolved by testing in the block editor and watching what broke. This is the matrix I wish existed before I started. Why the gap exists ACF's own documentation covers acf_register_block_type() on one page and the block.json acf key on another. Both pages are accurate. Neither cross-references the other. A developer migrating a block has to hold both pages open and manually match render_template to renderTemplate , post_types to postTypes , and so on. Miss one, and a block silently loses a feature instead of throwing an error. Three categories of keys make this worse: Renamed keys. Same feature, different casing, different location. snake_case becomes camelCase , and the key moves from the flat settings array into a nested acf object. Relocated keys. Some legacy settings aren't ACF-specific at all. They belong to WordPress's core block registration and move to the top level of block.json, outside the acf object entirely. Orphaned keys. A few legacy settings have no documented block.json equivalent. You either drop the behavior, replicate it with WordPress's native supports API, or handle it in your render template instead. The full matrix Legacy acf_register_block_type() key block.json location Notes name Top-level name Must be namespaced, e.g. acf/testimonial instead of testimonial title Top-level title Direct match description Top-level description Direct match category Top-level category Direct match icon Top-level icon Direct match, including the array form for background/foreground colors keywords Top-level keywords Direct match p