PublishedDealChange

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/agentdeals-dev/json-schema/agentdeals-dev-published-deal-change-schema.json",
  "title": "PublishedDealChange",
  "description": "A change record as /api/changes serves it: every field of DealChange, plus a standing on every record rather than only on the ones we have withdrawn.",
  "x-generated": "2026-11-01",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/agentdeals-dev-openapi.json#/components/schemas/PublishedDealChange",
  "allOf": [
    {
      "$ref": "#/$defs/DealChange"
    },
    {
      "type": "object",
      "properties": {
        "standing": {
          "type": "string",
          "enum": [
            "in_force",
            "reversed",
            "retracted"
          ],
          "description": "Where the record stands with us. 'in_force' — the change happened and still holds. 'reversed' — it happened and has since been undone, so the record is true history. 'retracted' — the record was our error and we do not stand behind it. Read this rather than testing whether resolution is present: 'reversed' and 'retracted' are different answers to a reader asking whether to trust the record, and the presence of resolution flattens them into one."
        },
        "impact": {
          "type": "string",
          "enum": [
            "high",
            "medium",
            "low",
            "none"
          ],
          "description": "'none' whenever standing is 'retracted' — a record we have withdrawn describes no event, so it weighs nothing. Derived at the point of serving; the stored value is left alone."
        },
        "date_meaning": {
          "type": "string",
          "enum": [
            "effective",
            "discovered",
            "effective_by"
          ],
          "description": "What this record's date means. \"effective\": the day the change took effect. \"discovered\": the day we recorded the change; when it took effect is unknown. \"effective_by\": the latest day the change can have taken effect. Where archived copies of the vendor's page bracket a change, it is dated by the first copy that shows the new terms. Read this field, not date_source: date_source says who wrote the record, not what its date means."
        },
        "ends_a_free_tier": {
          "type": "boolean"
        },
        "listing_effect": {
          "type": "string",
          "enum": [
            "ends",
            "narrows",
            "none"
          ]
        },
        "archive_check": {
          "type": [
            "object",
            "null"
          ],
          "description": "Our check of this record against archived copies of the vendor's page (#1952). Absent where we have not checked the record. Only the outcome no_usable_capture changes how the record counts: it sets no caution or risky label, and where it is the only record that would, the vendor's rating is withheld (rating_withheld, reason unconfirmed) rather than reported as stable; a standing narrowing with it also withholds a favourable stability class; and our pages mark the record unconfirmed. Every other outcome leaves the record counting as it did before the check.",
          "properties": {
            "checked": {
              "type": "string",
              "format": "date",
              "description": "The day we ran the check."
            },
            "outcome": {
              "type": "string",
              "enum": [
                "vendor_changed",
                "ours",
                "removal_stated_before",
                "no_usable_capture",
                "text_day_unknown",
                "page_unreadable_today"
              ],
              "description": "'vendor_changed' — archived copies show the vendor's page changing. 'ours' — the archived copy from when our listing text was written already states what the record calls new, so the difference was in our text, not on the vendor's page. 'removal_stated_before' — that archived copy already states the removal, so the removal predates our text. 'no_usable_capture' — no archived copy could settle the record either way. 'text_day_unknown' — we do not know when our listing text was written, so there was no capture to compare. 'page_unreadable_today' — we could not read the vendor's page when we ran the check, so no comparison ran."
            },
            "brackets": {
              "type": "array",
              "description": "Where outcome is vendor_changed: each pair of archived copies between which the page changed, the last showing the old terms and the first showing the new. Where there is exactly one, date_meaning is effective_by: the change took effect after last_old and on or before date.",
              "items": {
                "type": "object",
                "properties": {
                  "last_old": {
                    "type": "string",
                    "format": "date",
                    "description": "The day of the last copy showing the old terms."
                  },
                  "first_new": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "date",
                    "description": "The day of the first copy showing the new terms, or null where only our own read of the page shows them."
                  },
                  "last_old_capture": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "uri",
                    "description": "That copy's address in the Internet Archive."
                  },
                  "first_new_capture": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "uri",
                    "description": "That copy's address in the Internet Archive."
                  }
                },
                "required": [
                  "last_old",
                  "first_new"
                ]
              }
            },
            "capture_day": {
              "type": [
                "string",
                "null"
              ],
              "format": "date",
              "description": "Where outcome is ours or removal_stated_before: the day of the archived copy from when our listing text was written."
            },
            "capture": {
              "type": [
                "string",
                "null"
              ],
              "format": "uri",
              "description": "That copy's address in the Internet Archive."
            },
            "stated_then": {
              "type": [
                "string",
                "null"
              ],
              "description": "The line in that copy that settled the check, as the copy prints it: the terms the record called new (ours), or the removal (removal_stated_before)."
            },
            "recorded_as": {
              "type": [
                "string",
                "null"
              ],
              "enum": [
                "free_tier_removed",
                "open_source_killed",
                "product_deprecated",
                "limits_reduced",
                "restriction",
                "pricing_restructured",
                "pricing_model_change",
                "limits_increased",
                "new_free_tier",
                "new_tier",
                "startup_program_expanded",
                "pricing_postponed",
                "rebranded",
                "record_corrected"
              ],
              "description": "Where outcome is ours: the change type our re-read recorded. The record's change_type is record_corrected."
            }
          },
          "required": [
            "checked",
            "outcome"
          ]
        }
      },
      "required": [
        "standing",
        "date_meaning",
        "ends_a_free_tier"
      ]
    }
  ],
  "$defs": {
    "ChangeResolution": {
      "type": [
        "object",
        "null"
      ],
      "description": "Present when the change this record describes is no longer in force. state is 'reversed' when the vendor ended it and 'retracted' when the record was our error. date is the day from which it stopped being in force, or the day we established that, whichever we can source. resolved_by names the change record that ended it, when one exists. A record carrying this field never rates the vendor.",
      "properties": {
        "state": {
          "type": "string",
          "enum": [
            "reversed",
            "retracted"
          ]
        },
        "date": {
          "type": "string",
          "format": "date"
        },
        "detail": {
          "type": "string"
        },
        "source_url": {
          "type": "string",
          "format": "uri"
        },
        "resolved_by": {
          "type": "object",
          "properties": {
            "vendor": {
              "type": "string"
            },
            "date": {
              "type": "string",
              "format": "date"
            },
            "change_type": {
              "type": "string"
            }
          }
        }
      },
      "required": [
        "state",
        "date"
      ]
    },
    "DealChange": {
      "type": "object",
      "properties": {
        "vendor": {
          "type": "string"
        },
        "change_type": {
          "type": "string",
          "enum": [
            "free_tier_removed",
            "open_source_killed",
            "product_deprecated",
            "limits_reduced",
            "restriction",
            "pricing_restructured",
            "pricing_model_change",
            "limits_increased",
            "new_free_tier",
            "new_tier",
            "startup_program_expanded",
            "pricing_postponed",
            "rebranded",
            "record_corrected"
          ]
        },
        "reports": {
          "type": "string",
          "enum": [
            "vendor_offer",
            "our_index"
          ],
          "description": "What the record is about. 'vendor_offer' — the vendor changed its own offer, and a vendor page is where that can be read. 'our_index' — we changed what we list while the vendor's offer stood still, so no vendor page evidences it and the record carries no source_url. Absent means vendor_offer. Filter these out of any figure you present as vendor market activity."
        },
        "date": {
          "type": "string",
          "format": "date"
        },
        "summary": {
          "type": "string"
        },
        "previous_state": {
          "type": "string"
        },
        "current_state": {
          "type": "string"
        },
        "tier_direction": {
          "type": "string",
          "enum": [
            "narrowed",
            "unchanged",
            "widened"
          ],
          "description": "Whether the tier we list is worse, the same, or better under current_state than it was under previous_state, judged with both in hand rather than read off change_type. Where it says the tier did not get worse we publish the record and take no risk verdict from it. Absent means we have not judged this record."
        },
        "impact": {
          "type": "string",
          "enum": [
            "high",
            "medium",
            "low"
          ]
        },
        "source_url": {
          "type": "string",
          "format": "uri"
        },
        "category": {
          "type": "string"
        },
        "alternatives": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "resolution": {
          "$ref": "#/$defs/ChangeResolution"
        }
      },
      "required": [
        "vendor",
        "change_type",
        "date",
        "summary",
        "previous_state",
        "current_state",
        "impact",
        "source_url",
        "category",
        "alternatives"
      ]
    }
  }
}