CreateEventBlockRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/robosystems-ai/json-schema/robosystems-ai-create-event-block-request-schema.json",
  "title": "CreateEventBlockRequest",
  "description": "Write surface for a single business event.",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/robosystems-ai-openapi.json#/components/schemas/CreateEventBlockRequest",
  "properties": {
    "entity_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Entity Id",
      "description": "The entity whose books the event lands in, by id; every GL row its handler writes follows it. Omit for the group parent."
    },
    "event_type": {
      "type": "string",
      "title": "Event Type",
      "description": "Open vocabulary: 'invoice_issued' | 'contract_signed' | 'bank_transaction' | ..."
    },
    "event_category": {
      "type": "string",
      "enum": [
        "sales",
        "purchase",
        "financing",
        "payroll",
        "treasury",
        "adjustment",
        "recognition",
        "other",
        "control",
        "approval",
        "reconciliation",
        "inquiry"
      ],
      "title": "Event Category",
      "description": "REA classification. Economic categories (sales, purchase, financing, payroll, treasury, adjustment, recognition, other) require event_class='economic'. Support categories (control, approval, reconciliation, inquiry) require event_class='support'. The DB CHECK rejects mismatched pairings."
    },
    "event_class": {
      "type": "string",
      "enum": [
        "economic",
        "support"
      ],
      "title": "Event Class",
      "description": "REA event class. 'economic' events change resources and drive GL postings; 'support' events are audit-trail / value-chain primitives (typically captured with apply_handlers=False).",
      "default": "economic"
    },
    "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": "Canonical action verb refining `event_category`. Disambiguates concepts ERPs collapse: `transferAllRights` (ownership transfer, no physical movement) vs `transferCustody` (physical only, no rights transfer) — load-bearing for consignment, drop-shipping, marketplace settlement, escrow. Optional; null is valid for legacy events and during adapter rollout."
    },
    "agent_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Agent Id",
      "description": "ID of the counterparty agent (customer, vendor, employee, lender) involved in the event. `null` for internal-only events."
    },
    "resource_type": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "goods",
            "services",
            "money",
            "right",
            "obligation",
            "information",
            "labor"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Resource Type",
      "description": "REA resource kind being exchanged. One of: `goods`, `services`, `money`, `right`, `obligation`, `information`, `labor`."
    },
    "resource_element_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Resource Element Id",
      "description": "ID of the specific element being exchanged, when known (e.g. the cash account for a treasury movement, the inventory item for a sale)."
    },
    "occurred_at": {
      "type": "string",
      "format": "date-time",
      "title": "Occurred At",
      "description": "When the event happened in the real world"
    },
    "effective_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Effective At",
      "description": "Accounting recognition date, if different from occurred_at"
    },
    "due_date": {
      "anyOf": [
        {
          "type": "string",
          "format": "date"
        },
        {
          "type": "null"
        }
      ],
      "title": "Due Date",
      "description": "When an obligation falls due: an `invoice_issued` or a `bill_received`. Give it, or `terms_days`; with neither, the obligation is due on receipt. Refused on any other event type."
    },
    "terms_days": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 3650.0,
          "minimum": 0.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Terms Days",
      "description": "Net terms in days from `occurred_at` (30 for net 30), in place of `due_date`. Only on an `invoice_issued` or a `bill_received`."
    },
    "source": {
      "type": "string",
      "title": "Source",
      "description": "'manual' | 'system' | 'schedule', a connected provider name (e.g. 'quickbooks'), or a source_name registered via an 'external' connection. Validated against the graph's registered connections."
    },
    "external_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "External Id",
      "description": "Source-system dedup key. (source, external_id) is enforced unique when external_id is provided, so retries from external adapters are idempotent at the DB level."
    },
    "external_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "External Url",
      "description": "Deep link back to source-system record"
    },
    "amount": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Amount",
      "description": "Economic value of the event in **cents** of `currency`, signed. Sign convention follows the perspective of the entity that owns the graph: inflows positive, outflows negative. `null` for non-economic events (e.g. `event_class='support'`)."
    },
    "currency": {
      "type": "string",
      "title": "Currency",
      "description": "ISO 4217 currency code for `amount`.",
      "default": "USD"
    },
    "description": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Description",
      "description": "Free-text human-readable summary of the event."
    },
    "metadata": {
      "additionalProperties": true,
      "type": "object",
      "title": "Metadata",
      "description": "Free-form payload, opaque to the event surface. When `apply_handlers=True`, the matched handler's metadata schema validates this dict — required keys depend on the handler registered for `event_type`. Use `preview-event-block` to discover the expected shape without writing."
    },
    "dimension_ids": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "title": "Dimension Ids",
      "description": "Management dimension members tagging this event (department, class, location, project), one per axis. Every line its handler writes carries them on the axes the line does not tag itself."
    },
    "obligated_by_event_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Obligated By Event Id",
      "description": "Forward-materialization link: the event that scheduled or obligated this one (e.g. depreciation entries point at the asset_acquired event)."
    },
    "discharges_event_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Discharges Event Id",
      "description": "Settlement link: the obligation this event discharges (e.g. cash_received pointing at the originating sale_invoiced)."
    },
    "document_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Document Id",
      "description": "The stored document this event rests on, as evidence: the invoice PDF, the vendor bill, the receipt photo (upload it with create-document-upload and complete-document-upload). Must be a document on this graph. While the event is live, the document cannot be deleted."
    },
    "apply_handlers": {
      "type": "boolean",
      "title": "Apply Handlers",
      "description": "When True, resolves the event_type to a handler (Python registry first, then DSL) and fires it atomically with event creation.",
      "default": false
    }
  },
  "type": "object",
  "required": [
    "event_type",
    "event_category",
    "occurred_at",
    "source"
  ]
}