# Required Fields in the Codex Plugin Manifest: Complete Schema Reference

> Master the Codex plugin manifest schema. Discover all required fields, including name, version, description, and interface UI elements, for marketplace success. Explore the complete reference now.

- Repository: [Peter Yang/no-ai-slop](https://github.com/petergyang/no-ai-slop)
- Tags: api-reference
- Published: 2026-09-13

---

**The Codex plugin manifest requires nine top-level metadata fields—including `name`, `version`, `description`, `author`, `homepage`, `repository`, `license`, `keywords`, and `skills`—plus an `interface` object containing fifteen UI-specific fields such as `displayName`, `category`, `capabilities`, and `brandColor` to render correctly in the marketplace.**

The **Codex plugin manifest** defines how your extension integrates with the Codex ecosystem. In the **no-ai-slop** repository by petergyang, the file [`.codex-plugin/plugin.json`](https://github.com/petergyang/no-ai-slop/blob/main/.codex-plugin/plugin.json) demonstrates the exact schema required for plugin validation and marketplace display, ensuring all required fields in the Codex plugin manifest are properly implemented.

## Top-Level General Fields

These nine fields describe the plugin package, authorship, and discovery metadata. According to the source code in `no-ai-slop`, Codex expects these as direct properties of the manifest root object.

### Core Identity

- **`name`** — The unique identifier of the plugin (e.g., `"no-ai-slop"`).
- **`version`** — Semantic version string (e.g., `"1.0.0"`).
- **`description`** — Short textual summary shown in plugin listings and search results.

### Authorship and Legal

- **`author`** — Object containing `name` (required string) and optional `url` linking to the creator's profile.
- **`homepage`** — URL to the plugin's landing page or primary documentation.
- **`repository`** — Direct link to the source code repository (e.g., GitHub URL).
- **`license`** — SPDX-compatible license identifier (e.g., `"MIT"`, `"Apache-2.0"`).

### Discovery and Structure

- **`keywords`** — Array of searchable tags used for plugin discovery (e.g., `["productivity", "editing"]`).
- **`skills`** — Relative path string to the directory containing the plugin's skill definitions (e.g., `"./skills"`).

## Interface Configuration Fields

The **`interface`** object defines how Codex displays your plugin in the UI, handles legal compliance, and routes user requests. All fifteen sub-fields are required for marketplace submission.

### Display and Branding

- **`displayName`** — Human-readable name shown in the Composer UI and plugin catalog.
- **`shortDescription`** — Concise tagline (typically one sentence) displayed in grid views.
- **`longDescription`** — Full markdown-enabled description explaining features and usage.
- **`brandColor`** — Hex color code (e.g., `"#FF5733"`) used for UI borders and badges.
- **`composerIcon`** — Relative path to the icon displayed in the Composer interface (e.g., `"assets/icon.png"`).
- **`logo`** — Relative path to the full-resolution plugin logo.

### Compliance and Capabilities

- **`developerName`** — Name of the individual developer or organization responsible for the plugin.
- **`category`** — Broad functional classification (e.g., `"Productivity"`, `"Developer Tools"`).
- **`capabilities`** — Array of supported operation strings such as `"Edit"`, `"Detect"`, or `"Preserve voice"`.
- **`websiteURL`** — Link to the developer's official website or product page.
- **`privacyPolicyURL`** — Direct URL to the privacy policy document.
- **`termsOfServiceURL`** — Direct URL to the terms of service agreement.
- **`defaultPrompt`** — Example prompt string illustrating how users should invoke the plugin.

## Working with the Manifest in Code

The `no-ai-slop` repository includes build scripts and documentation referencing these fields. The manifest validation logic in [`scripts/build_plugin.py`](https://github.com/petergyang/no-ai-slop/blob/main/scripts/build_plugin.py) checks for presence of all required keys before packaging.

### Loading and Inspecting the Manifest

This Node.js snippet demonstrates reading the manifest and accessing nested interface properties:

```javascript
const fs = require('fs');
const path = require('path');

const manifestPath = path.join(__dirname, '.codex-plugin', 'plugin.json');
const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));

console.log(`Plugin "${manifest.name}" v${manifest.version}`);
console.log(`Category: ${manifest.interface.category}`);
console.log(`Capabilities: ${manifest.interface.capabilities.join(', ')}`);

```

### Rendering UI Components

React applications can import the manifest directly to generate consistent branding:

```jsx
import manifest from '../.codex-plugin/plugin.json';
import ComposerIcon from manifest.interface.composerIcon;

function PluginCard() {
  return (
    <div style={{ border: `2px solid ${manifest.interface.brandColor}` }}>
      <img src={ComposerIcon} alt={manifest.interface.displayName} />
      <h2>{manifest.interface.displayName}</h2>
      <p>{manifest.interface.shortDescription}</p>
      <a href={manifest.interface.websiteURL}>Learn more</a>
    </div>
  );
}

```

### Pre-Submission Validation

Use this Python script to verify all required fields in the Codex plugin manifest before publishing, as implemented in the repository's build process:

```python
import json, sys, pathlib

required = [
    "name", "version", "description", "author", "homepage",
    "repository", "license", "keywords", "skills", "interface"
]
interface_required = [
    "displayName", "shortDescription", "longDescription",
    "developerName", "category", "capabilities", "websiteURL",
    "privacyPolicyURL", "termsOfServiceURL", "defaultPrompt",
    "brandColor", "composerIcon", "logo"
]

manifest_path = pathlib.Path('.codex-plugin/plugin.json')
manifest = json.loads(manifest_path.read_text())

missing = [k for k in required if k not in manifest]
missing += [f"interface.{k}" for k in interface_required if k not in manifest["interface"]]

if missing:
    sys.exit(f"Missing required fields: {', '.join(missing)}")
print("All required fields present.")

```

## Summary

- The **Codex plugin manifest** requires nine top-level fields covering identity, authorship, and code location, plus a comprehensive `interface` object with fifteen display and compliance fields.
- **Validation scripts** like those in [`scripts/build_plugin.py`](https://github.com/petergyang/no-ai-slop/blob/main/scripts/build_plugin.py) enforce the presence of `privacyPolicyURL`, `termsOfServiceURL`, and `capabilities` before marketplace submission.
- **Asset paths** such as `composerIcon` and `logo` must be relative to the repository root, allowing Codex to resolve files like `assets/no-ai-slop.png` correctly.
- The complete schema is demonstrated in [`.codex-plugin/plugin.json`](https://github.com/petergyang/no-ai-slop/blob/main/.codex-plugin/plugin.json) within the `no-ai-slop` repository, serving as the authoritative reference for plugin developers.

## Frequently Asked Questions

### What is the difference between `description` and `interface.shortDescription`?

The top-level `description` field provides a technical summary for developers browsing repository listings, while `interface.shortDescription` is the marketing tagline displayed in the Codex marketplace UI. The interface version should be punchy and user-focused, whereas the top-level version can be more technical or detailed.

### Are `author.url` and all interface sub-fields strictly mandatory?

While `author` requires a `name` property, the `url` sub-field is optional. However, **all** fields listed within the `interface` object—including `privacyPolicyURL`, `termsOfServiceURL`, and `brandColor`—are strictly required for marketplace acceptance. Omitting any interface field causes validation failures in the submission pipeline referenced in [`plugin-submission.md`](https://github.com/petergyang/no-ai-slop/blob/main/plugin-submission.md).

### How should I reference external assets like icons in the manifest?

Store assets in a dedicated directory such as `assets/` and reference them using relative paths from the repository root. For example, `"composerIcon": "assets/no-ai-slop.png"` allows Codex to locate the file correctly during plugin packaging. The build process in [`scripts/build_plugin.py`](https://github.com/petergyang/no-ai-slop/blob/main/scripts/build_plugin.py) verifies these paths exist before generating the final distribution.

### What license identifiers does the Codex manifest accept?

The `license` field accepts **SPDX-compatible identifiers** such as `"MIT"`, `"Apache-2.0"`, `"GPL-3.0"`, or `"BSD-3-Clause"`. Using non-standard strings or full license text instead of SPDX short codes will trigger validation warnings when submitting to the Codex marketplace.