---
name: metabase_validate_document_payload
kind: function
lang: py
domain: infra
version: "1.0.0"
purity: pure
signature: "def metabase_validate_document_payload(payload: dict, known_card_slugs: set[str] | None = None) -> list[str]"
description: "Valida un arbol ProseMirror contra la whitelist de nodos y marks que el editor TipTap de Metabase renderiza. Detecta nodos desconocidos que la API acepta pero el frontend descarta silenciosamente."
tags: [metabase, document, prosemirror, validate, pure, python]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: ""
imports: []
params:
  - name: payload
    desc: "payload del document (name, document=arbol ProseMirror, archived)"
  - name: known_card_slugs
    desc: "set de slugs de cards del index para validar cardEmbed.attrs.card (None = skip)"
output: "list[str]: warnings describiendo nodos/marks no soportados o violaciones del schema. Lista vacia = payload renderizable"
tested: true
tests: [test_document_valido_minimo, test_document_nodo_desconocido_callout, test_document_mark_desconocido_underline, test_document_heading_level_invalido, test_document_cardEmbed_sin_id_ni_slug, test_document_flexContainer_demasiados_hijos, test_document_kitchen_sink_valido]
test_file_path: "python/functions/metabase/validation_test.py"
file_path: "python/functions/metabase/validation.py"
---

## Ejemplo

```python
issues = metabase_validate_document_payload({
    "name": "Notas",
    "document": {
        "type": "doc",
        "content": [
            {"type": "callout", "content": [...]}  # ← no soportado por TipTap
        ],
    },
})
# → ["document.content[0]: nodo 'callout' no soportado..."]
```

## Notas

**Whitelist de nodos** (derivada de inspeccionar el bundle de Metabase v0.59):
`doc, paragraph, text, heading, bulletList, orderedList, listItem, blockquote, codeBlock, horizontalRule, hardBreak, cardEmbed, flexContainer, smartLink, resizeNode, mention`

**Whitelist de marks:** `bold, italic, strike, code, link`

Nodos comunes de ProseMirror que la API acepta pero el editor **no renderiza** (el resultado es un documento vacio o incompleto en la UI): `callout, taskList, taskItem, details, table, image, iframe`. Marks equivalentes: `underline, highlight, subscript, textStyle`.

Restricciones estructurales adicionales:
- `heading.attrs.level` ∈ [1, 6]
- `flexContainer` acepta 1-3 hijos, solo `cardEmbed` o `supportingText`
- `flexContainer.attrs.columnWidths` debe tener el mismo largo que `content`
- `cardEmbed.attrs` requiere `id` (int) o `card` (slug del index)