Del estándar al grafo y al proyecto
Singular Solving trabajaba con un centro educativo que quería construir sus sistemas informáticos siguiendo HERM, el estándar de arquitectura empresarial que usan las universidades, con la ambición de que el resultado evolucionara hacia un sistema de referencia para centros educativos. Antes de opinar sobre viabilidad tenía que contestar una pregunta bastante menos glamurosa: qué es HERM exactamente y en qué formato existe.
La respuesta corta es que existe en un póster PDF y en tres catálogos de Excel.
HERM son las Higher Education Reference Models, y no es un proyecto pequeño. Nació en CAUDIT en 2016 —el consejo de directores de IT de las universidades de Australasia— a partir del trabajo de una consultora con dieciocho universidades, y en la versión 3.0.0 (22 de febrero de 2024) declara más de mil instituciones usándolo. Lo mantiene un grupo de trabajo que se reúne cada semana, aliado formalmente con las asociaciones equivalentes de Reino Unido, Europa y Norteamérica. Se publica bajo CC BY-NC-SA 4.0, © CAUDIT. Son cuatro modelos: capacidades de negocio (BCM), un canvas de modelo de negocio, un modelo conceptual de datos (DRM) y el mapa de aplicaciones (ARM), este último nuevo en la V3.
Esos 420 códigos son lo que sale de contar los identificadores de los tres catálogos xlsx: 185 capacidades de negocio (29 de nivel 1 y 156 de nivel 2), 18 topics y 76 entidades de datos, y 3 dominios + 22 capacidades + 116 componentes de aplicación. Sobre esa última cifra conviene ser preciso: 116 es lo que hay en el catálogo v3.0.0; la documentación oficial de CAUDIT cita 118. Preferí la cifra que podía contar yo y dejé la discrepancia documentada en lugar de barrerla.
El hallazgo que cambia el encargo
Lo importante apareció al leer los catálogos completos, y no era una cifra.
HERM define taxonomías. No define ningún artefacto de construcción: ni modelos lógicos o físicos de datos, ni procesos ejecutables, ni APIs, ni arquitecturas de solución. Las costuras internas entre modelos son laxas a propósito —la matriz fina entre capacidades y datos la evaluó el propio grupo de trabajo y la aparcó por «alto esfuerzo, muy subjetiva»—. Y no existe distribución legible por máquina: hay póster PDF, catálogo xlsx, ArchiMate XML y Visio. Ni JSON, ni RDF, ni API.
«Implementar HERM» no es un proyecto ejecutable; HERM solo puede ser guía de un proyecto, no su especificación.
Esa frase es la que reordena el encargo. Un marco descriptivo publicado como catálogo es material de consulta: sirve para tener conversaciones, no para tomar decisiones sobre 116 piezas de software una por una. Y la decisión que había que tomar era exactamente esa.
Así que hice lo único que hacía el estándar utilizable: convertirlo en un grafo tipado, con jerarquía real, y pintar encima el análisis de la propuesta de plataforma educativa para Singular Solving. Con ese mapa delante ya se podía contestar la pregunta de verdad: qué se construye, qué se compra y en qué orden.
OKF, o dónde vive el vocabulario
El motor es Quartz v5 más un toolkit propio, quartz-okf, que publicamos como open source. OKF es el Open Knowledge Format de Google Cloud (v0.1): un directorio de markdown con frontmatter YAML. El toolkit añade encima un perfil —vocabulario cerrado de tipos y aristas de topología declaradas en la propia prosa— más la herramienta para validarlo (okf-check), exportar un bundle con su grafo legible por máquina (okf-export) y calcular impacto documental (okf-impact). Node ≥ 20, cero dependencias en runtime.
La decisión de diseño que importa aquí: el motor no sabe nada del dominio. El vocabulario vive en el repositorio que lo consume, en un okf.config.mjs. Este proyecto declaró 16 tipos (los 14 del perfil de referencia más proposal y organization) y 16 etiquetas de arista. El explorador dibuja las preguntas que le declares como datos; si mañana el dominio es otro, cambia el overlay, no el motor.
El toolkit se pinea por commit SHA y nunca se vendoriza. En el repo hay un fichero con una línea:
$ cat okf/quartz-okf.ref
92499340c04a0f7db434687d42b37d3286b76b78
El pipeline: tres scripts de Python
De xlsx a grafo hay tres pasos, y cada uno resuelve un problema distinto. Son 395 líneas de Python en total.
1. generate-herm-codes.py (109 líneas). Parsea los tres xlsx con openpyxl y emite herm-codes.json. La parte fea es que las hojas no comparten cabecera: hay que detectarla olfateando las celdas que contienen code, id o terminan en id, y luego resolver cada columna por coincidencia parcial de nombre. Los identificadores se extraen con una sola expresión regular, \b(BC|DT|DE|AD|AP|AC)\d{3}\b, y en el mapa de aplicaciones el prefijo ya da el nivel del nodo: AD dominio, AP capacidad, AC componente.
Este script se ejecuta una vez en local, porque el corpus del estándar vive fuera del repositorio: llegó dentro del archivo documental del cliente. El JSON resultante se commitea y pasa a ser la fuente de verdad. El fichero declara su procedencia en la primera clave:
{
"source": "HERM V3.0.0 catalogues (22-feb-2024, © CAUDIT, CC BY-NC-SA 4.0)",
"counts": { "BC": 185, "DT": 18, "DE": 76, "AD": 3, "AP": 22, "AC": 116 }
}2. herm-linker.py (173 líneas). Paso de build. Recorre las notas y convierte cada mención de un código en un enlace a su ficha de catálogo, con tooltip "CÓDIGO · Nombre oficial", e inyecta un ancla <span id="…"> en la primera aparición dentro del catálogo correspondiente. Escribir un linkificador de markdown es un ejercicio de saber cuándo no tocar el texto: no entra en frontmatter, ni en bloques de código, ni en inline code, ni en encabezados, ni en enlaces que ya existen, y en la ficha del BCM no enlaza los códigos BC a sí misma —aunque sí los registra como menciones—.
La segunda función es la que convierte el linker en algo más que cosmética: parsea el gap analysis. El análisis clasificaba los 116 componentes del ARM con símbolos en una columna de tablas markdown (🟢 core, 🔵 integrar, ⚪ evolución, ⬛ no aplica). El script lee ese símbolo como estado, expande código a código los rangos escritos a mano (ACxxx-ACyyy, cómodos de redactar e ilegibles para un parser ingenuo) y recoge también las clasificaciones «en bloque» que aparecen en párrafos fuera de tabla. El criterio editorial —una tabla revisable a mano— y el dato estructurado que alimenta el grafo son el mismo fichero. No hay una segunda copia que se desincronice.
3. herm-to-okf.py (113 líneas). Traduce el dataset al esquema okf-graph/v1 que consume el explorador: la jerarquía oficial se vuelve aristas Part of, las menciones se vuelven aristas Cita desde la nota que las hace, y el estado del gap analysis viaja como propiedad state del nodo, para que un modo pueda colorear y filtrar por ella.
Aquí hay tres decisiones que están escritas en el código, con su porqué, porque ninguna es obvia:
- Raíz sintética. Se añade un nodo
HERMque no existe en el estándar: sin él, los tres modelos flotarían como islas sin relación visible. - Los agregadores no reciben estado. El gap analysis clasifica las piezas, no sus contenedores. Sin propiedad no hay pastilla de filtro, así que dominios y capacidades quedan siempre visibles y sus hijos nunca pierden el enlace al filtrar.
- Los tres catálogos se excluyen del modo menciones. Citan todos los códigos; incluirlos convertiría el modo en ruido.
Que 420 nodos se puedan leer
Un grafo de 420 nodos con jerarquía y transversales sale, por defecto, como una maraña. Los parámetros del layout no son decoración:
layout: {
charge: -55,
gravity: 0.045,
link: {
"*": { distance: 30, strength: 0.65 },
Cita: { distance: 62, strength: 0.15 },
},
}La jerarquía se lee cuando la espina dorsal es corta y firme y las transversales largas y flojas. Y el tamaño del nodo lo da su rango en el estándar —raíz, agregador, hoja—, no su número de hijos: una jerarquía se lee por posición.
El resultado son cuatro modos declarativos sobre el mismo lienzo. Taxonomía: el estándar completo en su jerarquía oficial. Uso en esta propuesta: los códigos que el análisis toca de verdad, con las notas que los citan alrededor. Esta propuesta: la topología OKF del propio repositorio, que es otro grafo y otro corpus. Y Cobertura: el mapa de aplicaciones coloreado por el gap analysis, donde las pastillas filtran por estado en lugar de por tipo.
El grafo publicado tiene 427 nodos y 571 aristas: 420 de jerarquía y 151 de cita.
Del camino salió algo que no estaba en el plan: el visor empezó siendo un HTML propio del repositorio y terminó siendo un plugin reutilizable del toolkit, @zetesis/quartz-okf-explorer, que no existía cuando arrancó el proyecto. Mantuve la misma URL a propósito, porque los enlaces inyectados en 85 páginas seguían valiendo. Hubo también un arreglo de rendimiento que se nota en el ratón: el lienzo hacía unas 4.600 llamadas de dibujo por fotograma.
Validar un sitio de conocimiento como se valida una aplicación
Un sitio estático de documentación se rompe en silencio. Se rompe cuando un wikilink queda literal porque una tabla tenía un pipe sin escapar, cuando la caché de transpilación sirve la interfaz sin traducir, cuando el ancla existe pero el router SPA pisa el salto del navegador. Nada de eso lanza un error.
Así que el repositorio lleva su propia suite E2E con Playwright, 139 líneas, que corre contra producción y comprueba 19 páginas:
$ okf/review.sh
OK — 19 páginas + grafo + anclas + auth verificados en producción
Lo que mira, en orden de utilidad real: que sin credenciales el sitio devuelva 401; errores de consola y peticiones fallidas; que no aparezca ni una cadena de interfaz en inglés (hay once vetadas: min read, graph view, backlinks, blast radius…); que no haya [[ sin resolver; que no quede visible ningún marcador de texto pendiente; que el ancla #ac114 del catálogo ARM haga scroll de verdad; y que el canvas del grafo, en cada uno de los cuatro modos, tenga más de mil píxeles pintados. Esa última comprobación es la que distingue «la página carga» de «el grafo se dibuja».
El despliegue es Cloudflare Pages con Basic Auth en una Pages Function, y CI en GitHub Actions con Node 22: caché del toolkit por hash del fichero de pin, instalación de Typst 0.14.2 —una plantilla de circular escolar se compila a SVG en cada build, como demo documental—, build y wrangler pages deploy. d3 se sirve desde el propio sitio, no desde un CDN.
El sitio es privado, tras Basic Auth. Y eso encaja con lo que dice la licencia: HERM puede cargarse como datos en una plataforma y usarse como guía de diseño, pero no puede venderse embebido. El propio informe deja escrito que, antes de empaquetar HERM como datos de un producto, conviene confirmarlo por escrito con CAUDIT.
Qué del estándar vale para un colegio
Hasta aquí, el vehículo. El contenido que viaja dentro son cuatro documentos, cada uno con una función distinta.
Cuatro entregables, ninguno decorativo
Lo que se entregó a Singular Solving. El sistema del colegio no está entre ellos.
Informe de análisis del estándar
Qué dice HERM, catálogo a catálogo, en la versión que llegó en el corpus. Reproduce los catálogos completos, no un resumen de ellos.
Informe de factibilidad
El veredicto: tres formas de hacer el proyecto comparadas una contra otra, con los hechos y los riesgos numerados.
Gap analysis del mapa de aplicaciones
Cada componente del modelo de referencia de aplicaciones, clasificado contra la realidad de un colegio.
Índice del corpus recibido
Un índice topológico del archivo documental del cliente: «si buscas X, ve a Y». Fue el primer entregable útil, antes de cualquier conclusión.
No se construyó el sistema del colegio. Lo entregado es análisis, veredicto, mapa y propuesta: la plataforma es propuesta, no entrega.
Qué se construye y qué se compra se decide en el gap analysis, componente a componente. Su reparto sobre los 116 del mapa de aplicaciones es exactamente el que el modo Cobertura pinta en el grafo:
El resultado más útil fue una resta. El dominio de investigación desaparece entero —dieciocho componentes en bloque, un colegio no gestiona candidaturas doctorales— y con él las especializaciones universitarias: acreditación de titulaciones, convalidación de créditos, graduaciones con venta de entradas. El mapa de un colegio es bastante más corto que el catálogo completo: una parte grande del estándar sencillamente no aplica. Casi la mitad del estándar sobra, y saberlo antes de firmar nada cambia la conversación sobre alcance.
Y luego está el hueco inverso, que es lo que de verdad valió el ejercicio. Al recorrer el catálogo pensando en un centro escolar español aparecieron necesidades cotidianas que el estándar no nombra o cubre de refilón —el comedor, la agenda diaria entre familia y tutor— y todas apuntaban al mismo sitio. No es un olvido: el modelo nació en universidades, donde el alumno es adulto. El gap analysis lo remata en una frase —«la familia como actor de primera clase es el gran ausente del ARM»— y ese vacío es justo el terreno donde construir se justifica frente a comprar. El inventario completo de esos huecos es parte del informe entregado.
Tres vías, y una hoja de ruta
Con el mapa filtrado, el informe de factibilidad comparó tres formas de hacer el proyecto y se quedó con una. Las otras dos siguen escritas, porque el porqué del descarte es la mitad del argumento.
La primera era la lectura literal del encargo: construir la suite completa que el estándar describe. Se descartó sin matices, y el argumento es de escala, no de ganas. Entre esos 116 componentes hay categorías —sistema de gestión académica, ERP financiero, gestión de personas, generación de horarios— donde los productos establecidos llevan décadas y equipos de cientos de personas detrás. En ocho años, una comunidad de más de mil instituciones no ha construido esa plataforma; su herramienta más avanzada es un kit de Excel y Power BI. El informe lo cierra así: «la versión literal de la ambición no es factible para nadie —tampoco para los grandes actores del sector— y perseguirla comprometería la versión que sí lo es».
La segunda era integrar productos de mercado y no construir nada. Sale viable como operación e insuficiente como proyecto: resuelve el día a día del colegio, pero no deja ningún activo replicable a Singular Solving. Aun así no la tachamos. Se quedó escrita como contrafactual de control, la referencia contra la que cualquier construcción propia tiene que justificarse. Incómoda a propósito.
La tercera es la recomendada, y es la única que responde a las dos mitades del encargo: asesorar sobre el sistema de un colegio concreto y, a la vez, evaluar si de ahí sale algo replicable en otros centros. Consiste en integrar producto de mercado para todo lo que ya está resuelto y construir solo lo diferencial —identidad, núcleo de datos, relación con las familias, capa de conocimiento—, con el estándar como referencia de medición y no como especificación.
Los números la sostienen por los dos lados. El gap analysis ya había acotado esa fracción a un grupo corto de componentes abordables, no a un mapa entero. Y un caso presentado en la comunidad europea del estándar clasificó el 86 % de las capacidades de una institución como «System of Record»: cubribles con producto de mercado o SaaS. Construir por encima de ese 86 % es rehacer lo que ya existe.
Construir solo donde aportamos diferencia; integrar lo resuelto
De ahí sale la hoja de ruta: siete fases, de la 0 a la 6. Cada una cierra con algo en producción y en uso, cada una queda mapeada contra el estándar, y ninguna depende de que llegue la siguiente. Esa última condición es la que permite parar en cualquier punto sin quedarse a medias, y va escrita como condición de viabilidad, no como buena intención.
El núcleo fundacional
Las fases 0 a 2, en el orden que fija la propuesta. Es lo propuesto, no lo hecho.
Descubrimiento
Un cuestionario de descubrimiento para levantar las capacidades reales del colegio. El gap analysis se declara «clasificación orientativa previa a la fase 0»: ordena el terreno, no lo mide.
La identidad primero
Keycloak, el realm del colegio, y las altas y bajas de las personas del centro. Va delante porque es autocontenida, no depende de nada y sostiene todo lo que viene después.
Las familias dentro
Portal de familias, autorizaciones con evidencia y documentos corporativos. Es el terreno del hueco inverso: donde el estándar no llega, se construye.
De la 3 a la 6 la propuesta deja evolución, no detalle: módulos académicos, el estándar cargado como taxonomía viva, búsqueda semántica y asistente, consolidación multi-centro. Ninguna fase tiene fecha de arranque.
Los plazos no están puestos, y es deliberado: «los plazos se estimarán en la versión final; lo que esta propuesta fija es el orden». Tampoco hay una cifra económica que citar. La oferta de la fase 1 perdió su apartado de condiciones antes de salir y quedó como documento de alcance, con un cierre que pide «validar este alcance y fijar fecha de arranque». Poner precio a un trabajo cuyo descubrimiento aún no se ha hecho es adivinar.
Qué se gana desmontando un marco
El grafo es lo que hizo discutible el análisis. Un informe de mil novecientas líneas se lee una vez y se archiva; un mapa donde puedes filtrar los 116 componentes por «esto lo construimos / esto lo integramos / esto no aplica» y pinchar cada uno hasta su definición oficial se usa en una reunión, y se puede rebatir pieza a pieza. Ahí está la diferencia entre entregar una opinión y entregar algo con lo que decidir.
El método no depende de HERM. Cualquier organización que trabaje contra un marco normativo publicado como catálogo —un esquema de seguridad, un modelo de capacidades sectorial, una norma con cientos de controles— tiene el mismo problema: el documento es inerte y las decisiones son por elemento. Convertirlo en un grafo tipado y auditable, con el análisis propio pintado encima, cambia por completo la conversación.
Los Higher Education Reference Models (HERM) son © CAUDIT y se publican bajo licencia CC BY-NC-SA 4.0. Este post los cita con atribución y con fines de análisis; no reproduce sus catálogos.
Preguntas frecuentes
¿Qué recibo al final: un informe o una herramienta?
Las dos cosas. El análisis se entrega como documento legible de principio a fin y como corpus navegable, con cada afirmación enlazada a su fuente. Lo segundo es lo que sigue siendo útil seis meses después.
¿Y si la conclusión es que no debo hacer el proyecto?
Se escribe. Aquí el informe descartó sin matices la versión más ambiciosa del encargo —se lo dijimos a Singular Solving por escrito— y dejó anotada la alternativa de «comprarlo hecho» como referencia contra la que medir cualquier construcción propia.
¿Tengo que adoptar el estándar para que esto sirva?
No. Aquí el estándar era el objeto de análisis, no el destino. El método funciona con cualquier corpus del que tenga que salir una decisión por elemento: normativa, documentación interna, un catálogo de aplicaciones heredado.
¿La documentación se queda con nosotros?
Sí. Son ficheros markdown con frontmatter, en un formato abierto, y el toolkit de publicación es código abierto y se fija por SHA. No hay producto del que dependas para leer tu propio análisis.
Más casos reales
Cómo crear tu propio grafo de conocimiento con quartz-okf
Que el grafo del conocimiento lo construya el que sabe del dominio
Gobernanza IT: quién entra, quién puede desplegar y cómo se demuestra
Clasificar documentos en 77 categorías sin entrenar un modelo
Montar un homelab desde cero: backups y restauración - Homelab (06/06)
Montar un homelab desde cero: observabilidad - Homelab (05/06)
¿Tienes un marco de referencia que nadie usa porque vive en un PDF?
Un esquema de seguridad, un modelo de capacidades sectorial, una norma con cientos de controles: si las decisiones son por elemento, el documento no basta. Cuéntame contra qué marco trabajas y te digo qué convertiría primero en grafo.