El estándar

Para qué sirve

El estándar define la forma común de un Atlas de Navegación: lo que lo hace compatible con el sistema Public Orbit y registrable en él. Cumplirlo habilita a cualquiera a construir un atlas de otro sector (agro, salud, transporte) o de otro país, y a que ese atlas conviva con los ya registrados.

Parte normativa

Es normativo lo que sostiene la interoperabilidad. Cumplir los cinco puntos N1–N5 y la regla de autocontención basta para que un atlas sea compatible.

Cada atlas constituye una unidad reconocible por su estructura. Puede publicarse como repositorio propio o alojarse como subcarpeta de un sistema (atlas/<sector>/), conservando en ambos casos su conformidad.

N1 — Tres archivos por entidad. Cada entidad cubierta se documenta en SKILL.md (descripción de la entidad y orientación general de navegación), mapa-web.md (árbol curado del sitio oficial) y fuentes.md (inventario de sistemas y plataformas, geovisores, portales de datos y documentos clave).

N2 — Convención de nombres. Las skills de entidad se nombran navegar-<entidad> (por ejemplo navegar-ideam, navegar-upme).

N3 — Skill orquestadora. Todo atlas tiene una skill orquestadora, nombrada atlas-orquestador-<sector>, con el mapa de skills por subsector, el procedimiento de navegación y rutas sugeridas para consultas que cruzan varias entidades del sector. El sufijo de sector mantiene el nombre único en todo Public Orbit, así que siempre acompaña a la orquestadora.

N4 — Patrón de enrutamiento. El orquestador de cada nivel enruta hacia las unidades inferiores y las conserva intactas. La especificidad vive abajo.

N5 — Línea vertical. La skill orquestadora de cada atlas incluye una línea estandarizada apuntando al nodo nacional de Public Orbit, para consultas que cruzan a otros sectores.

Autocontención. Cada atlas se sostiene con sus propios archivos. El cruce entre sectores lo resuelve el nodo nacional (N5), nunca un enlace directo entre atlas: así un atlas puede publicarse, moverse o instalarse solo, y el conjunto sigue coherente.

Parte recomendada

Buenas prácticas de los atlas fundadores. Elevan la calidad del atlas y son opcionales para la compatibilidad:

• Mapa web curado: reducido al contenido misional y estratégico del sitio.
• Tablas de fuentes con un vocabulario común de secciones: sistemas de información y plataformas, geovisores y mapas, portales de datos, publicaciones periódicas, documentos de referencia, normativa, y servicios y trámites, en ese orden y solo las que apliquen. Cada fuente lleva su URL verificada.
• Carpeta examples/ con consultas de ejemplo y su ruta esperada.
• Verificación en vivo de URLs y afirmaciones contra el sitio real antes de publicar.
• Descripción institucional contrastada con la norma vigente o la fuente oficial que la establece.
• Reglas de competencia en la orquestadora, para combinar resultados sin atribuir datos de una entidad a otra.
• Identidad visual propia: logo en SVG monocromo dentro de la familia visual de Public Orbit.

Cómo se comprueba

El estándar viene con una implementación de referencia que lo verifica. Es un script, verificar-conformidad.sh, que vive en la raíz del repositorio de Public Orbit y revisa la parte normativa —N1 a N5 y la autocontención—. La parte recomendada queda al criterio de cada atlas.

El script examina cada atlas como si fuera un repositorio independiente, ignorando el resto del árbol. Gracias a eso el mismo chequeo sirve para un atlas que vive suelto en su propio repositorio y para uno que vive como subcarpeta del repositorio de Public Orbit.

Mide con tres varas distintas, según el estado de cada atlas:

• Atlas sectorial poblado. Se le exige la norma completa.
• Nodo nacional. Solo se revisa su orquestadora. N1 y N2 quedan fuera, porque el nodo carece de entidades propias.
• Atlas en construcción. Sus carpetas marcador deben estar bien nombradas y vacías. El resultado es «omitido», a la espera de poblarse.

Se corre así:

bash verificar-conformidad.sh            # todos los atlas
bash verificar-conformidad.sh ambiental  # uno solo

GitHub Actions lo ejecuta en cada push y en cada pull request a main. Un atlas que incumple la norma deja el trabajo en rojo, así que la conformidad se comprueba sola en cada propuesta de cambio.

Junto al verificador corren sus propias pruebas adversariales, que rompen el repositorio a propósito sobre una copia temporal y exigen que el verificador lo detecte. Existen porque un verificador que aprueba todo también sale en verde, y ese fallo pasaría inadvertido.

Esa es la diferencia entre publicar una norma y publicar una norma verificable. Quien construya un atlas de otro sector puede comprobar por su cuenta si cumple, con un comando.

Cómo evoluciona el estándar

La parte normativa define el contrato de compatibilidad vigente, no una estructura definitiva. N1–N5 pueden revisarse cuando la experiencia de uso muestre una forma más clara, útil o sostenible de organizar los atlas.

Una modificación normativa afecta al conjunto de atlas de Public Orbit. Por ejemplo, cambiar N1 puede alterar los archivos exigidos por entidad, su contenido mínimo, el verificador de conformidad, las plantillas de construcción y los atlas ya registrados. Por eso, cada cambio debe precisar:

• qué problema resuelve;
• qué parte de la norma modifica;
• qué atlas y herramientas quedan afectados;
• cómo se realiza la transición;
• desde qué versión entra en vigor.

Una propuesta no modifica por sí sola el estándar. El cambio se vuelve vigente cuando se incorpora a la especificación, se refleja en el verificador y recibe una nueva versión. Mientras la versión mayor sea 0, estas revisiones pueden requerir ajustes coordinados en los atlas existentes.

Versión vigente

La especificación está en v0.1, en incubación. Durante esta etapa pueden revisarse incluso elementos normativos, siempre mediante el proceso descrito arriba. El versionado es semántico (mayor.menor.parche).

Especificación completa: github.com/Nicolas9714/public-orbit/blob/main/estandar/especificacion.md