{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/robosystems-ai/json-schema/robosystems-ai-update-event-block-request-schema.json",
  "title": "UpdateEventBlockRequest",
  "description": "Status transitions and field corrections for an event block.\n\nAll fields except event_id are optional — only supplied fields are updated.",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/robosystems-ai-openapi.json#/components/schemas/UpdateEventBlockRequest",
  "properties": {
    "event_id": {
      "type": "string",
      "title": "Event Id",
      "description": "Target event ID."
    },
    "transition_to": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "classified",
            "committed",
            "pending",
            "fulfilled",
            "voided",
            "superseded"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Transition To",
      "description": "Status transition. Valid moves depend on current status: captured → classified | committed | voided | superseded; classified → committed | pending | fulfilled | voided | superseded; committed → pending | fulfilled | voided | superseded; pending → fulfilled | voided | superseded; fulfilled → voided | superseded. A retraction (voided, superseded) is final and is refused from any status once the event's ledger rows have posted or it has published to QuickBooks — reverse the posted entries instead. captured → classified records an account choice without posting (bank-feed lines: patch classified_element_id, or accept_suggestion: true, in the same call); the later commit fires the handler. Note: classified and fulfilled are otherwise set by handlers, not by callers, but the transition is allowed for corrections."
    },
    "superseded_by_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Superseded By Id",
      "description": "New event id that replaces this one. Required when transition_to='superseded'."
    },
    "description": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Description",
      "description": "Replacement free-text summary. Unset = unchanged; pass an empty string to clear."
    },
    "effective_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Effective At",
      "description": "New accounting recognition date. Unset = unchanged. Useful when an event was captured against the wrong period."
    },
    "due_date": {
      "anyOf": [
        {
          "type": "string",
          "format": "date"
        },
        {
          "type": "null"
        }
      ],
      "title": "Due Date",
      "description": "New due date of an obligation (an `invoice_issued` or a `bill_received`), such as an extension granted. Unset = unchanged. It moves no ledger row, so it is accepted in a closed period."
    },
    "metadata_patch": {
      "additionalProperties": true,
      "type": "object",
      "title": "Metadata Patch",
      "description": "Key-value pairs merged into existing metadata (additive patch, not replace)."
    },
    "event_action": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "produce",
            "raise",
            "consume",
            "lower",
            "use",
            "cite",
            "work",
            "deliverService",
            "pickup",
            "dropoff",
            "accept",
            "transferCustody",
            "transferAllRights",
            "transfer",
            "move",
            "modify",
            "combine",
            "separate",
            "copy"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Event Action",
      "description": "Set or correct the canonical action verb. Unset = unchanged. Useful when an adapter improvement makes a previously-NULL verb fillable, or when reclassifying after the fact."
    },
    "obligated_by_event_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Obligated By Event Id",
      "description": "Set/update the forward-materialization link."
    },
    "discharges_event_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Discharges Event Id",
      "description": "Set the settlement link: the one invoice or bill this payment settles, at its full amount; an empty string clears it. Replaces any `discharge_allocations`. Checked as they are."
    },
    "discharge_allocations": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/DischargeAllocation"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Discharge Allocations",
      "description": "What this payment settles, document by document: one row per invoice or bill with the positive cents applied to it, together at most the payment's amount (the rest is unapplied). Replaces any held; an empty list clears them, and the settlement link becomes the first row's. Each must be an obligation of this event's entity, not voided: an invoice for money in, a bill for money out. A person chooses them; the open items a bank line may settle are `dischargeCandidates` over GraphQL."
    },
    "document_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Document Id",
      "description": "Set or replace the stored document the event rests on; an empty string detaches it. Must be a document on this graph. Unset = unchanged."
    }
  },
  "type": "object",
  "required": [
    "event_id"
  ],
  "$defs": {
    "DischargeAllocation": {
      "properties": {
        "obligation_event_id": {
          "type": "string",
          "title": "Obligation Event Id",
          "description": "The `invoice_issued` or `bill_received` event it settles."
        },
        "amount": {
          "type": "integer",
          "exclusiveMinimum": 0.0,
          "title": "Amount",
          "description": "Positive cents of the payment applied to it."
        }
      },
      "type": "object",
      "required": [
        "obligation_event_id",
        "amount"
      ],
      "title": "DischargeAllocation",
      "description": "How much of a payment went to one invoice or bill."
    }
  }
}