{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://kakao.io/data/cacao-origin.schema.json",
  "title": "Cacao Origin",
  "description": "A structured record of a cacao origin in the kakao.io Open Cacao Index. An 'origin' describes cacao as a raw agricultural commodity at its place of production — not a finished chocolate product.",
  "type": "object",
  "additionalProperties": false,
  "required": ["id", "name", "country", "coordinates", "genetic_groups", "status", "updated_at"],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^[a-z]{2}-[a-z0-9-]+$",
      "description": "Stable identifier '<ISO 3166-1 alpha-2 country>-<slug>', e.g. 've-chuao'. Other records reference an origin by this id."
    },
    "name": { "type": "string", "description": "Common name of the origin." },
    "also_known_as": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Alternative names for the same origin."
    },
    "country": { "type": "string", "description": "Country of production." },
    "region": {
      "type": ["string", "null"],
      "description": "Region, valley, or appellation within the country."
    },
    "coordinates": {
      "type": "object",
      "additionalProperties": false,
      "required": ["lat", "lon"],
      "description": "Approximate location for mapping. Cacao origins lie roughly within 20 degrees of the equator.",
      "properties": {
        "lat": { "type": "number", "minimum": -90, "maximum": 90, "description": "Latitude, decimal degrees." },
        "lon": { "type": "number", "minimum": -180, "maximum": 180, "description": "Longitude, decimal degrees." },
        "approx": { "type": "boolean", "description": "True if the point is a regional/country centroid rather than a precise location." }
      }
    },
    "elevation_m": {
      "type": ["string", "null"],
      "description": "Approximate growing elevation or range, in metres, e.g. '200-600'."
    },
    "producer": {
      "type": "object",
      "additionalProperties": false,
      "required": ["type"],
      "description": "The producing entity, where a single identifiable one exists.",
      "properties": {
        "type": {
          "type": "string",
          "enum": ["estate", "cooperative", "collective", "regional", "multiple"],
          "description": "Kind of producing entity. 'regional' = an appellation-level origin with no single producer."
        },
        "name": { "type": ["string", "null"], "description": "Name of the estate, cooperative, or collective." }
      }
    },
    "genetic_groups": {
      "type": "array",
      "minItems": 1,
      "description": "Modern genetic clusters present in the population, following Motamayor et al. (2008). 'admixture' = mixed/hybrid populations; 'unknown' = not yet characterised.",
      "items": {
        "type": "string",
        "enum": ["Amelonado", "Contamana", "Criollo", "Curaray", "Guiana", "Iquitos", "Marañón", "Nacional", "Nanay", "Purús", "admixture", "unknown"]
      }
    },
    "traditional_class": {
      "type": ["string", "null"],
      "enum": ["Criollo", "Forastero", "Trinitario", "Nacional", "mixed", "unknown", null],
      "description": "Legacy market classification, kept for reference and cross-checking only. The genetic_groups field is authoritative."
    },
    "bean_notes": {
      "type": ["string", "null"],
      "description": "Notes on bean appearance, e.g. white/ivory vs purple cotyledon."
    },
    "harvest_season": {
      "type": ["string", "null"],
      "description": "Typical harvest period(s), e.g. 'main Oct-Feb; mid-crop May-Jul'."
    },
    "fermentation": {
      "type": ["string", "null"],
      "description": "Typical fermentation method and duration for this origin."
    },
    "drying": {
      "type": ["string", "null"],
      "description": "Typical drying practice, e.g. 'sun-dried on raised beds'."
    },
    "flavor_profile": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Commonly reported flavour descriptors for well-processed cacao from this origin."
    },
    "summary": {
      "type": ["string", "null"],
      "description": "A short, neutral 1-3 sentence description of the origin."
    },
    "certifications": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Certifications commonly associated with this origin (e.g. organic)."
    },
    "status": {
      "type": "string",
      "enum": ["draft", "reviewed", "verified"],
      "description": "Editorial status. 'draft' = seed entry pending source verification."
    },
    "sources": {
      "type": "array",
      "items": { "type": "string" },
      "description": "References supporting the record."
    },
    "updated_at": {
      "type": "string",
      "format": "date",
      "description": "ISO 8601 date this record was last updated."
    }
  }
}