{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://openoutcry.dev/contract/v1/observation.schema.json",
"title": "MarketObservation",
"description": "What an agent sees at one point-in-time decision step. All data is point-in-time: close_history, fundamentals and news only ever hold information available at or before `date`. OpenOutcry Agent Interface v1.0.",
"type": "object",
"required": ["date", "cash", "symbols", "portfolio"],
"additionalProperties": false,
"properties": {
"date": {
"type": "string",
"description": "ISO-8601 date of the decision point."
},
"cash": {
"type": "number",
"description": "Cash available to the agent."
},
"symbols": {
"type": "array",
"description": "Point-in-time snapshot per tradable instrument.",
"items": { "$ref": "#/$defs/SymbolSnapshot" }
},
"portfolio": {
"type": "array",
"description": "The agent's current holdings.",
"items": { "$ref": "#/$defs/PositionState" }
}
},
"$defs": {
"SymbolSnapshot": {
"type": "object",
"required": ["symbol", "close_history"],
"additionalProperties": false,
"properties": {
"symbol": { "type": "string" },
"close_history": {
"type": "array",
"description": "Trailing closes up to and including `date` (oldest first).",
"items": { "type": "number" }
},
"fundamentals": {
"type": "object",
"description": "Named fundamental fields (e.g. `pe`, `revenue_yoy`). Optional; defaults to empty.",
"additionalProperties": { "type": "number" }
},
"news": {
"type": "array",
"description": "Headlines published on or before `date`. Optional; defaults to empty.",
"items": { "type": "string" }
}
}
},
"PositionState": {
"type": "object",
"required": ["symbol", "shares", "avg_price"],
"additionalProperties": false,
"properties": {
"symbol": { "type": "string" },
"shares": { "type": "number" },
"avg_price": { "type": "number" }
}
}
}
}