{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://valueledger.co/data/schema.json",
  "title": "研值月營收 JSON 資料契約",
  "description": "適用 /company/<代號>.json 物件及 /data/latest.json 頂層陣列。latest.json 保留既有欄位，單位及產站時間由同版 manifest.json 提供。",
  "oneOf": [
    {
      "$ref": "#/$defs/company"
    },
    {
      "$ref": "#/$defs/latest"
    }
  ],
  "$defs": {
    "revenueRecord": {
      "type": "object",
      "description": "latest.json 中的一家公司既有營收資料。",
      "properties": {
        "code": {
          "type": "string",
          "description": "公司代號；一律字串，保留前導零，例如 0050。",
          "pattern": "^[A-Za-z0-9_-]+$"
        },
        "name": {
          "type": "string",
          "description": "公司名稱。"
        },
        "market": {
          "type": "string",
          "description": "公司市場。",
          "enum": [
            "上市",
            "上櫃"
          ]
        },
        "industry": {
          "type": "string",
          "description": "原始產業別；未提供時沿用既有正規化值「未分類」。"
        },
        "month": {
          "type": "string",
          "pattern": "^\\d{4}-(0[1-9]|1[0-2])$",
          "description": "營收資料所屬月份，西元 YYYY-MM；不是產站月份。"
        },
        "reportDate": {
          "type": "string",
          "format": "date",
          "description": "原始資料出表日期，西元 YYYY-MM-DD；不是抓取或產站時間。"
        },
        "revenue": {
          "type": [
            "number",
            "null"
          ],
          "description": "當月營收；新台幣千元，缺值為 null，0 僅代表來源的真實零值。"
        },
        "previousMonthRevenue": {
          "type": [
            "number",
            "null"
          ],
          "description": "上月營收；新台幣千元，缺值為 null，0 僅代表來源的真實零值。"
        },
        "lastYearMonthRevenue": {
          "type": [
            "number",
            "null"
          ],
          "description": "去年同月營收；新台幣千元，缺值為 null，0 僅代表來源的真實零值。"
        },
        "momPercent": {
          "type": [
            "number",
            "null"
          ],
          "description": "月增率；百分比數值；1.6 代表 1.6%，不是 160%。缺值為 null，不以 0 代替。"
        },
        "yoyPercent": {
          "type": [
            "number",
            "null"
          ],
          "description": "年增率；百分比數值；1.6 代表 1.6%，不是 160%。缺值為 null，不以 0 代替。"
        },
        "cumulativeRevenue": {
          "type": [
            "number",
            "null"
          ],
          "description": "當年 1 月至資料月份累計營收；新台幣千元，缺值為 null，0 僅代表來源的真實零值。"
        },
        "lastYearCumulativeRevenue": {
          "type": [
            "number",
            "null"
          ],
          "description": "去年 1 月至同月份累計營收；新台幣千元，缺值為 null，0 僅代表來源的真實零值。"
        },
        "cumulativeYoyPercent": {
          "type": [
            "number",
            "null"
          ],
          "description": "累計年增率；百分比數值；1.6 代表 1.6%，不是 160%。缺值為 null，不以 0 代替。"
        },
        "sources": {
          "type": "array",
          "description": "沿用既有兩市場官方 OpenAPI 網址清單；個別資料列的直接來源依 market 對應 manifest.sources。",
          "items": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "required": [
        "code",
        "name",
        "market",
        "industry",
        "month",
        "reportDate",
        "revenue",
        "previousMonthRevenue",
        "lastYearMonthRevenue",
        "momPercent",
        "yoyPercent",
        "cumulativeRevenue",
        "lastYearCumulativeRevenue",
        "cumulativeYoyPercent",
        "sources"
      ],
      "additionalProperties": false
    },
    "historyRow": {
      "type": "object",
      "description": "單一月份歷史營收。",
      "properties": {
        "month": {
          "type": "string",
          "pattern": "^\\d{4}-(0[1-9]|1[0-2])$",
          "description": "營收資料所屬月份，西元 YYYY-MM；不是產站月份。"
        },
        "revenue": {
          "type": [
            "number",
            "null"
          ],
          "description": "當月營收；新台幣千元，缺值為 null，0 僅代表來源的真實零值。"
        },
        "reportDate": {
          "type": "string",
          "format": "date",
          "description": "原始資料出表日期，西元 YYYY-MM-DD；不是抓取或產站時間。"
        }
      },
      "required": [
        "month",
        "revenue",
        "reportDate"
      ],
      "additionalProperties": false
    },
    "company": {
      "type": "object",
      "description": "單一公司 JSON，保留全部既有欄位並新增契約 metadata。",
      "properties": {
        "code": {
          "type": "string",
          "description": "公司代號；一律字串，保留前導零，例如 0050。",
          "pattern": "^[A-Za-z0-9_-]+$"
        },
        "name": {
          "type": "string",
          "description": "公司名稱。"
        },
        "market": {
          "type": "string",
          "description": "公司市場。",
          "enum": [
            "上市",
            "上櫃"
          ]
        },
        "industry": {
          "type": "string",
          "description": "原始產業別；未提供時沿用既有正規化值「未分類」。"
        },
        "month": {
          "type": "string",
          "pattern": "^\\d{4}-(0[1-9]|1[0-2])$",
          "description": "營收資料所屬月份，西元 YYYY-MM；不是產站月份。"
        },
        "reportDate": {
          "type": "string",
          "format": "date",
          "description": "原始資料出表日期，西元 YYYY-MM-DD；不是抓取或產站時間。"
        },
        "revenue": {
          "type": [
            "number",
            "null"
          ],
          "description": "當月營收；新台幣千元，缺值為 null，0 僅代表來源的真實零值。"
        },
        "previousMonthRevenue": {
          "type": [
            "number",
            "null"
          ],
          "description": "上月營收；新台幣千元，缺值為 null，0 僅代表來源的真實零值。"
        },
        "lastYearMonthRevenue": {
          "type": [
            "number",
            "null"
          ],
          "description": "去年同月營收；新台幣千元，缺值為 null，0 僅代表來源的真實零值。"
        },
        "momPercent": {
          "type": [
            "number",
            "null"
          ],
          "description": "月增率；百分比數值；1.6 代表 1.6%，不是 160%。缺值為 null，不以 0 代替。"
        },
        "yoyPercent": {
          "type": [
            "number",
            "null"
          ],
          "description": "年增率；百分比數值；1.6 代表 1.6%，不是 160%。缺值為 null，不以 0 代替。"
        },
        "cumulativeRevenue": {
          "type": [
            "number",
            "null"
          ],
          "description": "當年 1 月至資料月份累計營收；新台幣千元，缺值為 null，0 僅代表來源的真實零值。"
        },
        "lastYearCumulativeRevenue": {
          "type": [
            "number",
            "null"
          ],
          "description": "去年 1 月至同月份累計營收；新台幣千元，缺值為 null，0 僅代表來源的真實零值。"
        },
        "cumulativeYoyPercent": {
          "type": [
            "number",
            "null"
          ],
          "description": "累計年增率；百分比數值；1.6 代表 1.6%，不是 160%。缺值為 null，不以 0 代替。"
        },
        "sources": {
          "type": "array",
          "description": "沿用既有兩市場官方 OpenAPI 網址清單；個別資料列的直接來源依 market 對應 manifest.sources。",
          "items": {
            "type": "string",
            "format": "uri"
          }
        },
        "schema_version": {
          "type": "string",
          "description": "研值營收資料契約版本。",
          "const": "1.0.0"
        },
        "currency": {
          "type": "string",
          "description": "金額幣別：新台幣。",
          "const": "TWD"
        },
        "amount_unit": {
          "type": "string",
          "description": "所有金額欄位以千元為單位；1 代表 TWD 1,000。",
          "const": "thousand"
        },
        "canonical_url": {
          "type": "string",
          "description": "本公司 HTML 頁面的正式引用網址。",
          "format": "uri"
        },
        "generated_at": {
          "type": "string",
          "description": "實際執行本次產站的 UTC 時間，ISO 8601；不代表資料剛抓取。",
          "format": "date-time"
        },
        "retrieved_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "來源實際抓取時間；現有快照查無此證據，填 null。"
        },
        "manifest_url": {
          "type": "string",
          "description": "本次資料集月份、公司數、來源日期與更新資訊所在網址。",
          "format": "uri"
        },
        "history_months_available": {
          "type": "integer",
          "minimum": 0,
          "maximum": 24,
          "description": "此公司 history 實際筆數，不把上限視為已具備的歷史長度。"
        },
        "history": {
          "type": "array",
          "maxItems": 24,
          "description": "依月份排序，最多 24 個月；各筆金額同為新台幣千元。",
          "items": {
            "$ref": "#/$defs/historyRow"
          }
        }
      },
      "required": [
        "code",
        "name",
        "market",
        "industry",
        "month",
        "reportDate",
        "revenue",
        "previousMonthRevenue",
        "lastYearMonthRevenue",
        "momPercent",
        "yoyPercent",
        "cumulativeRevenue",
        "lastYearCumulativeRevenue",
        "cumulativeYoyPercent",
        "sources",
        "schema_version",
        "currency",
        "amount_unit",
        "canonical_url",
        "generated_at",
        "retrieved_at",
        "manifest_url",
        "history_months_available",
        "history"
      ],
      "additionalProperties": false
    },
    "latest": {
      "type": "array",
      "description": "全部公司當月資料，頂層仍為陣列。",
      "items": {
        "$ref": "#/$defs/revenueRecord"
      }
    }
  }
}