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",
        "mode",
        "currency"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "recurring",
            "one-time",
            "tiered",
            "hybrid"
          ]
        },
        "rate": {
          "type": [
            "string",
            "number"
          ],
          "description": "Exactly what the source said, e.g. \"30%\", \"$5 per lead + 30%\", \"varies\". Kept verbatim; read mode and value instead."
        },
        "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"
        },
        "mode": {
          "type": "string",
          "enum": [
            "percentage",
            "flat",
            "tiered",
            "hybrid",
            "unknown"
          ],
          "description": "How to read value. unknown means no figure was published — say so rather than printing the raw string into a number column."
        },
        "value": {
          "type": [
            "number",
            "null"
          ],
          "description": "The number a reader compares on: percent when mode is percentage or tiered-by-percent, currency amount when flat. Null when mode is unknown. For a range this is the upper bound."
        }
      }
    },
    "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 the affiliate signup or program page. Must not be the bare homepage and must differ from url — a link that only repeats the website tells a reader nothing."
    },
    "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
}