Why your plugin loader might be breaking the spec without you knowing
A seemingly simple JSON Schema rule—additionalProperties: false—is quietly derailing plugin compatibility across different clients. The Agent Plugins 1.0.0 specification introduces strict validation for plugin.json, but a single misunderstood clause is creating silent failures that only surface months later.
The overlooked clause in the spec
The specification’s §5.2 explicitly states that clients must ignore unknown top-level fields and continue loading the plugin, provided the rest of the manifest is valid. Yet many loaders treat any schema violation as fatal, which directly contradicts the rule. This discrepancy means a plugin that works in one client may fail silently in another, often without clear error messages. The issue isn’t just theoretical—real-world cases show its impact. For instance, Codex’s Agent Plugins loader once accepted any directory with a plugin.json, but when unknown fields appeared, hooks stopped running entirely. Meanwhile, oh-my-pi dropped plugins with extra frontmatter keys, reducing a plugin’s skills from 33 to 3. These aren’t bugs in the plugins themselves, but in how clients interpret the spec.
The testing gap
Most validation tools check if a plugin you wrote is correct, not whether a client handles plugins correctly. The difference is crucial. A client that rejects on unknown fields fails the spec, yet this behavior often slips through testing because it doesn’t trigger errors—just silent plugin drops. The author behind this observation built a conformance kit to address this gap. It pairs a real plugin directory with the exact load report a compliant client should produce. For example, a fixture labeled AP-5.2-UNKNOWN-FIELD includes a canonical plugin.json with an unknown field and expects the client to report it while still loading the plugin. Clients that reject outright fail this test, revealing non-conformance that would otherwise go unnoticed.
Why it matters
This isn’t just a niche compliance quirk—it’s a fragmentation risk for the Agent Plugins ecosystem. When clients behave differently, plugins become fragile, breaking silently for users without clear cause. For developers, this means testing isn’t enough; validating your plugin against their client is now part of the process. The stakes are higher for open ecosystems: a single misunderstood rule can erode trust and slow adoption. The good news? Fixing this is straightforward—update loaders to ignore unknown fields per §5.2, and adopt conformance testing before release. The bad news? The first sign of trouble may come from a frustrated user, not your logs.
Check the conformance kit on GitHub
Source: DEV Community. AI-assisted editorial synthesis — TechnoExpress.