<!-- Generated by scripts/generate-site-content.py — do not edit by hand -->


# codex-marketplace-json-valid

.agents/plugins/marketplace.json must be valid JSON with required fields

| | |
|---|---|
| **Severity** | error (auto) |
| **Autofix** | - |
| **Since** | v0.18.0 |
| **Repo Types** | codex-marketplace |
| **Category** | [OpenAI Codex](codex.md) |

## Why

`.agents/plugins/marketplace.json` is the catalog Codex reads to list and
install plugins. When an entry is malformed Codex "skips that plugin
entry instead of failing the whole marketplace", so a broken entry is
invisible at runtime — the plugin simply never appears.

This rule validates the Codex schema only. `.claude-plugin/marketplace.json`
is a different schema and stays with `claude-marketplace-json-valid`.

## Examples

**Bad:**

```json
{
  "plugins": [
    {
      "name": "note_taker",
      "source": {"source": "local", "path": "../outside"},
      "policy": {"installation": "MAYBE"}
    }
  ]
}
```

**Good:**

```json
{
  "name": "example-codex-plugins",
  "interface": {"displayName": "Example Codex Plugins"},
  "plugins": [
    {
      "name": "note-taker",
      "source": {"source": "local", "path": "./plugins/note-taker"},
      "policy": {"installation": "AVAILABLE", "authentication": "ON_INSTALL"},
      "category": "Productivity"
    }
  ]
}
```

## How to fix

Add the missing field or correct the value the violation names.

The catalog needs a top-level `name` and a `plugins` array. Every entry
needs a unique `name` and a `source`. A source is either a bare relative
path string or an object whose `source` field selects the type — `local`
(needs `path`), `url` (needs `url`), `git-subdir` (needs `url` and
`path`), or `npm` (needs `package`). An unrecognized source type is
reported as a warning so a type added upstream never breaks an existing
marketplace.

Local paths resolve against the *marketplace root* — the repository root,
not `.agents/plugins/`. They must stay inside that root: an absolute path
or one containing `..` is an error, and a missing `./` prefix is
informational. An `npm` `registry` must be an HTTPS URL with no embedded
credentials, query string, or fragment.

The spec asks for `policy.installation`, `policy.authentication`, and
`category` on every entry, so their absence is a warning. Unrecognized
policy values are warnings too: the upstream sources disagree on
strictness — the prose spec offers the values as examples ("such as"),
while the field-level `plugin-json-spec.md` publishes closed enums — and
a warning is the safe intersection of the two. Use
`installation-values` and `authentication-values` to adjust the sets.

## Configuration

```yaml
rules:
  codex-marketplace-json-valid:
    enabled: auto  # true | false | auto
    severity: error
```

| Parameter | Description | Default |
|-----------|-------------|---------|
| `installation-values` | Recognized policy.installation values | `["AVAILABLE", "INSTALLED_BY_DEFAULT", "NOT_AVAILABLE"]` |
| `authentication-values` | Recognized policy.authentication values | `["ON_INSTALL", "ON_USE"]` |


*Run `skillsaw explain codex-marketplace-json-valid` to see this documentation and the rule's effective configuration in your terminal.*