{
  "$defs": {
    "CoordSummary": {
      "additionalProperties": false,
      "description": "Metadata summary of one coordinate (never the full array for large dims).\n\n``values`` lists categorical levels when there are at most :attr:`MAX_LEVELS` of them;\nordered dims (time/integer) describe a range by ``start``/``end``/``size`` and whether\nthe coordinate is ``contiguous`` (no gaps at its frequency/step).",
      "properties": {
        "contiguous": {
          "default": true,
          "title": "Contiguous",
          "type": "boolean"
        },
        "end": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "integer"
            },
            {
              "type": "number"
            },
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "End"
        },
        "freq": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Freq"
        },
        "kind": {
          "enum": [
            "categorical",
            "time",
            "integer",
            "float",
            "index"
          ],
          "title": "Kind",
          "type": "string"
        },
        "size": {
          "minimum": 0,
          "title": "Size",
          "type": "integer"
        },
        "start": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "integer"
            },
            {
              "type": "number"
            },
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Start"
        },
        "step": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Step"
        },
        "values": {
          "anyOf": [
            {
              "items": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "integer"
                  },
                  {
                    "type": "number"
                  },
                  {
                    "type": "boolean"
                  }
                ]
              },
              "maxItems": 10000,
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Values"
        }
      },
      "required": [
        "kind",
        "size"
      ],
      "title": "CoordSummary",
      "type": "object"
    },
    "DataSchema": {
      "additionalProperties": false,
      "description": "Schema of an ``xr.Dataset``: dims, variables, layout and ragged structure.",
      "properties": {
        "dims": {
          "maxProperties": 256,
          "patternProperties": {
            "^[A-Za-z_][A-Za-z0-9_.\\-]{0,127}$": {
              "$ref": "#/$defs/DimSpec"
            }
          },
          "title": "Dims",
          "type": "object"
        },
        "layout": {
          "default": "dense",
          "enum": [
            "dense",
            "long"
          ],
          "title": "Layout",
          "type": "string"
        },
        "ragged": {
          "items": {
            "$ref": "#/$defs/RaggedSpec"
          },
          "maxItems": 32,
          "title": "Ragged",
          "type": "array"
        },
        "vars": {
          "maxProperties": 4096,
          "patternProperties": {
            "^[A-Za-z_][A-Za-z0-9_.\\-]{0,127}$": {
              "$ref": "#/$defs/VarSpec"
            }
          },
          "title": "Vars",
          "type": "object"
        }
      },
      "title": "DataSchema",
      "type": "object"
    },
    "DimPolicy": {
      "description": "What may happen to a dim's coordinates at score time.",
      "enum": [
        "fixed",
        "extend",
        "new_levels"
      ],
      "title": "DimPolicy",
      "type": "string"
    },
    "DimSpec": {
      "additionalProperties": false,
      "description": "A dimension and its score-time policy.",
      "properties": {
        "description": {
          "anyOf": [
            {
              "maxLength": 2000,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Description"
        },
        "freq": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Pandas-style frequency, e.g. 'W-SUN'",
          "title": "Freq"
        },
        "kind": {
          "enum": [
            "categorical",
            "time",
            "integer",
            "float",
            "index"
          ],
          "title": "Kind",
          "type": "string"
        },
        "max_extension": {
          "anyOf": [
            {
              "minimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Periods allowed past the fit",
          "title": "Max Extension"
        },
        "new_level_strategy": {
          "default": "error",
          "enum": [
            "error",
            "hyperprior",
            "pooled",
            "zero"
          ],
          "title": "New Level Strategy",
          "type": "string"
        },
        "ordered": {
          "default": false,
          "title": "Ordered",
          "type": "boolean"
        },
        "policy": {
          "$ref": "#/$defs/DimPolicy",
          "default": "fixed"
        }
      },
      "required": [
        "kind"
      ],
      "title": "DimSpec",
      "type": "object"
    },
    "EndpointSchemaSnapshot": {
      "description": "The input contract of the promoted version, frozen at promotion: what callers send.\n\n``input_schema`` is the schema at ``inputs_stage`` under the spec's canonical names\n(``data.bind`` applied: ``time``, ``y``), which inline payloads use; the runner renames\nthem to the dataset's own names before scoring. ``horizon_dim`` is the canonical name of\nthe dim a forecast extends. ``conditions_on_actuals``: forecasts can carry actuals\n(target values for periods after the fit) that the model updates its state with\n(:mod:`mapi_spec.actuals`); the server sets it from the capabilities of the plugin\nbuild that serves the endpoint now, not only from those at fit.",
      "examples": [
        {
          "fit_coords": {
            "channel": {
              "kind": "categorical",
              "size": 2,
              "values": [
                "search",
                "tv"
              ]
            },
            "date": {
              "end": "2025-12-30",
              "freq": "D",
              "kind": "time",
              "size": 730,
              "start": "2024-01-01"
            },
            "market": {
              "kind": "categorical",
              "size": 2,
              "values": [
                "de",
                "fr"
              ]
            }
          },
          "future_required": [
            "spend_local"
          ],
          "horizon_dim": "time",
          "input_schema": {
            "dims": {
              "channel": {
                "kind": "categorical"
              },
              "date": {
                "freq": "D",
                "kind": "time",
                "policy": "extend"
              },
              "market": {
                "kind": "categorical",
                "new_level_strategy": "pooled",
                "policy": "new_levels"
              }
            },
            "vars": {
              "revenue_local": {
                "dims": [
                  "market",
                  "date"
                ],
                "dtype": "float64",
                "role": "target"
              },
              "spend_local": {
                "dims": [
                  "market",
                  "channel",
                  "date"
                ],
                "dtype": "float64",
                "future_required": true,
                "role": "spend"
              }
            }
          },
          "inputs_stage": "raw",
          "representation": "draws",
          "schema_hash": "sha256:5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a",
          "score_modes": [
            "counterfactual",
            "evaluate",
            "forecast",
            "predict"
          ]
        }
      ],
      "properties": {
        "conditions_on_actuals": {
          "default": false,
          "title": "Conditions On Actuals",
          "type": "boolean"
        },
        "fit_coords": {
          "additionalProperties": {
            "$ref": "#/$defs/CoordSummary"
          },
          "title": "Fit Coords",
          "type": "object"
        },
        "future_required": {
          "items": {
            "type": "string"
          },
          "title": "Future Required",
          "type": "array"
        },
        "horizon_dim": {
          "anyOf": [
            {
              "pattern": "^[A-Za-z_][A-Za-z0-9_.\\-]{0,127}$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Horizon Dim"
        },
        "input_schema": {
          "$ref": "#/$defs/DataSchema"
        },
        "inputs_stage": {
          "default": "raw",
          "title": "Inputs Stage",
          "type": "string"
        },
        "representation": {
          "anyOf": [
            {
              "$ref": "#/$defs/Representation"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "schema_hash": {
          "pattern": "^sha256:[0-9a-f]{64}$",
          "title": "Schema Hash",
          "type": "string"
        },
        "score_modes": {
          "items": {
            "enum": [
              "predict",
              "forecast",
              "counterfactual",
              "simulate",
              "filter",
              "evaluate"
            ],
            "type": "string"
          },
          "title": "Score Modes",
          "type": "array"
        }
      },
      "required": [
        "input_schema",
        "schema_hash"
      ],
      "title": "EndpointSchemaSnapshot",
      "type": "object"
    },
    "InputTable": {
      "description": "An endpoint's inline input as one long table: a header row (:attr:`columns`, the\ncoordinate columns first), then one row per coordinate - the layout of a spreadsheet's\nInput sheet and of :func:`mapi_spec.xrjson.xrjson_from_rows`.\n\nFor a forecasting endpoint :attr:`rows` lists the periods after the fitted history (the\nother dims' first levels), every value empty: fill the target where you have actuals and\nleave it empty for the periods to forecast (:mod:`mapi_spec.actuals`). Dates are ISO\n``yyyy-MM-dd``.",
      "examples": [
        {
          "columns": [
            {
              "description": "The period (yyyy-MM-dd)",
              "freq": "MS",
              "name": "t",
              "role": "coord"
            },
            {
              "description": "The actual (leave empty for the periods to forecast)",
              "dims": [
                "t"
              ],
              "name": "y",
              "role": "target"
            },
            {
              "description": "Necessary on each period, also on the periods to forecast",
              "dims": [
                "t"
              ],
              "name": "price",
              "role": "driver"
            }
          ],
          "conditions_on_actuals": true,
          "horizon_dim": "t",
          "rows": [
            [
              "1961-01-01",
              null,
              null
            ],
            [
              "1961-02-01",
              null,
              null
            ]
          ]
        }
      ],
      "properties": {
        "columns": {
          "items": {
            "$ref": "#/$defs/InputTableColumn"
          },
          "maxItems": 300,
          "title": "Columns",
          "type": "array"
        },
        "conditions_on_actuals": {
          "default": false,
          "title": "Conditions On Actuals",
          "type": "boolean"
        },
        "horizon_dim": {
          "anyOf": [
            {
              "pattern": "^[A-Za-z_][A-Za-z0-9_.\\-]{0,127}$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Horizon Dim"
        },
        "rows": {
          "items": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                },
                {
                  "type": "number"
                },
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                }
              ]
            },
            "type": "array"
          },
          "maxItems": 200,
          "title": "Rows",
          "type": "array"
        }
      },
      "title": "InputTable",
      "type": "object"
    },
    "InputTableColumn": {
      "description": "One column of an :class:`InputTable`.",
      "properties": {
        "description": {
          "default": "",
          "maxLength": 500,
          "title": "Description",
          "type": "string"
        },
        "dims": {
          "description": "The dims a value column varies along",
          "items": {
            "pattern": "^[A-Za-z_][A-Za-z0-9_.\\-]{0,127}$",
            "type": "string"
          },
          "title": "Dims",
          "type": "array"
        },
        "freq": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "The frequency of a time coordinate",
          "title": "Freq"
        },
        "name": {
          "pattern": "^[A-Za-z_][A-Za-z0-9_.\\-]{0,127}$",
          "title": "Name",
          "type": "string"
        },
        "role": {
          "enum": [
            "coord",
            "target",
            "driver",
            "input"
          ],
          "title": "Role",
          "type": "string"
        }
      },
      "required": [
        "name",
        "role"
      ],
      "title": "InputTableColumn",
      "type": "object"
    },
    "JsonValue": {},
    "RaggedSpec": {
      "additionalProperties": false,
      "description": "Ragged nesting (``hh \u2192 trip``): long form (obs + index vars) or padded + mask.",
      "properties": {
        "form": {
          "enum": [
            "long",
            "padded"
          ],
          "title": "Form",
          "type": "string"
        },
        "group_dim": {
          "pattern": "^[A-Za-z_][A-Za-z0-9_.\\-]{0,127}$",
          "title": "Group Dim",
          "type": "string"
        },
        "mask_var": {
          "anyOf": [
            {
              "pattern": "^[A-Za-z_][A-Za-z0-9_.\\-]{0,127}$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Mask Var"
        },
        "within_dim": {
          "pattern": "^[A-Za-z_][A-Za-z0-9_.\\-]{0,127}$",
          "title": "Within Dim",
          "type": "string"
        }
      },
      "required": [
        "group_dim",
        "within_dim",
        "form"
      ],
      "title": "RaggedSpec",
      "type": "object"
    },
    "Representation": {
      "description": "How a model encodes uncertainty in its outputs.",
      "enum": [
        "draws",
        "quantiles",
        "interval",
        "point",
        "moments"
      ],
      "title": "Representation",
      "type": "string"
    },
    "Role": {
      "description": "What a variable means to a model.",
      "enum": [
        "target",
        "covariate",
        "media",
        "spend",
        "control",
        "index",
        "mask",
        "constant",
        "weight",
        "exposure"
      ],
      "title": "Role",
      "type": "string"
    },
    "VarSpec": {
      "additionalProperties": false,
      "description": "A data variable: its dims (by name), dtype, role, units and missingness.",
      "properties": {
        "bounds": {
          "anyOf": [
            {
              "maxItems": 2,
              "minItems": 2,
              "prefixItems": [
                {
                  "anyOf": [
                    {
                      "type": "number"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                {
                  "anyOf": [
                    {
                      "type": "number"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              ],
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Bounds"
        },
        "description": {
          "anyOf": [
            {
              "maxLength": 2000,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Description"
        },
        "dims": {
          "items": {
            "pattern": "^[A-Za-z_][A-Za-z0-9_.\\-]{0,127}$",
            "type": "string"
          },
          "title": "Dims",
          "type": "array"
        },
        "dtype": {
          "enum": [
            "float64",
            "float32",
            "int64",
            "int32",
            "uint8",
            "bool",
            "str",
            "datetime64[ns]"
          ],
          "title": "Dtype",
          "type": "string"
        },
        "future_required": {
          "default": false,
          "description": "Must be supplied over a forecast horizon",
          "title": "Future Required",
          "type": "boolean"
        },
        "index_of": {
          "anyOf": [
            {
              "pattern": "^[A-Za-z_][A-Za-z0-9_.\\-]{0,127}$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Long layout: this var indexes that dim",
          "title": "Index Of"
        },
        "missing": {
          "default": "forbid",
          "enum": [
            "forbid",
            "allow",
            "mask"
          ],
          "title": "Missing",
          "type": "string"
        },
        "missing_sentinel": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Missing Sentinel"
        },
        "role": {
          "$ref": "#/$defs/Role",
          "default": "covariate"
        },
        "units": {
          "anyOf": [
            {
              "maxLength": 64,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "pint-style, e.g. 'EUR'",
          "title": "Units"
        }
      },
      "required": [
        "dims",
        "dtype"
      ],
      "title": "VarSpec",
      "type": "object"
    }
  },
  "$id": "https://schemas.mapi.dev/v1/api-EndpointSchema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "description": "``GET /v1/endpoints/{alias}/schema``: what to send, with a ready example payload.",
  "examples": [
    {
      "alias": "geo-mmm-prod",
      "example": {
        "future_covariates": "carry_last",
        "horizon": {
          "dim": "time",
          "periods": 8
        },
        "mode": "forecast",
        "output": {
          "kind": "expected",
          "summary": [
            "mean",
            "hdi_90"
          ]
        }
      },
      "model_ref": "model://growth/eu-geo-mmm@v3",
      "ref": "endpoint://growth/geo-mmm-prod",
      "revision": 4,
      "snapshot": {
        "fit_coords": {
          "channel": {
            "kind": "categorical",
            "size": 2,
            "values": [
              "search",
              "tv"
            ]
          },
          "date": {
            "end": "2025-12-30",
            "freq": "D",
            "kind": "time",
            "size": 730,
            "start": "2024-01-01"
          },
          "market": {
            "kind": "categorical",
            "size": 2,
            "values": [
              "de",
              "fr"
            ]
          }
        },
        "future_required": [
          "spend_local"
        ],
        "horizon_dim": "time",
        "input_schema": {
          "dims": {
            "channel": {
              "kind": "categorical"
            },
            "date": {
              "freq": "D",
              "kind": "time",
              "policy": "extend"
            },
            "market": {
              "kind": "categorical",
              "new_level_strategy": "pooled",
              "policy": "new_levels"
            }
          },
          "vars": {
            "revenue_local": {
              "dims": [
                "market",
                "date"
              ],
              "dtype": "float64",
              "role": "target"
            },
            "spend_local": {
              "dims": [
                "market",
                "channel",
                "date"
              ],
              "dtype": "float64",
              "future_required": true,
              "role": "spend"
            }
          }
        },
        "inputs_stage": "raw",
        "representation": "draws",
        "schema_hash": "sha256:5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a5a",
        "score_modes": [
          "counterfactual",
          "evaluate",
          "forecast",
          "predict"
        ]
      }
    }
  ],
  "properties": {
    "actuals_example": {
      "anyOf": [
        {
          "additionalProperties": {
            "$ref": "#/$defs/JsonValue"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "For endpoints whose model conditions forecasts on actuals: a forecast call with inline data over the periods after the fit, the target empty (null). Fill the target with the actuals you have and leave it empty for the periods to forecast (example_actuals_call)",
      "title": "Actuals Example"
    },
    "alias": {
      "pattern": "^[a-z0-9](?:[a-z0-9_-]{0,126}[a-z0-9])?$",
      "title": "Alias",
      "type": "string"
    },
    "example": {
      "additionalProperties": {
        "$ref": "#/$defs/JsonValue"
      },
      "description": "An EndpointScoreCall body that validates against this endpoint",
      "title": "Example",
      "type": "object"
    },
    "input_table": {
      "anyOf": [
        {
          "$ref": "#/$defs/InputTable"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The inline input as a long table (a spreadsheet's Input sheet): the columns and, for forecasts, the periods after the fit to fill in (input_table)"
    },
    "max_inline_bytes": {
      "default": 5242880,
      "title": "Max Inline Bytes",
      "type": "integer"
    },
    "model_ref": {
      "title": "Model Ref",
      "type": "string"
    },
    "ref": {
      "title": "Ref",
      "type": "string"
    },
    "revision": {
      "minimum": 1,
      "title": "Revision",
      "type": "integer"
    },
    "snapshot": {
      "$ref": "#/$defs/EndpointSchemaSnapshot"
    }
  },
  "required": [
    "alias",
    "ref",
    "model_ref",
    "revision",
    "snapshot",
    "example"
  ],
  "title": "EndpointSchema",
  "type": "object",
  "x-mapi-contract-version": "0.2"
}