ACF JSON: import files and Local JSON
Advanced Custom Fields can describe field groups as JSON in two closely related formats. The import file is what ACF → Tools → Export produces and Import accepts: a JSON array that can hold one or many field groups. Local JSON is a single field-group object saved as group_xxxxxxxxxxxxx.json in an acf-json folder inside your theme or plugin.
Local JSON is the workflow most agencies use. When the folder exists, ACF writes a JSON file every time a field group is saved in the admin, and reads field definitions from the files instead of the database — faster, and easy to commit to Git. When a file is newer than the database copy (judged by its modified timestamp), ACF shows Sync available, so changes made on a developer’s machine can be pulled into staging and production with one click.
This generator gives you a visual builder with the same field types and settings as ACF and outputs either format. Keys are generated deterministically from the group title and field names, and the modified value is set to the current time whenever you edit, so the sync notice appears as expected.
How to use the WordPress ACF JSON Generator
- Build the field group: title, location rules and fields — or load the sample.
- Choose Tools → Import file for a one-off import, or Local JSON for an
acf-jsonfile. - Download the file. For imports, open ACF → Tools, pick the file under Import Field Groups and click Import JSON.
- For Local JSON, save the file in
wp-content/themes/your-theme/acf-json/(create the folder), then open ACF → Field Groups and click Sync available.
Example
The outer shape of a Local JSON file (fields shortened):
{
"key": "group_7c1f0a3e9b2d4",
"title": "Book Details",
"fields": [ … ],
"location": [
[
{ "param": "post_type", "operator": "==", "value": "book" }
]
],
"position": "acf_after_title",
"active": true,
"show_in_rest": 1,
"modified": 1790000000
}Local JSON tips
- The file name must match the group key:
group_7c1f0a3e9b2d4.json. - ACF writes to the active theme’s
acf-jsonfolder by default. In a plugin, set the save and load paths with theacf/settings/save_jsonandacf/settings/load_jsonfilters. - Commit the
acf-jsonfolder to version control and never edit the same group on two environments without syncing first — the newestmodifiedtimestamp wins. - Need fields that editors can never change? Use the ACF Field Generator to register them in PHP instead. The ACF field groups guide compares the approaches.
Frequently Asked Questions
What is the difference between the import file and Local JSON?
The import file is an array of groups that ACF copies into the database once. A Local JSON file is a single group object that ACF keeps reading from disk and offers to sync whenever it changes.
Why doesn’t “Sync available” appear?
Check that the folder is named exactly acf-json in the active theme (or registered via acf/settings/load_json), that the file name matches the key, and that the modified value is newer than the group already in the database.
Can I import a Local JSON file with ACF → Tools?
Yes. ACF’s importer accepts a single group object as well as an array, so either file from this tool works with Tools → Import.
Will importing overwrite an existing field group?
If a group with the same key exists, ACF updates it in place; otherwise it creates a new group. Fields keep their saved values as long as their names stay the same.
How do I validate or tidy the JSON?
The output is already valid, pretty-printed JSON. To inspect or reformat a JSON file you exported elsewhere, use the JSON Formatter.