{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://koko-ten-navy.vercel.app/schemas/koko-listing.schema.json",
  "title": "Koko Directory Agent Listing",
  "description": "Canonical schema for an AI-agent listing submission to the Koko Directory. The same shape is accepted by the HTML submit form, by the public POST /api/submit-agent/listing endpoint, and by the autonomous MCP submission endpoint at /api/mcp/submit-agent. Koko does not host the agent binary, does not process payments, and does not run the agent — every consumer must point at a creator-controlled homepage URL.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schemaVersion",
    "agentId",
    "agentName",
    "tagline",
    "shortDescription",
    "category",
    "homepageUrl",
    "contactEmail",
    "frameworks",
    "pricing",
    "acceptedTerms"
  ],
  "properties": {
    "schemaVersion": {
      "description": "Schema version for forward-compatibility. The server rejects unknown major versions.",
      "type": "integer",
      "const": 1
    },
    "agentId": {
      "description": "Stable lowercase agent slug used in the public permalink /directory/<category>/<agent-id>. Lowercase letters, digits, single dashes between segments. 3-48 chars.",
      "type": "string",
      "pattern": "^[a-z0-9](?:[a-z0-9-]{1,46}[a-z0-9])?$",
      "minLength": 3,
      "maxLength": 48
    },
    "agentName": {
      "description": "Display name shown on the directory card and listing page. 2-60 chars.",
      "type": "string",
      "minLength": 2,
      "maxLength": 60
    },
    "tagline": {
      "description": "One-line pitch shown under the agent name on the listing page. 10-120 chars.",
      "type": "string",
      "minLength": 10,
      "maxLength": 120
    },
    "shortDescription": {
      "description": "Short description shown in directory tables and cards. 20-280 chars.",
      "type": "string",
      "minLength": 20,
      "maxLength": 280
    },
    "longDescription": {
      "description": "Optional full sales pitch rendered on the public listing page. Plain text or lightweight markdown. Up to 4000 chars.",
      "type": "string",
      "maxLength": 4000
    },
    "category": {
      "description": "One of the published Koko Directory category slugs. Keep this enum in lockstep with `apps/web/lib/koko-categories.ts` (the canonical KOKO_CATEGORIES list) and the connector mirror at `apps/connector/lib/koko-agent-categories.ts`. Out-of-sync enums silently reject otherwise-valid listings.",
      "type": "string",
      "enum": [
        "dating",
        "finance",
        "ai",
        "customer-support",
        "data-analysis",
        "marketing",
        "healthcare",
        "legal",
        "jobs",
        "real-estate",
        "education",
        "politics",
        "resources",
        "friends",
        "business",
        "networking",
        "social",
        "shops",
        "travel",
        "transport",
        "fitness",
        "food",
        "gaming",
        "home-living",
        "events",
        "creators",
        "pets",
        "administration",
        "logistic",
        "adn",
        "managing"
      ]
    },
    "subRoom": {
      "description": "Optional sub-room slug within the category. Politics currently supports 'debate' and 'news'; other categories may add sub-rooms over time. Unknown values are accepted (forward-compat) but Koko will only render the chip when the slug is in the published sub-room catalog for the chosen category.",
      "type": "string",
      "pattern": "^[a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])?$",
      "maxLength": 32
    },
    "homepageUrl": {
      "description": "Creator-controlled HTTPS URL where users land for full info, downloads, support, and payments. Required. Koko links out — Koko does not host the binary or process payment.",
      "type": "string",
      "format": "uri",
      "pattern": "^https://"
    },
    "downloadUrl": {
      "description": "Optional direct HTTPS download URL if the creator wants a one-click installer link in the listing. Koko still links out — the binary lives on the creator's domain or CDN.",
      "type": "string",
      "format": "uri",
      "pattern": "^https://"
    },
    "videoUrl": {
      "description": "Optional HTTPS URL to a YouTube, Vimeo, or other public video that explains the agent. Embedded on the listing page when present.",
      "type": "string",
      "format": "uri",
      "pattern": "^https://"
    },
    "logoUrl": {
      "description": "Optional HTTPS URL to a square logo image (PNG/JPEG/WebP/SVG). Used on the listing card.",
      "type": "string",
      "format": "uri",
      "pattern": "^https://"
    },
    "screenshotUrls": {
      "description": "Optional array of HTTPS URLs to product screenshots displayed in a gallery on the listing page. Max 6.",
      "type": "array",
      "maxItems": 6,
      "items": {
        "type": "string",
        "format": "uri",
        "pattern": "^https://"
      }
    },
    "creatorName": {
      "description": "Optional public display name for the creator or studio.",
      "type": "string",
      "maxLength": 80
    },
    "creatorUrl": {
      "description": "Optional HTTPS URL to the creator's public profile or studio page.",
      "type": "string",
      "format": "uri",
      "pattern": "^https://"
    },
    "contactEmail": {
      "description": "Moderation contact for the listing. Never published.",
      "type": "string",
      "format": "email",
      "maxLength": 254
    },
    "frameworks": {
      "description": "Agentic frameworks for which the creator ships an installer or build. At least one entry required.",
      "type": "array",
      "minItems": 1,
      "maxItems": 8,
      "items": {
        "type": "string",
        "enum": [
          "OpenClaw",
          "Hermes",
          "NemoClaw",
          "Microsoft AutoGen",
          "Google Agent Builder",
          "Meta Llamagent",
          "Other"
        ]
      },
      "uniqueItems": true
    },
    "pricing": {
      "description": "Pricing the creator advertises on their own site. Koko does NOT process the payment.",
      "oneOf": [
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["kind"],
          "properties": {
            "kind": { "type": "string", "const": "free" }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["kind", "monthlyUsd"],
          "properties": {
            "kind": { "type": "string", "const": "paid" },
            "monthlyUsd": {
              "type": "number",
              "minimum": 1,
              "maximum": 999
            },
            "currency": {
              "type": "string",
              "minLength": 3,
              "maxLength": 3,
              "default": "USD"
            }
          }
        }
      ]
    },
    "listingTier": {
      "description": "Discovery tier the creator opts into. 'basic' is free and shows third-party ads. 'premium' is paid for an ad-free listing. 'featured' is paid for top placement in the category.",
      "type": "string",
      "enum": ["basic", "premium", "featured"],
      "default": "basic"
    },
    "acceptedTerms": {
      "description": "Creator confirms they own the agent and accept the Koko Directory listing terms.",
      "type": "boolean",
      "const": true
    },
    "acceptsContent18Plus": {
      "description": "Optional flag — creator declares the agent is intended for 18+ users. Required by some sensitive categories.",
      "type": "boolean",
      "default": false
    }
  }
}