{
  "title": "Explore public trade aggregates — settings",
  "type": "object",
  "schemaVersion": 1,
  "properties": {
    "sources": {
      "title": "Trade data sources",
      "type": "array",
      "editor": "select",
      "description": "Public sources. Default comtrade is keyless.",
      "default": [
        "comtrade"
      ],
      "items": {
        "type": "string",
        "enum": [
          "comtrade",
          "census"
        ],
        "enumTitles": [
          "UN Comtrade preview (keyless)",
          "Census HS imports (free API key)"
        ]
      },
      "sectionCaption": "Source, period and commodity"
    },
    "reporterCode": {
      "title": "Comtrade reporter code",
      "type": "string",
      "editor": "textfield",
      "default": "842",
      "description": "842 = United States."
    },
    "period": {
      "title": "Comtrade calendar year",
      "type": "string",
      "editor": "textfield",
      "description": "Four-digit year. Empty = previous calendar year.",
      "example": "2023"
    },
    "flowCode": {
      "title": "Import or export flow",
      "type": "string",
      "editor": "select",
      "default": "M",
      "enum": [
        "M",
        "X"
      ],
      "enumTitles": [
        "Imports (M)",
        "Exports (X)"
      ],
      "description": "UN Comtrade trade flow code (e.g. M for imports)."
    },
    "cmdCode": {
      "title": "Comtrade commodity code",
      "type": "string",
      "editor": "textfield",
      "default": "TOTAL",
      "description": "Commodity / HS code filter for Comtrade queries."
    },
    "partnerCode": {
      "title": "Comtrade partner code",
      "type": "string",
      "editor": "textfield",
      "default": "0",
      "description": "Partner country/area code for Comtrade queries."
    },
    "censusApiKey": {
      "title": "Census API key",
      "type": "string",
      "editor": "textfield",
      "description": "Free key from api.census.gov — only for census source.",
      "isSecret": true
    },
    "censusTime": {
      "title": "Census month (YYYY-MM)",
      "type": "string",
      "editor": "textfield",
      "example": "2024-12",
      "description": "Census month period (YYYY-MM) for HS aggregate pulls."
    },
    "hsCode": {
      "title": "Census HS commodity code",
      "type": "string",
      "editor": "textfield",
      "default": "85",
      "description": "Census HS commodity code filter."
    },
    "maxItems": {
      "title": "Maximum aggregate rows",
      "type": "integer",
      "editor": "number",
      "minimum": 1,
      "maximum": 5000,
      "default": 50,
      "description": "Maximum dataset rows to emit before stopping."
    },
    "maxRunSeconds": {
      "title": "Run time budget (seconds)",
      "type": "integer",
      "editor": "number",
      "minimum": 30,
      "maximum": 3600,
      "default": 240,
      "description": "Hard wall-clock budget for the run in seconds.",
      "sectionCaption": "Run budget"
    },
    "softFail": {
      "title": "Keep run successful on source failure",
      "type": "boolean",
      "default": false,
      "description": "Default false: missing credentials or complete source failure fails the run. True: keep the run successful with zero dataset rows and an explicit blocked/source_failed SUMMARY status. Diagnostics never become billable results."
    }
  },
  "description": "For trade researchers, collect commodity and country aggregates from public statistical sources without treating them as shipment records. Keyless UN Comtrade preview by default. Optional Census HS import aggregates require a free Census API key. No bills of lading are returned."
}