{"id":48465872,"url":"https://github.com/troychaplin/validation-api","last_synced_at":"2026-04-07T04:32:26.663Z","repository":{"id":347448272,"uuid":"1193217099","full_name":"troychaplin/validation-api","owner":"troychaplin","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-04T17:34:27.000Z","size":15265,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-04T18:37:24.319Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/troychaplin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-27T01:51:27.000Z","updated_at":"2026-04-04T17:34:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/troychaplin/validation-api","commit_stats":null,"previous_names":["troychaplin/validation-api"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/troychaplin/validation-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/troychaplin%2Fvalidation-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/troychaplin%2Fvalidation-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/troychaplin%2Fvalidation-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/troychaplin%2Fvalidation-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/troychaplin","download_url":"https://codeload.github.com/troychaplin/validation-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/troychaplin%2Fvalidation-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31500397,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T03:10:19.677Z","status":"ssl_error","status_checked_at":"2026-04-07T03:10:13.982Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-07T04:32:23.101Z","updated_at":"2026-04-07T04:32:26.649Z","avatar_url":"https://github.com/troychaplin.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"assets/icon-256x256.png\" alt=\"Validation API Plugin Banner\" style=\"float: left; margin-right: 1.5em; height: auto; width: 128px;\"\u003e\n\n# Validation API\n\nA pure validation framework for the WordPress block editor. Register validation checks for blocks, post meta fields, and editor-level content structure — with real-time feedback, visual indicators, and publish-locking. Zero built-in checks. Zero settings UI. Zero opinions. Just infrastructure.\n\nDesigned for Gutenberg core merge. External plugins provide the rules.\n\n## Features\n\n- **Three-Scope Validation:** Register checks for block attributes, post meta fields, and editor-level concerns (heading hierarchy, content structure, etc.)\n- **Real-Time Editor Feedback:** Validation runs as users edit — instant visual indicators with red (error) and yellow (warning) borders on blocks\n- **Publish Locking:** Error-level checks prevent publishing. Warnings show feedback but allow saving\n- **Validation Sidebar:** All issues displayed in a unified sidebar panel, grouped by severity, with click-to-navigate to the offending block\n- **Flat Registration API:** Register checks with `wp_register_block_validation_check()` and related functions — a `namespace` field attributes each check to the registering plugin\n- **Filterable Severity:** Every check passes through the `wp_validation_check_level` filter — any plugin can override severity at runtime\n- **Centralized Data Store:** A dedicated `core/validation` store via `@wordpress/data` manages all validation state with reactive selectors\n- **REST API:** Registered checks are exposed via `GET /wp/v2/validation-checks` for admin tooling and companion packages\n- **Editor Settings Integration:** Validation config flows from PHP to JS via the `block_editor_settings_all` filter, following Gutenberg's standard data passing pattern\n- **Extensible:** 20+ PHP actions/filters and 3 JS filters for complete customization\n\n## How It Works\n\nThe Validation API provides three registries and a coordinator:\n\n1. **Block Registry** — Validates block attributes (e.g., image alt text, button links)\n2. **Meta Registry** — Validates post meta fields (e.g., required SEO description)\n3. **Editor Registry** — Validates document-level concerns (e.g., heading hierarchy)\n\nEach registered check has a severity level (`error`, `warning`, or `none`) that determines its behavior. The coordinator locks/unlocks publishing based on whether any errors exist.\n\nThe plugin ships no built-in checks — it's a framework. Install a companion plugin or write your own checks.\n\n## Demo\n\n\u003e Recorded against the previous version of this plugin — the UI and plugin name differ, but the core validation behaviour demonstrated is the same.\n\n[![Validation API demo video](https://img.youtube.com/vi/mLsC2tDcdL8/maxresdefault.jpg)](https://www.youtube.com/watch?v=mLsC2tDcdL8)\n\n## Severity Model\n\n| Level | Behavior |\n|---|---|\n| `error` | Prevents saving. Shows red indicator. Filter can override. |\n| `warning` | Shows yellow indicator. Allows saving. Filter can override. |\n| `none` | Check is disabled. Skipped entirely. |\n| *(omitted)* | Defaults to `error`. Filter can override. |\n\nEvery active check passes through the `wp_validation_check_level` filter, making all checks configurable without the core plugin needing any storage:\n\n```php\napply_filters(\n    'wp_validation_check_level',\n    $registered_level,\n    $context // [ 'scope' =\u003e 'block', 'block_type' =\u003e 'core/image', 'check_name' =\u003e 'alt_text' ]\n);\n```\n\n## Quick Start\n\n### Register a Block Check\n\n```php\nadd_action( 'init', function() {\n    if ( ! function_exists( 'wp_register_block_validation_check' ) ) {\n        return;\n    }\n\n    wp_register_block_validation_check( 'core/image', [\n        'namespace'   =\u003e 'my-content-rules',\n        'name'        =\u003e 'alt_text',\n        'level'       =\u003e 'error',\n        'description' =\u003e 'Images must have alt text',\n        'error_msg'   =\u003e 'This image is missing alt text.',\n        'warning_msg' =\u003e 'Consider adding alt text to this image.',\n    ] );\n} );\n```\n\n### Add JavaScript Validation Logic\n\n```javascript\nimport { addFilter } from '@wordpress/hooks';\n\naddFilter(\n    'editor.validateBlock',\n    'my-plugin/image-alt',\n    ( isValid, blockType, attributes, checkName ) =\u003e {\n        if ( blockType === 'core/image' \u0026\u0026 checkName === 'alt_text' ) {\n            return !! attributes.alt \u0026\u0026 attributes.alt.trim().length \u003e 0;\n        }\n        return isValid;\n    }\n);\n```\n\n## Companion Settings Package\n\nThe **[validation-api-settings](https://github.com/troychaplin/validation-api-settings)** companion plugin provides an admin settings page built using a sortable table. It reads all registered checks and lets admins override severity levels globally — no code required.\n\nThe core plugin has no settings UI and no storage. The companion bridges admin settings to the `wp_validation_check_level` filter via `wp_options`.\n\n## Requirements\n\n- WordPress 6.7 or higher\n- PHP 7.0 or higher\n- Gutenberg block editor (classic editor not supported)\n\n## Documentation\n\n### Developer Guide\n\n- **[Getting Started](docs/guide/README.md)** — Register your first check in 30 lines\n- **[Block Checks](docs/guide/block-checks.md)** — Validate block attributes\n- **[Meta Checks](docs/guide/meta-checks.md)** — Validate post meta fields\n- **[Editor Checks](docs/guide/editor-checks.md)** — Validate document-level concerns\n- **[Severity Model](docs/guide/severity.md)** — Error vs. warning vs. none, and runtime overrides\n- **[Examples](docs/guide/examples.md)** — Complete integration examples\n\n### Technical Reference\n\n- **[Architecture](docs/technical/README.md)** — System design and internals\n- **[Data Flow](docs/technical/data-flow.md)** — PHP → JS pipeline\n- **[Hooks Reference](docs/technical/hooks.md)** — All PHP and JS hooks\n- **[API Reference](docs/technical/api.md)** — Public functions and contracts\n- **[Design Decisions](docs/technical/decisions.md)** — Why the API is shaped this way\n\n## Getting Involved\n\n### Get Started\n\n- Fork this repo\n- Create a branch off of `main`\n- Clone your fork locally\n- Run the following in the repo root: `pnpm install`\n\n### Contributing\n\n1. Ensure your code follows WordPress coding standards\n2. Run `pnpm build` to build production assets\n3. Test in the post editor\n4. Create a PR from your branch into the primary repo\n5. Provide detailed info in the PR template\n\n## Support\n\nFor bug reports, feature requests, or questions:\n\n1. Check the [Documentation](docs/README.md)\n2. Search existing GitHub issues before creating new ones\n3. Provide detailed reproduction steps for bugs\n4. Include WordPress version, PHP version, and block details\n\n## License\n\nThis project is licensed under the GPL v2 or later — see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftroychaplin%2Fvalidation-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftroychaplin%2Fvalidation-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftroychaplin%2Fvalidation-api/lists"}