JSON Schema

Librería para graficar Json

Esta librería tiene dos variantes de build:

• projects/schema-ng19: build principal para Angular moderno (en este repo se usa Angular 19).
• projects/schema-ng16: build compatible con Angular 16 (export en subpath ./ng16).

Ambas se construyen desde la raíz del repo. No necesitas instalar dependencias dentro de projects/schema-ng19 ni projects/schema-ng16.

Demos de ejemplo

• Librería (repo): miguimono/json-schema
• Demo Angular 16 (repo): miguimono/demo-json-schema-ng16
• Demo Angular 16 (sitio): miguimono.github.io/demo-json-schema-ng16
• Demo Angular 19 (repo): miguimono/demo-json-schema-ng19
• Demo Angular 19 (sitio): miguimono.github.io/demo-json-schema-ng19

Requisitos y versiones

• Node.js: no hay engines definidos en los package.json, por lo que debes usar una versión compatible con tu Angular objetivo.
• NPM: la versión incluida con tu Node.
• Angular CLI: viene como dependencia del workspace cuando instalas en la raíz.

Recomendación práctica usando nvm:

• Para construir la variante principal (Angular moderno): nvm use 22
• Para probar compatibilidad Angular 16 en entornos antiguos: nvm use 16 (o una versión LTS más nueva si tu entorno lo permite)

Si cambias de versión de Node, reinstala dependencias en la raíz para evitar binarios incompatibles.

Instalación (única, en la raíz)

Desde la raíz del repo:

nvm use 22
npm install

Esto crea un solo node_modules en la raíz.
Las carpetas projects/schema-ng19/node_modules y projects/schema-ng16/node_modules no deberían existir.

Compilación

Desde la raíz del repo:

# build Angular moderno
npm run build:schema-ng19

# build Angular 16 (subpath ./ng16)
npm run build:schema-ng16

# build de ambas
npm run build

Los artefactos quedan en:

• dist/schema/ (principal)
• dist/schema/ng16/ (compatibilidad)

Empaquetado (npm pack)

npm run pack

Esto:

1. Construye ambas variantes.
2. Genera un .tgz en la raíz, por ejemplo json-schema-x.y.z.tgz.

Si quieres empaquetar manualmente desde la carpeta de salida:

cd dist/schema
npm pack

Consumo en proyectos

Import normal (Angular moderno):

import { SchemaComponent } from "@miguimono/json-schema";

Import explícito Angular 19:

import { SchemaComponent } from "@miguimono/json-schema/ng19";

Import compatible Angular 16:

import { SchemaComponent } from "@miguimono/json-schema/ng16";

¿Qué hace la librería?

Convierte un JSON arbitrario en un grafo visual interactivo de cards y enlaces.
Incluye normalización del JSON, layout jerárquico determinista y render con pan/zoom.

Módulos y responsabilidades

• SchemaComponent: orquesta el pipeline completo (normalización → layout → render), maneja pan/zoom, overlays y toolbar.
• SchemaCardComponent: renderiza un nodo como card, admite cardTemplate, badges e imagen opcional.
• SchemaLinksComponent: dibuja las aristas en SVG según el estilo configurado.
• JsonAdapterService: normaliza el JSON en nodos/aristas con metadatos.
• SchemaLayoutService: calcula posiciones y puntos de aristas.
• models.ts: contratos y DEFAULT_SETTINGS.

Flujo interno (alto nivel)

1. JsonAdapterService normaliza el JSON en NormalizedGraph.
2. SchemaLayoutService calcula posiciones y puntos de aristas.
3. SchemaComponent renderiza cards/enlaces y gestiona pan/zoom.

Recomendaciones de performance

• Para grafos muy grandes, considera:
  • dataView.previewMaxKeys bajo (ej. 3–8).
  • dataView.maxDepth (ej. 3–6).
  • dataView.autoResizeCards: false si necesitas mayor velocidad.
  • viewport.height más alto si el grafo es muy vertical.
• Si usas imágenes, define dataView.imageSizePx y imageFit para evitar relayouts.

