From 6b0210e4bee84d8bea3f200091badbe796a5c88f Mon Sep 17 00:00:00 2001 From: Jonathan Hefner Date: Tue, 1 Sep 2026 15:56:54 -0700 Subject: [PATCH] Make malformed extensions fatal in Agent Plugins 1.1 Treat a non-object `extensions` field like every other recognized-field schema violation. Keep unknown top-level fields as the sole non-fatal exception so clients can support forward compatibility without weakening strict authoring validation. Leave Agent Plugins 1.0 behavior unchanged, document the loading exception in the strict schema, and align the extension namespace, conformance, and failure wording. --- schemas/1.1.0/plugin.schema.json | 1 + spec/1.1.0.md | 10 +++++----- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/schemas/1.1.0/plugin.schema.json b/schemas/1.1.0/plugin.schema.json index 499cb1d..d9c4c72 100644 --- a/schemas/1.1.0/plugin.schema.json +++ b/schemas/1.1.0/plugin.schema.json @@ -3,6 +3,7 @@ "$id": "https://agent-plugins.org/schemas/1.1.0/plugin.schema.json", "title": "Agent Plugins Manifest", "description": "Machine-readable schema for plugin.json in Agent Plugins 1.1.0. The Agent Plugins specification defines additional semantic and operational requirements.", + "$comment": "When loading a plugin, clients must report and ignore unrecognized top-level properties, then validate the remaining manifest against this schema. All other schema violations are fatal.", "type": "object", "properties": { "$schema": { diff --git a/spec/1.1.0.md b/spec/1.1.0.md index a3c7103..266224d 100644 --- a/spec/1.1.0.md +++ b/spec/1.1.0.md @@ -144,7 +144,7 @@ The manifest MUST be JSON and MUST contain a top-level object. Its schema is clo If `plugin.json` contains any other top-level field, it does not conform to the schema. Clients MUST report and ignore each unknown field and MUST continue loading the plugin if the manifest otherwise satisfies this section. Clients MUST NOT assign semantics to unknown fields. Client-specific manifest data belongs under `extensions` as defined in §8. -A non-object `extensions` field is handled as defined in §8.1. Every permitted field otherwise MUST match the type and constraints defined below. Any schema violation other than an unknown top-level field or a non-object `extensions` field is fatal: the client MUST reject the plugin and MUST NOT discover or execute any of its components. +Every permitted field MUST match the type and constraints defined below. Any schema violation other than an unknown top-level field is fatal: the client MUST reject the plugin and MUST NOT discover or execute any of its components. The official machine-readable schema is [`schemas/1.1.0/plugin.schema.json`](../schemas/1.1.0/plugin.schema.json). The specification text is authoritative if it conflicts with the schema. @@ -404,7 +404,7 @@ Client-specific manifest data MUST be represented under a reverse-domain namespa A client SHOULD base its namespace on a domain name it controls and SHOULD keep the namespace stable. For example, a client that controls `example.com` could use `com.example.client`. -Agent Plugins assigns no portable discovery, validation, loading, or failure semantics to client extension data or files. Each client defines the contents and behavior of its own namespace, including how its manifest data and directory contents relate. +Agent Plugins assigns no portable discovery, validation, loading, or failure semantics within a client extension namespace. Each client defines the contents and behavior of its own namespace, including how its manifest data and directory contents relate. ### 8.1 Manifest extension data @@ -424,7 +424,7 @@ Example: } ``` -If `extensions` is not an object, the client MUST report and ignore the field and continue loading components. A client MUST ignore manifest entries for namespaces it does not implement without validating the contents of their values. Validation and failure handling within an implemented namespace are defined by that client. +A client MUST ignore manifest entries for namespaces it does not implement without validating the contents of their object values. Validation and failure handling within an implemented namespace are defined by that client. ### 8.2 Extension directories @@ -528,7 +528,7 @@ Clients MAY use `version` to determine whether updates are available and whether A conformant client MUST satisfy all applicable requirements in sections 1–10. At minimum, it: 1. Can load a plugin from a directory path. -2. Selects a locally supported plugin manifest schema from `$schema`, then parses and validates the closed `plugin.json` schema using the non-fatal exceptions in §5.2 and §8.1. +2. Selects a locally supported plugin manifest schema from `$schema`, then parses and validates the closed `plugin.json` schema using the non-fatal unknown-field exception in §5.2. 3. Ignores unimplemented members of `extensions` without validating the contents of their values. 4. For each component type it supports, discovers components in its fixed location. 5. If it supports MCP servers, selects a locally supported MCP configuration schema from `$schema` and supports at least one of the `stdio` or `streamable-http` variants in `mcp.json`. @@ -543,7 +543,7 @@ A client is not required to support every component type. For example, a skills- ### 11.3 Unsupported components and failures 1. Clients MUST ignore unsupported component types. -2. An unknown top-level field or a non-object `extensions` field is non-fatal under §5.2 and §8.1. Any other `plugin.json` schema violation is fatal to the plugin: the client MUST reject the plugin and MUST NOT discover or execute any of its components. +2. An unknown top-level field is non-fatal under §5.2. Any other `plugin.json` schema violation is fatal to the plugin: the client MUST reject the plugin and MUST NOT discover or execute any of its components. 3. A failure isolated to a component type, component entry, or component process MUST NOT prevent the client from loading independently valid components. Clients MUST apply the failure behavior defined for that component in §6 and §7. 4. Clients SHOULD report invalid configuration and component failures. Clients MAY report partially unsupported plugins, but lack of support for a component type, MCP transport, or client extension is not itself an error.