---
name: metabase_validate_dashboard_payload
kind: function
lang: py
domain: infra
version: "1.0.0"
purity: pure
signature: "def metabase_validate_dashboard_payload(payload: dict, known_card_ids: set[int]) -> list[str]"
description: "Valida la estructura de un payload de dashboard de Metabase sin red. Verifica campos obligatorios, bounds de dashcards, referencias a cards conocidas y solapamientos entre dashcards. Acumula todos los issues."
tags: [metabase, validation, dashboard, dashcard, overlap, pure, pre-flight, structural]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: ""
imports: []
params:
  - name: payload
    desc: "dict con los campos del dashboard a validar: name, dashcards (opcional), tabs (opcional), parameters (opcional)"
  - name: known_card_ids
    desc: "conjunto de IDs enteros de cards que existen en Metabase; las dashcards con card_id entero deben referenciar un ID de este conjunto. Pasar set vacio si no se quiere verificar referencias."
output: "lista de strings describiendo cada issue encontrado; lista vacia indica payload valido listo para enviarse a PUT /api/dashboard/:id"
tested: true
tests:
  - "dashboard valido sin dashcards"
  - "dashboard valido con dashcards"
  - "dashboard card id desconocido"
  - "dashboard card virtual null permitido"
  - "dashboard dashcards solapadas"
  - "dashboard dashcards adyacentes no solapan"
  - "dashboard col fuera de bounds"
  - "dashboard col mas size x excede grid"
  - "dashboard size y fuera de bounds"
  - "dashboard name ausente"
  - "dashboard tabs invalidos"
  - "dashboard parameters no list"
test_file_path: "python/functions/metabase/validation_test.py"
file_path: "python/functions/metabase/validation.py"
---

## Ejemplo

```python
known_ids = {c["id"] for c in metabase_list_cards(client)}
issues = metabase_validate_dashboard_payload(dashboard_payload, known_card_ids=known_ids)
if issues:
    print("Dashboard invalido:")
    for issue in issues:
        print(f"  - {issue}")
else:
    metabase_update_dashboard(client, dashboard_id, **dashboard_payload)
```

## Notas

Bounds del grid de Metabase:
- `col` in [0, 23], `row` >= 0
- `size_x` in [1, 24], `size_y` in [1, 100]
- `col + size_x <= 24` (no exceder el ancho del grid)

Deteccion de solapamientos: O(n^2) sobre pares de dashcards. Optimo para dashboards tipicos (< 50 cards).

Dashcards con `card_id = null` son virtuales (texto, headings, iframes) y se permiten sin verificar contra known_card_ids.