parisek/acf-json-schema

JSON Schema bundle for Advanced Custom Fields JSON exports (field groups, CPT, taxonomy, blocks). Targets ACF Pro 6.8.x.

v0.4.1 2026-06-01 15:57 UTC

Requires

• php: ^8.3
• nikic/php-parser: ^5.0
• opis/json-schema: ^2.3

Requires (Dev)

• ergebnis/composer-normalize: ^2.0
• php-stubs/acf-pro-stubs: ^6.5
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^11.0 || ^12.0

GPL-3.0-or-later

• Petr Parimucha

• wordpress
• lint
• acf
• json-schema
• advanced custom fields

README

JSON Schema bundle for Advanced Custom Fields JSON exports — field groups (acf.json), Custom Post Types (<cpt>.json), Taxonomies (<tax>.json), and ACF Blocks (block.json).

Target: ACF Pro 6.8.x. Free edition partially supported (field-group + field-type schemas only).

Generated against: ACF Pro 6.8.2 · WPML 4.9.4 · ACFML 2.2.4 — the live install the canonical schemas were curated and snapshot-tested against.

What this is

Comprehensive JSON Schema (draft 2020-12) coverage for every JSON file the ACF Pro Admin Sync UI emits. Schemas are hand-curated against a live WP + ACF Pro + WPML install — the generator (bin/acf-schema-gen) reproduces the canonical baseline, and a snapshot test asserts byte-equality on every CI run. WPML/ACFML keys (e.g. acfml_field_group_mode, wpml_cf_preferences) are optional, so plain ACF (non-WPML) exports validate too.

Use case: lint your project's ACF JSON files in CI. Catch typos, type drift, and shape regressions before they ship to production.

Install

composer require --dev parisek/acf-json-schema

Point your Ajv-based JSON validator at vendor/parisek/acf-json-schema/schemas/:

import path from "node:path";
import { createRequire } from "node:module";
const require = createRequire(import.meta.url);
const pkgPath = require.resolve("parisek/acf-json-schema/composer.json");
const SCHEMAS_ROOT = path.join(path.dirname(pkgPath), "schemas");

Load acf.schema.json, block.schema.json, cpt.schema.json, or taxonomy.schema.json from SCHEMAS_ROOT, register the refs/ directory, and validate your project's ACF JSON files against them.

Bundled schemas

File	Validates
schemas/acf.schema.json	ACF Field Group JSON — discriminates on type to per-field-type refs
schemas/block.schema.json	ACF Block JSON (block.json with acf section)
schemas/cpt.schema.json	ACF Custom Post Type JSON (Pro 6.2+ JSON-Sync)
schemas/taxonomy.schema.json	ACF Taxonomy JSON (Pro 6.2+ JSON-Sync)
schemas/refs/field-<36 types>.schema.json	Per-field-type closed-shape constraints (35 stable + icon_picker new in 6.8)
schemas/refs/{field,icon,location-rule,permalink-rewrite}.schema.json	Shared utility refs

(_meta.json carries generator provenance — ACF version, timestamp — and is intentionally not part of the canonical schemas.)

Linting your project's ACF JSON (PHP)

composer require --dev parisek/acf-json-schema
vendor/bin/acf-lint --strict path/to/templates path/to/blocks

acf-lint walks the given files/dirs, dispatches each JSON to the right bundled schema (block / acf / cpt / taxonomy), and reports findings. Files of an unrecognized shape are skipped.

Flag	Effect
--strict	Exit non-zero on any finding (CI gate).
--fix	Bump stale/missing modified timestamps.
--wpml	Require WPML/ACFML translation keys to be present: acfml_field_group_mode on each field group and wpml_cf_preferences on every value-holding field (recurses into repeater/group/flexible-content; tab/message/accordion are exempt). Opt-in — the schemas keep these keys optional so non-WPML projects are unaffected.

For maintainers

Regenerate / verify schemas against a live WP+ACF Pro install:

ddev exec "php vendor/bin/acf-schema-gen --wp-root /var/www/html --output /tmp/acf-schemas-out/"
diff -r /tmp/acf-schemas-out/ vendor/parisek/acf-json-schema/schemas/

See RELEASING.md for the full release flow.

License

GPL-3.0-or-later