@eventcatalog/core 3.45.0 → 3.46.1

package/eventcatalog/src/content.config.ts

@@ -71,6 +71,7 @@ const channelPointer = z
 
 const schemaPointer = z.object({
   id: z.string().optional(),
+  ref: z.string().optional(),
   file: z.string().optional(),
   path: z.string().optional(),
   name: z.string().optional(),
@@ -1018,10 +1019,13 @@ const schemas = defineCollection({
       ]) as string[],
       base: projectDirBase,
     },
+    sources: config.schemas?.sources ?? [],
   }),
   schema: z
     .object({
       format: z.string(),
+      schemaId: z.string().optional(),
+      ref: z.string().optional(),
       content: z.string().optional(),
       file: z.string().optional(),
       filePath: z.string().optional(),
@@ -1038,8 +1042,11 @@ const schemas = defineCollection({
       }),
       source: z.object({
         provider: z.string(),
+        id: z.string().optional(),
         path: z.string().optional(),
         url: z.string().optional(),
+        ref: z.string().optional(),
+        branch: z.string().optional(),
       }),
       readOnly: z.boolean().optional(),
     })

package/eventcatalog/src/enterprise/tools/catalog-tools.ts

@@ -28,6 +28,8 @@ import { getNodesAndEdges as getNodesAndEdgesForContainer } from '@utils/node-gr
 import { convertToMermaid } from '@utils/node-graphs/export-mermaid';
 import config from '@config';
 
+const MESSAGE_COLLECTIONS = new Set(['events', 'commands', 'queries']);
+
 // ============================================
 // Pagination utilities
 // ============================================
@@ -226,6 +228,27 @@ export async function getSchemaForResource(params: { resourceId: string; resourc
     };
   }
 
