Local JSON Sync — Git-Friendly Field Groups
Field Forge writes your field groups as JSON files in your site’s uploads folder (wp-content/uploads/fieldforge-json/). Commit those files to git, and your field group changes become part of your version control history. This is how professional agencies and development teams manage custom fields across multiple environments (development → staging → production) and across multiple team members.
The problem this solves
When you edit a field group in Field Forge’s admin, the change is saved to the WordPress database. Great — until you realize:
- Your local dev environment has one version of the field group
- Staging has a slightly different version (because someone edited it there)
- Production has yet another version (because a content editor added a field directly)
- You have no history of who changed what, or when, or why
Without version control, field groups drift out of sync. Migrations from dev to production become error-prone. Rollbacks are impossible.
Local JSON sync solves all of this by making field groups file-based alongside being database-based. The database is the source of truth for live editing; the JSON files are the source of truth for version control and deployment.
How it works
Step 1: Enable local JSON sync
In Field Forge → Settings → General, tick the Local JSON checkbox (“Save field groups as JSON files on disk (for version control)”). The save path is shown under it: wp-content/uploads/fieldforge-json/. There is no setting for the folder; a developer can move it with the fieldforge/local_json/save_path filter, inside the uploads folder only.
Step 2: Field groups are saved as JSON
Every time you save a field group in Field Forge’s admin, the plugin also writes a JSON file to the save folder. The filename is group_{id}_{slug}.json — e.g., group_1_hero-section.json.
File contents:
{
"_fieldforge_version": "1.1.0",
"_modified": "2026-10-11T09:30:00+00:00",
"_hash": "5d41402abc4b2a76b9719d911017c592",
"id": 1,
"title": "Hero Section",
"fields": [
{
"key": "field_hero_title",
"label": "Hero Title",
"name": "hero_title",
"type": "text",
"required": true,
"maxlength": 120
},
{
"key": "field_hero_subtitle",
"label": "Hero Subtitle",
"name": "hero_subtitle",
"type": "textarea",
"rows": 2
},
{
"key": "field_hero_image",
"label": "Background Image",
"name": "background_image",
"type": "image",
"return_format": "array"
}
],
"location_rules": [
[
{
"param": "post_template",
"operator": "==",
"value": "template-landing.php"
}
]
],
"menu_order": 0,
"status": "publish"
}
Step 3: Commit to git
Add the fieldforge-json/ folder to your git repo (or copy it into your theme or plugin repo). Commit field group changes like any other code change.
git add fieldforge-json/group_1_hero-section.json
git commit -m "Add background image field to Hero Section"
git push
Every field group change now has an author, a timestamp, and a commit message. You can diff changes over time, revert to previous versions, and see who added which field.
Step 4: Deploy JSON files to other environments
Deploy the JSON files with your code, or copy them to the other environment’s wp-content/uploads/fieldforge-json/ folder. Field Forge there detects the new or changed files, shows a notice, and imports them when you click Sync JSON → DB.
Bidirectional sync
Local JSON sync works in both directions: saving a field group in the admin writes its JSON file, and Sync JSON → DB applies the files to the database. Sync DB → JSON writes the database field groups to their JSON files.
UI-first workflow
Edit field groups visually in Field Forge’s admin. JSON files are updated on save. Commit JSON files to git. Deploy to other environments.
Code-first workflow
Commit the JSON files that Field Forge writes and deploy them with your code. Field Forge checks when an admin page loads (at most every five minutes) and shows a notice when a file differs from the database; click Sync JSON → DB to update the database. A file counts as changed when its _hash value differs from the hash of the database field group, so a file edited by hand that keeps its old _hash is not detected as a change. A file with a group id that the database does not have is offered as a new field group.
Because change detection compares only _hash, make changes to a field group in the field group editor and let Field Forge write the file. A file that you edit by hand without changing its _hash is not detected as a change, and neither is a file without a _hash.
Change detection
Field Forge compares each JSON file’s content hash to the database version on admin page loads (at most once every five minutes). If they differ, Field Forge:
- Shows an admin notice on the Field Forge screens: “Field Forge: N field group(s) have changes in JSON files”, with a Review & Sync link
- Shows the same count on the Local JSON Sync card of the Import / Export screen, with two buttons: Sync JSON → DB and Sync DB → JSON
- Changes nothing until you click one of them
This prevents silent drift: the files and the database are only brought together when you click. Sync JSON → DB replaces the database version with the file.
Security
Local JSON sync respects WordPress security best practices:
.htaccessprotection — Field Forge creates a.htaccessfile withDeny from alland anindex.phpin the JSON folder, so servers that read.htaccessfiles block direct HTTP access- Path validation — the plugin writes only inside the uploads folder, in a folder whose name starts with
fieldforge; a save path anywhere else is ignored
Load paths
Field Forge reads JSON files from these folders:
- The
fieldforge-json/folder of the uploads folder - The save path, when a filter moved it to another folder inside the uploads folder
- Any folders added with the
fieldforge/local_json/load_pathsfilter
Theme folders are not read by default. A theme that ships its own fieldforge-json/ folder, or a site whose files an older release wrote into a theme, adds that folder with the filter. The files in it are then applied with Sync JSON → DB.
Multi-site considerations
On a WordPress multisite network, each site has its own uploads folder, so its own fieldforge-json/ folder. To share field groups, add a common folder to the load paths of every site with the fieldforge/local_json/load_paths filter; each site applies the files to its own database with Sync JSON → DB.
Filter hooks for customization
Custom save path
The save path must be inside the uploads folder, in a folder whose name starts with fieldforge. Any other path is ignored.
add_filter('fieldforge/local_json/save_path', function($path) {
$uploads = wp_upload_dir();
return $uploads['basedir'] . '/fieldforge-json-shared';
});
Custom load paths (e.g., from a plugin)
add_filter('fieldforge/local_json/load_paths', function($paths) {
$paths[] = WP_PLUGIN_DIR . '/my-plugin/fields';
return $paths;
});
Comparison with ACF’s Local JSON
ACF introduced a similar local JSON feature years ago. Field Forge has its own file format, and Local JSON does not read ACF’s acf-json files.
If you’re migrating from ACF with existing acf-json files, the migration tool can read them as a source when the field groups are not in the ACF database tables, and translates them to Field Forge’s format.
Use cases
Agency development workflow
Multiple developers working on client sites. Field groups defined in code, committed to git, deployed via CI/CD. New team members pull the repo and have all field groups after clicking Sync JSON → DB.
Staged deployments
Dev → staging → production pipeline where field group changes travel as files with your deployment. No manual “oh wait, I need to export and import the field groups” step.
Theme distribution
Build a WordPress theme that ships with pre-defined field groups in its own folder. The theme adds that folder with the load paths filter, Field Forge detects the files, and the field groups appear after Sync JSON → DB.
Plugin bundling
A custom plugin that requires specific field groups. Ship the JSON files inside the plugin and register a load path via filter; Field Forge offers the field groups for Sync JSON → DB.
Ready to version control your field groups?
Local JSON sync is included in every version — the free edition on WordPress.org and every paid plan.