{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/placementapi-com/json-schema/placementapi-com-basket-compare-request-schema.json",
  "title": "BasketCompareRequest",
  "description": "A captured basket for POST /v1/baskets/compare, built by the Perch extension or the hosted compare-basket page and posted unchanged. The panel is strict: an unrecognised field is refused rather than ignored, so a partly understood basket cannot be compared as though it were complete. Nothing here is stored.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/placementapi-com-comparison-api-openapi.yml#/components/schemas/BasketCompareRequest",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "lines"
  ],
  "properties": {
    "lines": {
      "type": "array",
      "minItems": 1,
      "maxItems": 100,
      "description": "1..100 captured placements. Every `id` must be unique within the request.",
      "items": {
        "$ref": "#/$defs/BasketCompareLineInput"
      }
    },
    "basket_adjustment_usd_minor": {
      "type": "integer",
      "default": 0,
      "minimum": -1000000000,
      "maximum": 1000000000,
      "description": "Whole-basket discount (negative) or surcharge (positive) in USD minor units, applied only to the whole-basket saving. It is never folded into the per-line or matched-line figures, and a discount may not push a fully known source total below zero."
    }
  },
  "$defs": {
    "BasketCompareLineInput": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "domain",
        "placement_type",
        "quantity",
        "observed_unit_usd_minor",
        "currency",
        "writing",
        "link_attribute",
        "source_all_in"
      ],
      "description": "One captured row. Terms the capture could not determine are carried as `unknown`; they are never filled in with a default.",
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200,
          "description": "Caller-chosen line id, echoed on the result. Unique within the request; a repeat is a 400 `duplicate_line_id`."
        },
        "domain": {
          "type": "string",
          "minLength": 1,
          "maxLength": 253,
          "description": "The captured domain or URL. A scheme or path is tolerated; it is canonicalised to the same site id the catalogue uses, so `www.` and `blog.` are never confused."
        },
        "placement_type": {
          "type": "string",
          "minLength": 1,
          "maxLength": 40,
          "description": "Only `guest_post`, `niche_edit` and `link_insert` are compared. Any other value is answered on the line as `unsupported` rather than failing the whole request, so one odd row does not sink the basket."
        },
        "quantity": {
          "type": "integer",
          "minimum": 1,
          "maximum": 20,
          "description": "Placements for this line. Retained exactly; no deduplication that would drop multiple placements."
        },
        "observed_unit_usd_minor": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 1,
          "maximum": 1000000000,
          "description": "The captured unit price in USD minor units (cents), or null when the capture had no unambiguous USD price. Null (or any non-USD `currency`) makes the line ineligible for a numeric saving while still returning the comparison. Bounded so every aggregate is an exact safe integer; out of range is a 400, never clamped."
        },
        "currency": {
          "type": "string",
          "minLength": 1,
          "maxLength": 10,
          "description": "The captured ISO 4217 code, upper-cased by the engine. Anything other than `USD` stays visible but is not converted — no exchange rate is invented — and is ineligible for a numeric saving."
        },
        "writing": {
          "type": "string",
          "enum": [
            "included",
            "supplied",
            "unknown"
          ],
          "description": "Who provides the article. `unknown` never matches a known offer term and never becomes a default."
        },
        "link_attribute": {
          "type": "string",
          "enum": [
            "dofollow",
            "nofollow",
            "sponsored",
            "unknown"
          ],
          "description": "The captured link attribute. `unknown` never matches; `sponsored` is honoured as captured and never inferred on the offer side."
        },
        "source_all_in": {
          "type": "boolean",
          "description": "Whether the captured price already includes every fee. A line that is not flagged all-in withholds a numeric saving rather than possibly overstating it; it never disqualifies the line from being shown."
        }
      }
    }
  }
}