quant-os/schemas/order_event.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://boat.local/quant60/schemas/order_event.schema.json",
  "title": "Quant60 normalized ledger replay event",
  "description": "Canonical JSON envelope consumed by LedgerProjector for ORDER_STATUS and FILL events. It is the LedgerRecord.as_dict shape emitted by SimBroker; previous_hash and hash are optional only for explicitly ordered, unhashed replay fixtures.",
  "$comment": "The canonical payload names are quantity and filled_quantity. Python compatibility aliases accepted by LedgerProjector are intentionally not part of this wire contract.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "sequence",
    "timestamp",
    "event_id",
    "event_type",
    "payload"
  ],
  "properties": {
    "sequence": {
      "type": "integer",
      "minimum": 1
    },
    "timestamp": {
      "type": "string",
      "format": "date-time"
    },
    "event_id": {
      "type": "string",
      "minLength": 1
    },
    "event_type": {
      "type": "string",
      "enum": [
        "ORDER_STATUS",
        "FILL"
      ]
    },
    "payload": {
      "type": "object"
    },
    "previous_hash": {
      "$ref": "#/$defs/sha256"
    },
    "hash": {
      "$ref": "#/$defs/sha256"
    }
  },
  "dependentRequired": {
    "previous_hash": [
      "hash"
    ],
    "hash": [
      "previous_hash"
    ]
  },
  "oneOf": [
    {
      "title": "ORDER_STATUS ledger envelope",
      "required": [
        "event_type",
        "payload"
      ],
      "properties": {
        "event_type": {
          "const": "ORDER_STATUS"
        },
        "payload": {
          "$ref": "#/$defs/order_status_payload"
        }
      }
    },
    {
      "title": "FILL ledger envelope",
      "required": [
        "event_type",
        "payload"
      ],
      "properties": {
        "event_type": {
          "const": "FILL"
        },
        "payload": {
          "$ref": "#/$defs/fill_payload"
        }
      }
    }
  ],
  "$defs": {
    "sha256": {
      "type": "string",
      "pattern": "^[0-9a-f]{64}$"
    },
    "canonical_symbol": {
      "type": "string",
      "pattern": "^[0-9]{6}\\.(XSHG|XSHE|XBSE)$"
    },
    "side": {
      "type": "string",
      "enum": [
        "BUY",
        "SELL"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "NEW",
        "ACCEPTED",
        "PARTIALLY_FILLED",
        "FILLED",
        "CANCEL_PENDING",
        "CANCELLED",
        "REJECTED",
        "UNKNOWN"
      ]
    },
    "decimal": {
      "oneOf": [
        {
          "type": "number"
        },
        {
          "type": "string",
          "pattern": "^-?(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?$"
        }
      ]
    },
    "nonnegative_decimal": {
      "oneOf": [
        {
          "type": "number",
          "minimum": 0
        },
        {
          "type": "string",
          "pattern": "^(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?$"
        }
      ]
    },
    "positive_decimal": {
      "oneOf": [
        {
          "type": "number",
          "exclusiveMinimum": 0
        },
        {
          "type": "string",
          "pattern": "^(?:[1-9][0-9]*(?:\\.[0-9]+)?|0\\.[0-9]*[1-9][0-9]*)$"
        }
      ]
    },
    "order_status_payload": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "order_id",
        "symbol",
        "side",
        "quantity",
        "filled_quantity",
        "status"
      ],
      "properties": {
        "order_id": {
          "type": "string",
          "minLength": 1
        },
        "broker_order_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "symbol": {
          "$ref": "#/$defs/canonical_symbol"
        },
        "side": {
          "$ref": "#/$defs/side"
        },
        "quantity": {
          "type": "integer",
          "minimum": 1
        },
        "filled_quantity": {
          "type": "integer",
          "minimum": 0
        },
        "average_fill_price": {
          "$ref": "#/$defs/nonnegative_decimal"
        },
        "status": {
          "$ref": "#/$defs/status"
        },
        "reason": {
          "type": [
            "string",
            "null"
          ]
        },
        "submitted_at": {
          "type": "string",
          "format": "date"
        },
        "metadata": {
          "type": "object"
        }
      }
    },
    "fill_payload": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "fill_id",
        "order_id",
        "symbol",
        "side",
        "quantity",
        "price"
      ],
      "properties": {
        "fill_id": {
          "type": "string",
          "minLength": 1
        },
        "order_id": {
          "type": "string",
          "minLength": 1
        },
        "trading_date": {
          "type": "string",
          "format": "date"
        },
        "symbol": {
          "$ref": "#/$defs/canonical_symbol"
        },
        "side": {
          "$ref": "#/$defs/side"
        },
        "quantity": {
          "type": "integer",
          "minimum": 1
        },
        "price": {
          "$ref": "#/$defs/positive_decimal"
        },
        "commission": {
          "$ref": "#/$defs/nonnegative_decimal"
        },
        "stamp_duty": {
          "$ref": "#/$defs/nonnegative_decimal"
        },
        "transfer_fee": {
          "$ref": "#/$defs/nonnegative_decimal"
        },
        "cash_delta": {
          "$ref": "#/$defs/decimal"
        }
      }
    }
  }
}