program.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "OpenAffiliate Program",
  "description": "Schema for affiliate program YAML files in the OpenAffiliate registry",
  "type": "object",
  "required": ["name", "slug", "url", "category", "commission", "description", "short_description", "agents"],
  "properties": {
    "name": {
      "type": "string",
      "description": "Display name of the product/service"
    },
    "slug": {
      "type": "string",
      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
      "description": "URL-safe identifier, must match the filename"
    },
    "aliases": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Alternative names or brand references used for dedup/fuzzy matching (e.g. ChatGPT → openai)"
    },
    "url": {
      "type": "string",
      "format": "uri",
      "description": "Product website URL"
    },
    "kind": {
      "type": "string",
      "enum": [
        "affiliate",
        "referral",
        "creator-payout",
        "revenue-share",
        "cashback",
        "partner-network"
      ],
      "default": "affiliate",
      "description": "Type of income program. affiliate=traditional commission; referral=in-app refer-a-friend; creator-payout=platform payouts (YouTube Partner, Twitch); revenue-share=rev-share (Substack, Beehiiv); cashback=consumer cashback; partner-network=large marketplace partner programs (Amazon Associates, Shopify Partners)"
    },
    "source": {
      "type": "string",
      "enum": [
        "partnerstack-api",
        "cj-api",
        "impact-api",
        "awin-api",
        "reditus",
        "dub",
        "rewardful",
        "tolt",
        "firstpromoter",
        "lemonsqueezy",
        "product-hunt",
        "yc-directory",
        "hacker-news",
        "theresanaiforthat",
        "futuretools",
        "community",
        "manual",
        "legacy"
      ],
      "description": "Discovery channel this program was sourced from. Used for refresh cadence and attribution."
    },
    "category": {
      "type": "string",
      "enum": [
        "AI",
        "Analytics",
        "Business Operations",
        "Communication",
        "Content Management",
        "CRM",
        "Customer Support",
        "Design",
        "Developer Tools",
        "E-Commerce",
        "Email Marketing",
        "Finance",
        "HR & Recruiting",
        "Infrastructure",
        "Marketing",
        "Productivity",
        "SaaS",
        "Sales",
        "Security",
        "Social Media"
      ],
      "description": "Primary category (must be from allowlist)"
    },
    "tags": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Searchable tags"
    },
    "commission": {
      "type": "object",
      "required": ["type", "rate", "currency"],
      "properties": {
        "type": {
          "type": "string",
          "enum": ["recurring", "one-time", "tiered", "hybrid"]
        },
        "rate": {
          "type": "string",
          "description": "Commission rate (e.g. '30%', '$100', '20-40%')"
        },
        "currency": {
          "type": "string",
          "default": "USD"
        },
        "duration": {
          "type": ["string", "null"],
          "description": "How long commissions are paid (e.g. '12 months', 'lifetime')"
        },
        "conditions": {
          "type": ["string", "null"],
          "description": "Conditions for earning the commission"
        }
      }
    },
    "cookie_days": {
      "type": "integer",
      "minimum": 0,
      "description": "Cookie/attribution window in days"
    },
    "attribution": {
      "type": "string",
      "enum": ["last-click", "first-click", "multi-touch"],
      "default": "last-click"
    },
    "tracking_method": {
      "type": "string",
      "enum": ["cookie", "server-side", "hybrid"],
      "default": "cookie"
    },
    "payout": {
      "type": "object",
      "properties": {
        "minimum": {
          "type": "number",
          "description": "Minimum payout threshold"
        },
        "currency": {
          "type": "string",
          "default": "USD"
        },
        "frequency": {
          "type": "string",
          "enum": ["weekly", "monthly", "net-30", "net-60"]
        },
        "methods": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": ["bank", "paypal", "wise", "crypto", "check", "stripe"]
          }
        }
      }
    },
    "signup_url": {
      "type": ["string", "null"],
      "format": "uri",
      "description": "Direct link to affiliate program signup"
    },
    "approval": {
      "type": "string",
      "enum": ["auto", "manual", "invite-only"],
      "description": "How applications are approved"
    },
    "approval_time": {
      "type": ["string", "null"],
      "description": "Expected time to get approved"
    },
    "restrictions": {
      "type": ["array", "null"],
      "items": { "type": "string" },
      "description": "Program restrictions and rules"
    },
    "marketing_materials": {
      "type": "boolean",
      "default": false,
      "description": "Whether banners, links, landing pages are provided"
    },
    "api_available": {
      "type": "boolean",
      "default": false,
      "description": "Whether the program has an affiliate API"
    },
    "dedicated_manager": {
      "type": "boolean",
      "default": false,
      "description": "Whether a dedicated affiliate manager is assigned"
    },
    "dashboard_url": {
      "type": ["string", "null"],
      "description": "URL to the affiliate dashboard"
    },
    "network": {
      "type": ["string", "null"],
      "enum": [
        "partnerstack",
        "impact",
        "rewardful",
        "awin",
        "cj-affiliate",
        "dub",
        "firstpromoter",
        "tolt",
        "lemonsqueezy",
        "tapfiliate",
        "in-house",
        null
      ],
      "description": "Affiliate network (lowercase, hyphenated; null if unknown)"
    },
    "program_age": {
      "type": ["string", "null"],
      "description": "How long the affiliate program has existed"
    },
    "description": {
      "type": "string",
      "description": "Full description of the product and affiliate program"
    },
    "short_description": {
      "type": "string",
      "maxLength": 100,
      "description": "One-line description"
    },
    "agents": {
      "type": "object",
      "required": ["prompt"],
      "properties": {
        "prompt": {
          "type": "string",
          "description": "Instructions for AI agents on when to recommend this product"
        },
        "keywords": {
          "type": "array",
          "items": { "type": "string" }
        },
        "use_cases": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Specific scenarios when this product should be recommended"
        }
      }
    },
    "verified": {
      "type": "boolean",
      "default": false
    },
    "submitted_by": {
      "type": "string"
    },
    "created_at": {
      "type": "string",
      "format": "date"
    },
    "updated_at": {
      "type": ["string", "null"],
      "format": "date"
    },
    "last_verified_at": {
      "type": ["string", "null"],
      "format": "date",
      "description": "ISO date of last URL + data verification. Used for freshness / refresh cadence decisions."
    }
  },
  "additionalProperties": false
}