+  if (MESSAGE_COLLECTIONS.has(params.resourceCollection)) {
+    const schemaEntries = await getCollection('schemas');
+    const schemas = schemaEntries.filter(
+      (schema) =>
+        schema.data.message.collection === params.resourceCollection &&
+        schema.data.message.id === params.resourceId &&
+        schema.data.message.version === params.resourceVersion
+    );
+
+    if (schemas.length > 0) {
+      return schemas.map((schema) => ({
+        id: schema.id,
+        name: schema.data.name,
+        ref: schema.data.ref,
+        format: schema.data.format,
+        source: schema.data.source,
+        code: schema.data.content || '',
+      }));
+    }
+  }
+
   const schema = await getSchemasFromResource(resource);
 
   if (schema.length > 0) {

package/eventcatalog/src/pages/docs/[type]/[id]/[version]/index.astro

@@ -565,7 +565,7 @@ if (!isAdrPage && !hasCurrentFlowEmbed && !hasCurrentPageNodeGraph) {
         <div data-pagefind-ignore>
           <!-- @ts-ignore -->
           <!-- <SchemaViewer id={props.data.id} catalog={props.catalog} filePath={props.filePath} /> -->
-          <SchemaViewer id={props.data.id} filePath={props.filePath} />
+          <SchemaViewer id={props.data.id} version={props.data.version} collection={props.collection} filePath={props.filePath} />
 
           {
             nodeGraphs.length > 0 &&

package/eventcatalog/src/stores/sidebar-store/builders/message.ts

@@ -15,11 +15,33 @@ import { isVisualiserEnabled, isChangelogEnabled } from '@utils/feature';
 import { iconFieldsForResource } from '@utils/icon';
 import { collectionToResourceMap } from '@utils/collections/util';
 
+type MessageSchemaEntry = CollectionEntry<'schemas'>;
+
 const getProducerConsumerPageRef = (resource: any) => {
   const resourceType = collectionToResourceMap[resource.collection as keyof typeof collectionToResourceMap];
   return `${resourceType}:${resource.data.id}:${resource.data.version}`;
 };
 
+const getSchemasForMessage = (
+  message: CollectionEntry<'events' | 'commands' | 'queries'>,
+  schemas: MessageSchemaEntry[] = []
+) => {
+  return schemas.filter(
+    (schema) =>
+      schema.data.message.collection === message.collection &&
+      schema.data.message.id === message.data.id &&
+      schema.data.message.version === message.data.version
+  );
+};
+
+const getSchemaNavTitle = (schemas: MessageSchemaEntry[]) => {
+  if (schemas.length > 1) return 'Schemas';
+
+  const schemaPath = schemas[0]?.data.file || schemas[0]?.data.source.path || schemas[0]?.data.ref || schemas[0]?.id;
+  const format = schemaPath ? getSchemaFormatFromURL(schemaPath) : schemas[0]?.data.format;
+  return format ? `Schema (${format.toUpperCase()})` : 'Schema';
+};
+
 export const buildMessageNode = (
   message: CollectionEntry<'events' | 'commands' | 'queries'>,
   owners: any[],
@@ -51,7 +73,8 @@ export const buildMessageNode = (
   };
   const defaultIcon = iconMap[collection] || 'Mail';
 
-  const hasSchema = message.data.schemaPath !== undefined;
+  const resolvedSchemas = getSchemasForMessage(message, context.schemas);
+  const hasSchema = resolvedSchemas.length > 0;
   const renderVisualiser = isVisualiserEnabled();
   const docsSection = buildResourceDocsSection(
     collection as 'events' | 'commands' | 'queries',
@@ -116,7 +139,7 @@ export const buildMessageNode = (
         pages: [
           {
             type: 'item',
-            title: `Schema (${getSchemaFormatFromURL(message.data.schemaPath!).toUpperCase()})`,
+            title: getSchemaNavTitle(resolvedSchemas),
             href: buildUrl(`/schemas/${collection}/${message.data.id}/${message.data.version}`),
           },
           hasFieldUsage && {

package/eventcatalog/src/stores/sidebar-store/builders/shared.ts

@@ -67,6 +67,7 @@ export type ResourceGroupContext = {
   entities?: CollectionEntry<'entities'>[];
   dataProducts: CollectionEntry<'data-products'>[];
   diagrams: CollectionEntry<'diagrams'>[];
+  schemas?: CollectionEntry<'schemas'>[];
   adrs: Adr[];
   users?: CollectionEntry<'users'>[];
   teams?: CollectionEntry<'teams'>[];

package/eventcatalog/src/stores/sidebar-store/state.ts

@@ -292,6 +292,7 @@ export const getNestedSideBarData = async (): Promise<NavigationData> => {
     dataProducts,
     entities,
     adrs,
+    schemas,
     resourceDocs,
     resourceDocCategories,
   ] = await Promise.all([
@@ -309,6 +310,7 @@ export const getNestedSideBarData = async (): Promise<NavigationData> => {
     getDataProducts({ getAllVersions: false }),
     getEntities({ getAllVersions: false }),
     getAdrs({ getAllVersions: false }),
+    getCollection('schemas'),
     getResourceDocs(),
     getResourceDocCategories(),
   ]);
@@ -330,6 +332,7 @@ export const getNestedSideBarData = async (): Promise<NavigationData> => {
     containers,
     channels,
     diagrams,
+    schemas,
     dataProducts,
     entities,
     adrs,

package/eventcatalog/src/styles/tailwind.css

@@ -2,6 +2,24 @@
 
 @plugin "@tailwindcss/typography";
 
+/*
+ * EventCatalog renders MDX inside Tailwind Typography's `.prose` wrapper.
+ * Typography adds decorative backticks around inline code via pseudo-elements;
+ * docs should show only the code content itself.
+ */
+.prose code::before,
+.prose code::after {
+  content: '';
+}
+
+.prose :not(pre) > code {
+  background-color: oklab(0.97 0 0.0013 / 0.5);
+  border-radius: 0.25rem;
+  font-family: var(--font-mono);
+  padding: 0.125rem 0.375rem;
+  font-weight: 400;
+}
+
 /* Dark mode uses data-theme attribute, not prefers-color-scheme */
 @custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *));
 

package/eventcatalog/src/utils/collections/schema-loader.ts

@@ -4,12 +4,18 @@ import matter from 'gray-matter';
 import fs from 'node:fs/promises';
 import fsSync from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import pc from 'picocolors';
+import { isEventCatalogScaleEnabled } from '../feature';
 import { sortVersioned } from './util';
 
+const colors = pc.createColors(true);
+
 type MessageCollection = 'events' | 'commands' | 'queries';
 
 type SchemaReference = {
   id?: string;
+  ref?: string;
   file?: string;
   path?: string;
   name?: string;
@@ -18,6 +24,34 @@ type SchemaReference = {
   default?: boolean;
 };
 
+type SchemaSourceEntry = {
+  provider: string;
+  id?: string;
+  path?: string;
+  url?: string;
+  ref?: string;
+  [key: string]: unknown;
+};
+
+type SchemaSource = {
+  type: 'schemas';
+  name: string;
+  canResolve: (ref: string) => boolean;
+  resolve: (
+    ref: string,
+    context?: { messageFilePath?: string }
+  ) => Promise<
+    | {
+        id: string;
+        name?: string;
+        format?: string;
+        content: string;
+        source: SchemaSourceEntry;
+      }
+    | undefined
+  >;
+};
+
 type MessageFrontmatter = {
   id?: string;
   name?: string;
@@ -30,6 +64,8 @@ type MessageFrontmatter = {
 
 export type MessageSchemaResource = {
   id: string;
+  schemaId?: string;
+  ref?: string;
   name?: string;
   version?: string;
   format: string;
@@ -48,8 +84,19 @@ export type MessageSchemaResource = {
     owners?: string[];
   };
   source: {
-    provider: 'file';
-    path: string;
+    provider: string;
+    id?: string;
+    path?: string;
+    url?: string;
+    ref?: string;
+    [key: string]: unknown;
+  };
+  readOnly?: boolean;
+};
+
+type InternalMessageSchemaResource = MessageSchemaResource & {
+  _context?: {
+    messageFilePath?: string;
   };
 };
 
@@ -58,11 +105,13 @@ type SchemaLoaderOptions = {
     pattern: string[];
     base?: string;
   };
+  sources?: SchemaSource[];
 };
 
 type LoaderContext = Parameters<Loader['load']>[0];
 
 const MESSAGE_COLLECTIONS: MessageCollection[] = ['events', 'commands', 'queries'];
+const FILE_SCHEMA_REF_PREFIX = 'file://';
 
 const normalizePath = (value: string) => value.replace(/\\/g, '/');
 
@@ -85,11 +134,137 @@ const getSchemaFormat = (schemaPath: string) => {
 const buildGeneratedSchemaId = (message: { collection: MessageCollection; id: string; version: string }, schemaPath: string) =>
   `schema:${message.collection}:${message.id}:${message.version}:${schemaPath}`;
 
+const getSchemaCollectionId = ({
+  message,
+  reference,
+  schemaRef,
+  schemaFile,
+}: {
+  message: { collection: MessageCollection; id: string; version: string };
+  reference: SchemaReference;
+  schemaRef?: string;
+  schemaFile?: string;
+}) => {
+  if (schemaRef) return buildGeneratedSchemaId(message, schemaRef);
+  if (reference.id) return buildGeneratedSchemaId(message, reference.id);
+  return buildGeneratedSchemaId(message, schemaFile as string);
+};
+
 const getSchemaFile = (reference: SchemaReference) => reference.file ?? reference.path;
 
+const getSchemaRef = (reference: SchemaReference) => {
+  if (reference.ref) return reference.ref;
+  if (!getSchemaFile(reference)) return reference.id;
+  return undefined;
+};
+
+const getSchemaDisplayName = ({
+  referenceName,
+  resolvedName,
+  schemaFile,
+  filePath,
+  schemaRef,
+  sourcePath,
+  schemaId,
+  messageName,
+}: {
+  referenceName?: string;
+  resolvedName?: string;
+  schemaFile?: string;
+  filePath?: string;
+  schemaRef?: string;
+  sourcePath?: string;
+  schemaId: string;
+  messageName?: string;
+}) => {
+  const pathLikeName = schemaFile ?? filePath ?? sourcePath ?? schemaRef ?? schemaId;
+  return referenceName ?? resolvedName ?? path.basename(pathLikeName) ?? messageName ?? 'Schema';
+};
+
 const schemaFileExists = (schema: MessageSchemaResource): schema is MessageSchemaResource & { filePath: string } =>
   Boolean(schema.filePath && fsSync.existsSync(schema.filePath));
 
+const getSchemaProvider = (id: string) => {
+  try {
+    const url = new URL(id);
+    return url.protocol.replace(':', '') || 'external';
+  } catch {
+    return 'external';
+  }
+};
+
+const isFileSchemaRef = (ref?: string) => ref?.startsWith(FILE_SCHEMA_REF_PREFIX);
+
+const getFileSchemaRefPath = (ref: string, messageFilePath: string) => {
+  if (ref.startsWith('file:///') || ref.startsWith('file://localhost/')) {
+    try {
+      const filePath = fileURLToPath(ref);
+      return {
+        filePath,
+        sourcePath: filePath,
+      };
+    } catch {
+      throw new Error(`Invalid file schema ref "${ref}". Expected file://<relative-path> or file:///absolute/path.`);
+    }
+  }
+
+  const sourcePath = decodeURIComponent(ref.slice(FILE_SCHEMA_REF_PREFIX.length));
+  if (!sourcePath) {
+    throw new Error(`Invalid file schema ref "${ref}". Expected file://<relative-path> or file:///absolute/path.`);
+  }
+
+  return {
+    filePath: path.resolve(path.dirname(messageFilePath), sourcePath),
+    sourcePath,
+  };
+};
+
+const getTimestamp = () => {
+  const now = new Date();
+  return now.toLocaleTimeString('en-US', { hour12: false });
+};
+
+const logSchemaInfo = (message: string) => {
+  console.log(`${colors.dim(getTimestamp())} ${colors.blue('[schemas]')} ${message}`);
+};
+
+const getMessageTypeLabel = (collection: MessageCollection) => {
+  if (collection === 'events') return 'event';
+  if (collection === 'commands') return 'command';
+  return 'query';
+};
+
+const getErrorMessage = (error: unknown) => {
+  return error instanceof Error ? error.message : String(error);
+};
+
+const getSchemaResolveRef = (schema: MessageSchemaResource) => schema.ref ?? schema.id;
+
+const buildSchemaSourceErrorMessage = ({
+  schema,
+  source,
+  error,
+}: {
+  schema: MessageSchemaResource;
+  source: SchemaSource;
+  error: unknown;
+}) => {
+  const messageType = getMessageTypeLabel(schema.message.collection);
+
+  return [
+    '',
+    colors.red(colors.bold('[schemas] Failed to resolve schema')),
+    '',
+    `  Message: ${messageType} "${schema.message.id}" version "${schema.message.version}"`,
+    `  Schema:  ${getSchemaResolveRef(schema)}`,
+    `  Source:  ${source.name}`,
+    '',
+    colors.bold('Reason:'),
+    `  ${getErrorMessage(error)}`,
+    '',
+  ].join('\n');
+};
+
 const addLatestMetadata = (schemas: MessageSchemaResource[]) => {
   const schemasByMessage = schemas.reduce(
     (acc, schema) => {
@@ -138,11 +313,10 @@ export const getMessageSchemasFromFrontmatter = ({
   };
 
   const schemaReferences =
-    data.schemas?.filter((schema) => getSchemaFile(schema)) ??
+    data.schemas?.filter((schema) => getSchemaRef(schema) || getSchemaFile(schema)) ??
     (data.schemaPath
       ? [
           {
-            id: buildGeneratedSchemaId(message, data.schemaPath),
             file: data.schemaPath,
             name: 'Schema',
             default: true,
@@ -151,29 +325,123 @@ export const getMessageSchemasFromFrontmatter = ({
       : []);
 
   return schemaReferences.map((reference) => {
-    const schemaFile = getSchemaFile(reference) as string;
-    const schemaFilePath = path.resolve(path.dirname(messageFilePath), schemaFile);
-    const schemaId = reference.id ?? buildGeneratedSchemaId(message, schemaFile);
+    const schemaFile = getSchemaFile(reference);
+    const schemaRef = getSchemaRef(reference);
+    const fileSchemaRef = isFileSchemaRef(schemaRef) ? getFileSchemaRefPath(schemaRef as string, messageFilePath) : undefined;
+    const schemaFilePath = schemaFile ? path.resolve(path.dirname(messageFilePath), schemaFile) : fileSchemaRef?.filePath;
+    const schemaId = getSchemaCollectionId({ message, reference, schemaRef, schemaFile });
+    const schemaPathForFormat = schemaFile ?? fileSchemaRef?.filePath;
 
     return {
       id: schemaId,
-      name: reference.name ?? schemaId,
+      ...(reference.id && !schemaRef ? { schemaId: reference.id } : {}),
+      ...(schemaRef ? { ref: schemaRef } : {}),
+      name: getSchemaDisplayName({
+        referenceName: reference.name,
+        schemaFile,
+        filePath: fileSchemaRef?.filePath,
+        schemaRef,
+        schemaId,
+        messageName: data.name,
+      }),
       version: data.version,
-      format: reference.format ?? getSchemaFormat(schemaFile),
+      format: reference.format ?? (schemaPathForFormat ? getSchemaFormat(schemaPathForFormat) : 'unknown'),
       file: schemaFile,
       filePath: schemaFilePath,
       environments: reference.environments,
       default: reference.default,
       message,
       source: {
-        provider: 'file',
-        path: schemaFile,
+        provider: schemaFile || fileSchemaRef ? 'file' : getSchemaProvider(schemaRef ?? schemaId),
+        path: schemaFile ?? fileSchemaRef?.sourcePath,
       },
     };
   });
 };
 
-export const loadMessageSchemas = async ({ pattern, base }: SchemaLoaderOptions['messages']) => {
+const resolveSchemaSource = async (
+  schema: InternalMessageSchemaResource,
+  source: SchemaSource
+): Promise<InternalMessageSchemaResource | undefined> => {
+  if (schemaFileExists(schema)) return schema;
+  if (schema.filePath) return undefined;
+
+  let resolvedSchema: Awaited<ReturnType<SchemaSource['resolve']>>;
+  const schemaResolveRef = getSchemaResolveRef(schema);
+
+  try {
+    resolvedSchema = await source.resolve(schemaResolveRef, schema._context);
+  } catch (error) {
+    throw new Error(buildSchemaSourceErrorMessage({ schema, source, error }));
+  }
+
+  if (!resolvedSchema) return undefined;
+
+  const resolvedMessageSchema: InternalMessageSchemaResource = {
+    ...schema,
+    format: schema.format !== 'unknown' ? schema.format : (resolvedSchema.format ?? 'unknown'),
+    content: resolvedSchema.content,
+    source: resolvedSchema.source,
+    readOnly: true,
+  };
+
+  resolvedMessageSchema.name = getSchemaDisplayName({
+    referenceName: schema.name,
+    resolvedName: resolvedSchema.name,
+    schemaRef: schema.ref,
+    sourcePath: resolvedSchema.source.path,
+    schemaId: schema.id,
+    messageName: schema.message.name,
+  });
+
+  return resolvedMessageSchema;
+};
+
+const resolveSchemaSources = async (schemas: InternalMessageSchemaResource[], sources: SchemaSource[] = []) => {
+  if (sources.length > 0 && !isEventCatalogScaleEnabled()) {
+    throw new Error('Schema sources require EventCatalog Scale.');
+  }
+
+  const localSchemas = schemas.filter(schemaFileExists);
+  const externalSchemas = schemas.filter((schema) => !schema.filePath);
+  const resolvedExternalSchemas: InternalMessageSchemaResource[] = [];
+  const resolvedExternalSchemaIds = new Set<string>();
+
+  for (const source of sources) {
+    const sourceSchemas = externalSchemas.filter((schema) => source.canResolve(getSchemaResolveRef(schema)));
+    if (sourceSchemas.length === 0) continue;
+
+    logSchemaInfo(
+      `Loading ${sourceSchemas.length} schema${sourceSchemas.length === 1 ? '' : 's'} from schema source "${source.name}"`
+    );
+
+    const resolvedSchemas = await Promise.all(sourceSchemas.map((schema) => resolveSchemaSource(schema, source)));
+    const syncedSchemas = resolvedSchemas.filter((schema): schema is InternalMessageSchemaResource => schema !== undefined);
+
+    for (const schema of syncedSchemas) {
+      resolvedExternalSchemaIds.add(schema.id);
+      resolvedExternalSchemas.push(schema);
+    }
+
+    const skippedSchemas = sourceSchemas.length - syncedSchemas.length;
+    logSchemaInfo(
+      `Synced ${syncedSchemas.length} schema${syncedSchemas.length === 1 ? '' : 's'} from schema source "${source.name}"${
+        skippedSchemas > 0 ? ` (${skippedSchemas} skipped)` : ''
+      }`
+    );
+  }
+
+  return [
+    ...localSchemas,
+    ...resolvedExternalSchemas,
+    ...schemas.filter((schema) => schema.filePath && !schemaFileExists(schema)),
+  ].filter((schema) => {
+    if (schema.filePath) return schemaFileExists(schema);
+    return resolvedExternalSchemaIds.has(schema.id);
+  });
+};
+
+const loadMessageSchemaResources = async ({ pattern, base }: SchemaLoaderOptions['messages']) => {
   if (!base) return [];
 
   const files = await glob(pattern, {
@@ -189,14 +457,32 @@ export const loadMessageSchemas = async ({ pattern, base }: SchemaLoaderOptions[
       if (!collection) return [];
 
       const { data } = matter.read(file) as { data: MessageFrontmatter };
-      return getMessageSchemasFromFrontmatter({ data, collection, messageFilePath: file });
+      return getMessageSchemasFromFrontmatter({ data, collection, messageFilePath: file }).map((schema) => ({
+        ...schema,
+        _context: {
+          messageFilePath: file,
+        },
+      }));
     })
   );
 
-  return addLatestMetadata(schemas.flat().filter(schemaFileExists));
+  return schemas.flat();
+};
+
+const stripSchemaLoaderContext = (schema: InternalMessageSchemaResource): MessageSchemaResource => {
+  const { _context, ...publicSchema } = schema;
+  return publicSchema;
+};
+
+export const loadMessageSchemas = async (messages: SchemaLoaderOptions['messages'], sources: SchemaSource[] = []) => {
+  const schemas = await loadMessageSchemaResources(messages);
+  const resolvedSchemas = await resolveSchemaSources(schemas, sources);
+
+  return addLatestMetadata(resolvedSchemas.map(stripSchemaLoaderContext));
 };
 
 const getSchemaBody = async (schema: MessageSchemaResource) => {
+  if (schema.content !== undefined) return schema.content;
   if (!schemaFileExists(schema)) return undefined;
   return fs.readFile(schema.filePath, 'utf8');
 };
@@ -222,12 +508,12 @@ const setSchema = async (context: LoaderContext, schema: MessageSchemaResource)
   });
 };
 
-export const schemaLoader = ({ messages }: SchemaLoaderOptions): Loader => {
+export const schemaLoader = ({ messages, sources = [] }: SchemaLoaderOptions): Loader => {
   return {
     name: 'eventcatalog-schema-loader',
     load: async (context) => {
       context.store.clear();
-      const schemas = await loadMessageSchemas(messages);
+      const schemas = await loadMessageSchemas(messages, sources);
 
       for (const schema of schemas) {
         await setSchema(context, schema);

package/eventcatalog/src/utils/files.ts

@@ -1,4 +1,4 @@
-import path from 'node:path';
+import * as path from 'node:path';
 
 /**
  * Resolves a file path relative to PROJECT_DIR, handling ../ paths correctly

package/package.json

@@ -7,7 +7,7 @@
   },
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
-  "version": "3.45.0",
+  "version": "3.46.1",
   "publishConfig": {
     "access": "public"
   },
@@ -65,7 +65,6 @@
     "auth-astro": "^4.2.0",
     "boxen": "^8.0.1",
     "commander": "^12.1.0",
-    "concurrently": "^8.2.2",
     "cross-env": "^7.0.3",
     "dagre": "^0.8.5",
     "diff": "^8.0.3",
@@ -74,7 +73,7 @@
     "elkjs": "^0.10.0",
     "glob": "^13.0.6",
     "gray-matter": "^4.0.3",
-    "hono": "4.12.18",
+    "hono": "4.12.21",
     "html-to-image": "^1.11.11",
     "js-yaml": "^4.1.1",
     "jsonpath-plus": "^10.4.0",
@@ -112,8 +111,8 @@
     "update-notifier": "^7.3.1",
     "uuid": "^10.0.0",
     "zod": "^4.3.6",
-    "@eventcatalog/sdk": "2.24.1",
     "@eventcatalog/linter": "1.0.29",
+    "@eventcatalog/sdk": "2.24.1",
     "@eventcatalog/visualiser": "^3.22.1"
   },
   "devDependencies": {