{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/valotcg/json-schema/valotcg-price-summary-schema.json",
  "title": "PriceSummary",
  "x-generated": "2026-11-03",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/valotcg-data-v1-openapi.json#/components/schemas/PriceSummary",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "card",
        "sealed"
      ],
      "title": "Type"
    },
    "card": {
      "anyOf": [
        {
          "$ref": "#/$defs/CardSummary"
        },
        {
          "type": "null"
        }
      ]
    },
    "sealed": {
      "anyOf": [
        {
          "$ref": "#/$defs/SealedSummary"
        },
        {
          "type": "null"
        }
      ]
    },
    "recommended": {
      "$ref": "#/$defs/RecommendedPrice"
    },
    "reliability": {
      "type": "string",
      "enum": [
        "ok",
        "stale",
        "insufficient_sample"
      ],
      "title": "Reliability",
      "description": "`insufficient_sample`: no source qualifies for a recommended price. `stale`: the retained Cardmarket or US market observation is older than 48 h (35 days for French Cardmarket offers)."
    },
    "changes": {
      "items": {
        "$ref": "#/$defs/PriceChange"
      },
      "type": "array",
      "title": "Changes",
      "description": "Changes over 7, 30 and 90 days."
    },
    "prices": {
      "items": {
        "$ref": "#/$defs/PriceQuote"
      },
      "type": "array",
      "title": "Prices",
      "description": "Every source in its native currency, as on /prices."
    },
    "graded": {
      "anyOf": [
        {
          "$ref": "#/$defs/GradedPrices"
        },
        {
          "type": "null"
        }
      ],
      "description": "Cards, with `include=graded`."
    },
    "population": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/PopulationReport"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Population",
      "description": "Cards, with `include=population`."
    }
  },
  "type": "object",
  "required": [
    "type",
    "recommended",
    "reliability",
    "changes",
    "prices"
  ],
  "$defs": {
    "CardSummary": {
      "properties": {
        "card_id": {
          "type": "integer",
          "title": "Card Id",
          "description": "Stable Valo.Data card id."
        },
        "game": {
          "type": "string",
          "title": "Game",
          "description": "Game slug, e.g. `pokemon`, `onepiece`, `star_wars_unlimited`."
        },
        "name": {
          "type": "string",
          "title": "Name",
          "description": "Printed name in the card language."
        },
        "name_en": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Name En",
          "description": "English name when known."
        },
        "number": {
          "type": "string",
          "title": "Number",
          "description": "Collector number as printed, e.g. `001/102`, `OP01-012`."
        },
        "rarity": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Rarity",
          "description": "Rarity label as printed on the card or as given by the source, in the card language, e.g. `Illustration spéciale rare`, `SuperRare`."
        },
        "rarity_code": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Rarity Code",
          "description": "Canonical rarity code, shared by every language of one rarity system, e.g. `special_illustration_rare`. Japanese and Chinese Pokémon prints follow their own system (`sar`, `ur`). `null` when the rarity is unknown. Codes of a game: `GET /data/v1/games/{game}/rarities`."
        },
        "language": {
          "type": "string",
          "enum": [
            "fr",
            "en",
            "ja",
            "zh",
            "de",
            "es",
            "it",
            "pt"
          ],
          "title": "Language",
          "description": "Language of the printed card."
        },
        "edition": {
          "$ref": "#/$defs/EditionRef"
        },
        "image_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Image Url"
        },
        "variants": {
          "items": {
            "type": "string",
            "enum": [
              "default",
              "foil"
            ]
          },
          "type": "array",
          "title": "Variants",
          "description": "Price variants tracked for this card: `default` (main printing) and, for games pricing foils separately, `foil`."
        },
        "cardmarket_product_id": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Cardmarket Product Id",
          "description": "Cardmarket idProduct; `null` on Sandbox and Starter."
        },
        "tcgplayer_product_id": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "US market product id",
          "description": "US market product id; `null` on Sandbox and Starter."
        }
      },
      "type": "object",
      "required": [
        "card_id",
        "game",
        "name",
        "number",
        "language",
        "edition",
        "variants"
      ],
      "title": "CardSummary"
    },
    "ConditionPrice": {
      "properties": {
        "condition": {
          "type": "string",
          "enum": [
            "NM",
            "EX",
            "GD",
            "LP",
            "PL",
            "PO"
          ],
          "title": "Condition"
        },
        "amount": {
          "type": "number",
          "title": "Amount",
          "description": "Cheapest French-language offer in this condition, in EUR."
        }
      },
      "type": "object",
      "required": [
        "condition",
        "amount"
      ],
      "title": "ConditionPrice"
    },
    "EditionRef": {
      "properties": {
        "id": {
          "type": "integer",
          "title": "Id",
          "description": "Edition id, usable as `edition_id` filter."
        },
        "name": {
          "type": "string",
          "title": "Name"
        },
        "code": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Code",
          "description": "Publisher set code, e.g. `SV06`, `OP-01`."
        },
        "release_date": {
          "anyOf": [
            {
              "type": "string",
              "format": "date"
            },
            {
              "type": "null"
            }
          ],
          "title": "Release Date"
        }
      },
      "type": "object",
      "required": [
        "id",
        "name"
      ],
      "title": "EditionRef"
    },
    "GradedPrices": {
      "properties": {
        "currency": {
          "type": "string",
          "const": "EUR",
          "title": "Currency",
          "default": "EUR"
        },
        "collection": {
          "type": "string",
          "const": "best_effort",
          "title": "Collection",
          "default": "best_effort"
        },
        "quotes": {
          "items": {
            "$ref": "#/$defs/GradedQuote"
          },
          "type": "array",
          "title": "Quotes"
        }
      },
      "type": "object",
      "required": [
        "quotes"
      ],
      "title": "GradedPrices"
    },
    "GradedQuote": {
      "properties": {
        "grade": {
          "type": "integer",
          "enum": [
            9,
            10
          ],
          "title": "Grade",
          "description": "Exact numeric grade, all grading companies combined."
        },
        "window_days": {
          "type": "integer",
          "enum": [
            30,
            90
          ],
          "title": "Window Days"
        },
        "amount": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Amount",
          "description": "Median sold price in EUR; `null` unless `status` is `available`."
        },
        "sales_count": {
          "type": "integer",
          "title": "Sales Count"
        },
        "status": {
          "type": "string",
          "enum": [
            "available",
            "stale",
            "insufficient_sample",
            "missing"
          ],
          "title": "Status",
          "description": "`insufficient_sample` when fewer than 3 sales over 90 days."
        }
      },
      "type": "object",
      "required": [
        "grade",
        "window_days",
        "amount",
        "sales_count",
        "status"
      ],
      "title": "GradedQuote"
    },
    "PopulationReport": {
      "properties": {
        "grader": {
          "type": "string",
          "enum": [
            "psa",
            "ccc"
          ],
          "title": "Grader"
        },
        "label": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Label",
          "description": "Print specificity, e.g. `1st Edition`, `Holo`."
        },
        "grades": {
          "additionalProperties": {
            "type": "integer"
          },
          "type": "object",
          "title": "Grades",
          "description": "Graded copies per grade, e.g. `{\"10\": 312, \"9.5\": 40}`."
        },
        "total": {
          "type": "integer",
          "title": "Total"
        },
        "scraped_at": {
          "type": "string",
          "format": "date-time",
          "title": "Scraped At",
          "description": "When the grader report was read."
        }
      },
      "type": "object",
      "required": [
        "grader",
        "grades",
        "total",
        "scraped_at"
      ],
      "title": "PopulationReport"
    },
    "PriceChange": {
      "properties": {
        "period_days": {
          "type": "integer",
          "enum": [
            7,
            30,
            90
          ],
          "title": "Period Days"
        },
        "change_pct": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Change Pct",
          "description": "Price change over the period in %; `null` without enough data."
        },
        "source": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "cardmarket",
                "us_market",
                "ebay"
              ]
            },
            {
              "type": "null"
            }
          ],
          "title": "Source",
          "description": "Single source of the change: eBay when 4 sales at least in the period, else the US market, else Cardmarket (as the ValoTCG Trending)."
        }
      },
      "type": "object",
      "required": [
        "period_days",
        "change_pct",
        "source"
      ],
      "title": "PriceChange"
    },
    "PriceQuote": {
      "properties": {
        "source": {
          "type": "string",
          "enum": [
            "cardmarket",
            "us_market",
            "ebay"
          ],
          "title": "Source"
        },
        "metric": {
          "type": "string",
          "enum": [
            "trend",
            "low",
            "market",
            "sold_median_raw"
          ],
          "title": "Metric",
          "description": "`trend` and `low` (Cardmarket), `market` (US market, USD), `sold_median_raw` (eBay sold, ungraded)."
        },
        "amount": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Amount",
          "description": "Price in `currency`; `null` whenever `status` is not `available`."
        },
        "currency": {
          "type": "string",
          "enum": [
            "EUR",
            "USD"
          ],
          "title": "Currency",
          "description": "Native currency of the source; never converted."
        },
        "variant": {
          "type": "string",
          "enum": [
            "default",
            "foil"
          ],
          "title": "Variant"
        },
        "card_language": {
          "type": "string",
          "enum": [
            "fr",
            "en",
            "ja",
            "zh",
            "de",
            "es",
            "it",
            "pt"
          ],
          "title": "Card Language"
        },
        "market_language": {
          "type": "string",
          "enum": [
            "fr",
            "en",
            "global"
          ],
          "title": "Market Language",
          "description": "Language of the listings behind the price: `fr` for French Cardmarket listings, `en` for the US market, `global` for language-agnostic markets."
        },
        "observed_at": {
          "anyOf": [
            {
              "type": "string",
              "format": "date"
            },
            {
              "type": "null"
            }
          ],
          "title": "Observed At",
          "description": "Date the source observed this price (not the recompute date)."
        },
        "computed_at": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time"
            },
            {
              "type": "null"
            }
          ],
          "title": "Computed At",
          "description": "When Valo.Data last recomputed the snapshot."
        },
        "status": {
          "type": "string",
          "enum": [
            "available",
            "stale",
            "insufficient_sample",
            "missing"
          ],
          "title": "Status",
          "description": "`stale`: Cardmarket/US market observation older than 48 h (35 days for French Cardmarket listings, scraped weekly at best). `insufficient_sample`: fewer than 3 eBay sales in the window. `missing`: no observation."
        },
        "reason": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Reason",
          "description": "Machine readable cause when not `available`."
        },
        "window_days": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Window Days",
          "description": "eBay only: sales window in days."
        },
        "sales_count": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Sales Count",
          "description": "eBay only: sales in the window."
        },
        "collection": {
          "anyOf": [
            {
              "type": "string",
              "const": "best_effort"
            },
            {
              "type": "null"
            }
          ],
          "title": "Collection",
          "description": "eBay only: sales are collected on a best effort basis."
        },
        "last_collected_at": {
          "anyOf": [
            {
              "type": "string",
              "format": "date"
            },
            {
              "type": "null"
            }
          ],
          "title": "Last Collected At",
          "description": "eBay only: latest sale day collected."
        },
        "condition": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "NM",
                "EX",
                "GD",
                "LP",
                "PL",
                "PO"
              ]
            },
            {
              "type": "null"
            }
          ],
          "title": "Condition",
          "description": "French Cardmarket listings only: condition of the offer behind `amount`."
        },
        "conditions": {
          "anyOf": [
            {
              "items": {
                "$ref": "#/$defs/ConditionPrice"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Conditions",
          "description": "French Cardmarket listings only: cheapest offer per condition in the same scrape, best condition first; `null` whenever `amount` is `null`."
        }
      },
      "type": "object",
      "required": [
        "source",
        "metric",
        "amount",
        "currency",
        "variant",
        "card_language",
        "market_language",
        "observed_at",
        "computed_at",
        "status"
      ],
      "title": "PriceQuote"
    },
    "RecommendedPrice": {
      "properties": {
        "amount": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Amount",
          "description": "The price the ValoTCG app displays, in EUR; `null` when no source qualifies."
        },
        "currency": {
          "type": "string",
          "const": "EUR",
          "title": "Currency",
          "default": "EUR"
        },
        "source": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "ebay_30d",
                "ebay_3m",
                "cardmarket",
                "us_market"
              ]
            },
            {
              "type": "null"
            }
          ],
          "title": "Source",
          "description": "`ebay_30d` / `ebay_3m`: median of eBay sales (4 sales at least; 2 for sealed products), `cardmarket`: French offer, then trend, then low, `us_market`: US market price converted to EUR."
        },
        "observed_at": {
          "anyOf": [
            {
              "type": "string",
              "format": "date"
            },
            {
              "type": "null"
            }
          ],
          "title": "Observed At",
          "description": "Date the retained source observed this price."
        },
        "window_days": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Window Days",
          "description": "eBay only: sales window in days."
        },
        "sales_count": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Sales Count",
          "description": "eBay only: sales in the window."
        },
        "confidence": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "high",
                "medium",
                "low"
              ]
            },
            {
              "type": "null"
            }
          ],
          "title": "Confidence",
          "description": "Reliability level of this price in the ValoTCG app: sample size, freshness and agreement between sources."
        },
        "fx_rate": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Fx Rate",
          "description": "US market only: USD→EUR rate applied (ECB)."
        },
        "fx_rate_date": {
          "anyOf": [
            {
              "type": "string",
              "format": "date"
            },
            {
              "type": "null"
            }
          ],
          "title": "Fx Rate Date",
          "description": "US market only: day of that rate."
        }
      },
      "type": "object",
      "required": [
        "amount",
        "source",
        "observed_at"
      ],
      "title": "RecommendedPrice"
    },
    "RetailPrice": {
      "properties": {
        "amount": {
          "type": "number",
          "title": "Amount",
          "description": "Launch retail price, in `currency`."
        },
        "currency": {
          "type": "string",
          "enum": [
            "EUR",
            "USD",
            "JPY"
          ],
          "title": "Currency",
          "description": "Currency of the product's own market (EUR for French, USD for English, JPY for Japanese), never converted."
        },
        "source": {
          "type": "string",
          "enum": [
            "estimated",
            "verified"
          ],
          "title": "Source",
          "description": "`estimated` from the product type, name and release period; `verified` checked product by product."
        }
      },
      "type": "object",
      "required": [
        "amount",
        "currency",
        "source"
      ],
      "title": "RetailPrice"
    },
    "SealedSummary": {
      "properties": {
        "sealed_id": {
          "type": "integer",
          "title": "Sealed Id",
          "description": "Stable Valo.Data sealed product id (`sealed:{id}` in batches)."
        },
        "game": {
          "type": "string",
          "title": "Game"
        },
        "name": {
          "type": "string",
          "title": "Name"
        },
        "product_type": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Product Type",
          "description": "e.g. booster, display, etb, starter_deck."
        },
        "language": {
          "type": "string",
          "enum": [
            "fr",
            "en",
            "ja",
            "zh",
            "de",
            "es",
            "it",
            "pt"
          ],
          "title": "Language"
        },
        "edition": {
          "anyOf": [
            {
              "$ref": "#/$defs/EditionRef"
            },
            {
              "type": "null"
            }
          ]
        },
        "release_date": {
          "anyOf": [
            {
              "type": "string",
              "format": "date"
            },
            {
              "type": "null"
            }
          ],
          "title": "Release Date"
        },
        "msrp": {
          "anyOf": [
            {
              "$ref": "#/$defs/RetailPrice"
            },
            {
              "type": "null"
            }
          ],
          "description": "Launch retail price (MSRP) on the product's market; `null` when unknown."
        },
        "image_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Image Url"
        },
        "slug": {
          "type": "string",
          "title": "Slug",
          "description": "Slug of the product's page on valotcg.com."
        },
        "cardmarket_product_id": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Cardmarket Product Id",
          "description": "Cardmarket idProduct; `null` on Sandbox and Starter."
        },
        "tcgplayer_product_id": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "US market product id",
          "description": "US market product id; `null` on Sandbox and Starter."
        }
      },
      "type": "object",
      "required": [
        "sealed_id",
        "game",
        "name",
        "language",
        "slug"
      ],
      "title": "SealedSummary"
    }
  }
}