Export and import definitions (JSON)

WPM Fields › Tools › Export & import copies definitions from one site to another with a single file. Saved field values are not included: see WordPress export files (WXR) and duplicates to move values.

Export

1. Open WPM Fields › Tools. The Export & import tab is the default.
2. In the Export card, tick what you want. Every kind that has at least one item gets its own box, titled with its name and count, for example Field Groups (3). Each item shows its label and its key.
3. • Tick a box title to select every item of that kind.
   • Select all at the top selects everything.
3. The counter next to the button shows %d selected.
4. Click Download JSON. The browser saves wpmcf-export-YYYY-MM-DD.json.

If you have not created anything yet the card says Nothing to export yet.

The Download JSON button stays disabled until at least one item is ticked.

What the file looks like

{
  "format": "wpmcf-export",
  "version": 1,
  "plugin_version": "1.0.0",
  "exported_at": "2026-10-03T12:58:39+00:00",
  "post_types": [],
  "taxonomies": [],
  "options_pages": [],
  "field_groups": []
}

• All four sections are always present; the ones you did not select are empty lists.
• Field groups carry their fields (with sub-fields, conditional logic, settings and validation), their location rules and their group settings. Each field has a uid, a stable identifier that lets the importer recognise a field after it was renamed.
• Dates of creation and change are exported but ignored on import: the target site keeps its own.
• The file is readable and diff-friendly (pretty printed, no escaped slashes or Unicode).

Import

1. In the Import card click Choose JSON file and pick a file made by this plugin. (.json files only.)
2. The preview starts at once. Nothing is saved yet. The Preview list shows one row per definition:

Each row shows the label, the key, the kind and a message. Warnings appear in orange below the row; file-wide warnings appear in a notice above the list.

3. Decide about overwriting. Replace existing definitions is off by default, so definitions that already exist on this site are kept exactly as they are. Switch it on to replace them. The preview reloads when you flip the switch.
4. Click Import N definition(s). The button is disabled while the preview has nothing to create or replace.
5. The Result list replaces the preview, with the badges Created, Replaced, Kept and Error. A toast says Import finished. or, when at least one row failed, Import finished with errors. See the list below.

One failing row never stops the others: every item is imported on its own. Fix the file (or the site) and import again; items that already went through are then simply Kept.

Order and references

Items are imported in this order: post types, taxonomies, options pages, field groups. That order lets a field group be placed on a post type that the same file creates, and lets a post type and a taxonomy in the same file refer to each other. References to things that are neither in the file nor on the site are errors.

What happens to a field group

Importing a field group goes through the same code as saving it in the editor:

• A new group gets its table created immediately. A file with many new groups takes a moment.
• Replacing a group adds, renames, retypes and removes columns exactly as saving the group would. A very large table is changed in the background instead; the row then carries the warning The table is large, so the database change runs in the background. The new definition is used once it is done.
• Data in a removed field is not dropped. See Changing a field group safely.
• A group on a site without the right plan fails when it contains an advanced field type: Field "pics": the Gallery field type is not included in your plan.
• Location rules that point to a term (post category, post taxonomy) store the term id, and ids differ between sites. Check those rules after importing.

Keys and uids when you write the file yourself

Keys are cleaned the same way WordPress cleans slugs: lowercase letters, numbers, dashes and underscores. A key like Bad Key! is imported as badkey.

Fields without a uid are fine. When you import over an existing group (Replace existing definitions on), a field that has no uid reuses the stored uid of the field with the same key, so the importer sees the same field and no column is dropped or recreated. Keep the uid anyway when you rename a field key in the file: the uid is what tells the importer it is the same field. A field with a new key and no uid is a new field.

Files made by Download JSON always have uids.

Messages you can meet

The whole file is refused

Warnings (the import still runs)

One definition fails

For developers

The Tools screen uses these REST routes (namespace wpmcf/v1, administrators only):

Troubleshooting

The preview shows Error for every field group. Open the message of one row. The most common causes are a missing plan for an advanced field type and a location rule that points to something that does not exist on this site.

The group was imported but my data is not there. Definitions never include values. Use WXR for posts, or the ACF migration for ACF data.

Replace did nothing for a post type. Post types and taxonomies are replaced as a whole. Check the preview badge: it must say Replace, not Kept. If it says Kept, Replace existing definitions is off.

"Choose JSON file" accepts my file but the preview is empty. The file is valid but contains no definitions: The file contains no definitions.