Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions schemas/1.1.0/plugin.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,14 @@
"license": {
"type": "string"
},
"privacyPolicyUrl": {
"type": "string",
"description": "Publisher's privacy policy URL (HTTPS recommended)."
},
"termsOfServiceUrl": {
"type": "string",
"description": "Publisher's terms of service URL (HTTPS recommended)."
},
"keywords": {
"type": "array",
"items": {
Expand Down
37 changes: 25 additions & 12 deletions spec/1.1.0.md
Original file line number Diff line number Diff line change
Expand Up @@ -178,7 +178,7 @@ A client loads and validates root `plugin.json` before discovering components or

### 5.2 Manifest object

The manifest MUST be JSON and MUST contain a top-level object. Its schema is closed: the only permitted top-level fields are `$schema`, `name`, `displayName`, `version`, `description`, `author`, `homepage`, `repository`, `license`, `keywords`, and `extensions`.
The manifest MUST be JSON and MUST contain a top-level object. Its schema is closed: the only permitted top-level fields are `$schema`, `name`, `displayName`, `version`, `description`, `author`, `homepage`, `repository`, `license`, `privacyPolicyUrl`, `termsOfServiceUrl`, `keywords`, and `extensions`.

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.

Expand Down Expand Up @@ -216,6 +216,8 @@ Example: full manifest
"homepage": "https://docs.example.com/plugin",
"repository": "https://github.com/example/plugin",
"license": "MIT",
"privacyPolicyUrl": "https://example.com/privacy",
"termsOfServiceUrl": "https://example.com/terms",
"keywords": ["keyword1", "keyword2"],
"extensions": {
"com.example.client": {
Expand All @@ -236,22 +238,26 @@ If a required field is missing, has the wrong type, is empty, or otherwise viola

### 5.4 Metadata fields

| Field | Type | Description |
| ------------- | -------- | ----------------------------------------------------------------------------------------------- |
| `version` | string | Version string (Semantic Versioning RECOMMENDED). Used for update checks and cache freshness. |
| `displayName` | string | Human-readable plugin name for presentation. |
| `description` | string | Short description of plugin purpose. |
| `author` | object | Author object with optional `name`, `email`, and `url` string fields. |
| `homepage` | string | Documentation or homepage URL. |
| `repository` | string | Source repository URL. |
| `license` | string | License identifier (SPDX identifier RECOMMENDED). |
| `keywords` | string[] | Search and discovery tags. |
| Field | Type | Description |
| ------------------- | -------- | ----------------------------------------------------------------------------------------------- |
| `version` | string | Version string (Semantic Versioning RECOMMENDED). Used for update checks and cache freshness. |
| `displayName` | string | Human-readable plugin name for presentation. |
| `description` | string | Short description of plugin purpose. |
| `author` | object | Author object with optional `name`, `email`, and `url` string fields. |
| `homepage` | string | Documentation or homepage URL. |
| `repository` | string | Source repository URL. |
| `license` | string | License identifier (SPDX identifier RECOMMENDED). |
| `privacyPolicyUrl` | string | Publisher's privacy policy URL (HTTPS RECOMMENDED). |
| `termsOfServiceUrl` | string | Publisher's terms of service URL (HTTPS RECOMMENDED). |
| `keywords` | string[] | Search and discovery tags. |

The optional `displayName` field provides a human-readable plugin name for presentation. A client that presents a human-readable plugin name SHOULD use `displayName` when present, but MAY use `name` instead when `displayName` is unsuitable for the presentation context, such as when it is empty or contains only whitespace.

The optional `privacyPolicyUrl` and `termsOfServiceUrl` fields identify the plugin publisher's own privacy policy and terms of service. They do not describe independently operated services that a plugin accesses. Clients MAY present these URLs in plugin discovery, installation, or management interfaces and are not required to retrieve or display them. A client that presents them SHOULD attribute them to the plugin publisher.

The `author` object MAY contain only the `name`, `email`, and `url` fields, each with a string value. Any other field or value type makes the manifest invalid.

Except where this specification states an explicit constraint, metadata fields are validated only by their JSON types. Clients MUST NOT reject a manifest solely because `version` is not valid Semantic Versioning; `homepage`, `repository`, or `author.url` is not a recognized URL; `author.email` is not a recognized email address; or `license` is not an SPDX identifier.
Except where this specification states an explicit constraint, metadata fields are validated only by their JSON types. Clients MUST NOT reject a manifest solely because `version` is not valid Semantic Versioning; `homepage`, `repository`, `author.url`, `privacyPolicyUrl`, or `termsOfServiceUrl` is not a recognized URL; `author.email` is not a recognized email address; or `license` is not an SPDX identifier.

### 5.5 Plugin name constraints

Expand Down Expand Up @@ -607,6 +613,7 @@ A client is not required to support every component type. For example, a skills-
- [ ] Validate required `$schema` and `name` fields ([§5.3](#53-required-fields))
- [ ] Validate plugin name against naming constraints ([§5.5](#55-plugin-name-constraints))
- [ ] If presenting a human-readable plugin name, prefer `displayName` and fall back to `name` ([§5.4](#54-metadata-fields))
- [ ] If presenting `privacyPolicyUrl` or `termsOfServiceUrl`, attribute them to the plugin publisher ([§5.4](#54-metadata-fields))
- [ ] Report and ignore unknown `plugin.json` fields ([§5.2](#52-manifest-object))
- [ ] Ignore unimplemented namespaces in manifest `extensions` without validating the contents of their object values ([§8.1](#81-extension-data))
- [ ] Reject package paths that resolve outside the plugin root ([§4.1](#41-general-requirements))
Expand Down Expand Up @@ -678,6 +685,12 @@ The constrained `name` field gives every client the same portable plugin name. T

`displayName` is intentionally constrained only by its JSON type. Presentation needs such as length and formatting vary across clients and UI surfaces, and the field affects only optional presentation metadata. Clients can fall back to the required `name` when `displayName` is unsuitable for a presentation context, rather than reject an otherwise valid plugin.

### Why portable publisher policy URLs?

A plugin's privacy policy and terms of service describe the plugin as distributed, not the client that loads it, so every client and catalog would otherwise rediscover the same information through a client-specific extension. Existing plugin ecosystems already carry these URLs in their manifests, and a portable field lets an author declare them once.

The fields are validated only by their JSON types, like the other metadata URLs. Requiring a URL form or an HTTPS scheme would make a malformed policy link fatal to an otherwise valid plugin, which is a worse outcome than a link a client can choose not to present.

### Why reverse-domain client extensions?

Reverse-domain identifiers provide a decentralized convention for avoiding collisions without requiring a central client-name registry. The same identifier can be used for configuration data and a client-specific directory; each representation can exist independently. Extension directories remain top-level to keep plugin layouts flat and convention-driven.
Expand Down