Troubleshooting (errores comunes)

• Cannot destructure property 'pos' of 'file.referencedFiles[index]' ...
  Suele indicar incompatibilidad de TypeScript. Para Angular 19 usa TS ~5.5.x.
• Could not find the '@angular-devkit/build-angular:ng-packagr' builder
  Verifica que @angular-devkit/build-angular y ng-packagr estén en devDependencies.
• Unknown argument: verbose
  Usa npx ng ... para forzar el CLI local del proyecto.
• Si el esquema no se re-renderiza tras mutar el JSON, reasigna data con un nuevo objeto (cache referencial).

Estructura recomendada (mantenimiento)

• projects/schema-ng19: build principal (Angular 19).
• projects/schema-ng16: build compatibilidad (Angular 16).
• projects/schema-shared: fuente única de modelos y servicios.
• scripts/sync-shared.js: copia schema-shared dentro de cada build antes de compilar.
• projects/schema-shared/src/lib/styles: tokens, mixins y base de estilos.

Notas de mantenimiento:

• No edites manualmente las copias dentro de schema-ng16/src/lib/shared ni schema-ng19/src/lib/shared.
• Haz cambios en projects/schema-shared/src/lib y compila (el script las sincroniza).
• Mantén la versión única en el package.json raíz (se sincroniza a los subproyectos).
• Puedes verificar sincronización con npm run check:shared.
• Para builds limpios: npm run clean:dist (funciona en Windows, macOS y Linux).

Uso rápido (Angular 19 / 16)

Angular 19 (default)

import { SchemaComponent } from "@miguimono/json-schema";

Angular 16

import { SchemaComponent } from "@miguimono/json-schema/ng16";

Ejemplo mínimo

import { Component } from "@angular/core";
import { CommonModule } from "@angular/common";
import { SchemaComponent } from "@miguimono/json-schema";

@Component({
  selector: "app-demo",
  standalone: true,
  imports: [CommonModule, SchemaComponent],
  template: `<schema [data]="data"></schema>`,
})
export class DemoComponent {
  data = {
    root: {
      name: "Root",
      children: [{ name: "Child A" }, { name: "Child B" }],
    },
  };
}

Ejemplo con settings básicos

import { SchemaSettings, DEFAULT_SETTINGS } from "@miguimono/json-schema";

const settings: SchemaSettings = {
  ...DEFAULT_SETTINGS,
  layout: {
    ...DEFAULT_SETTINGS.layout,
    layoutDirection: "RIGHT",
    linkStyle: "curve",
  },
  dataView: {
    ...DEFAULT_SETTINGS.dataView,
    titleKeyPriority: ["name", "title", "id"],
    previewMaxKeys: 5,
  },
};

<schema [data]="data" [settings]="settings"></schema>

Instalación directa desde .tgz local (sin publicar)

Si copiaste el paquete a lib/json-schema-x.y.z.tgz dentro del proyecto consumidor:

npm install ./lib/json-schema-x.y.z.tgz

Luego:

• Angular 19+:

  import { SchemaComponent } from "@miguimono/json-schema";

• Angular 19 explícito:

  import { SchemaComponent } from "@miguimono/json-schema/ng19";

• Angular 16:

  import { SchemaComponent } from "@miguimono/json-schema/ng16";

Nota: el .tgz puede estar en cualquier ruta local; usa la ruta relativa o absoluta.

Notas importantes

• Hay 3 package.json:
  • package.json raíz: scripts y exports.
  • projects/schema-ng19/package.json: metadata del build principal.
  • projects/schema-ng16/package.json: metadata del build ng16.
• Solo se instala en la raíz.
  Si instalas dentro de projects/schema-ng19 o projects/schema-ng16, tendrás tres node_modules y eso genera inconsistencias.

Limpieza si ya instalaste en subproyectos

Si ya creaste node_modules dentro de los subproyectos, bórralos y vuelve a instalar en la raíz:

rm -rf projects/schema-ng19/node_modules projects/schema-ng16/node_modules
npm install

Licencia

MIT — Copyright (c) 2026 Miguimono