@eventcatalog/core 3.45.0 → 3.46.0

package/dist/analytics/analytics.cjs

@@ -36,7 +36,7 @@ module.exports = __toCommonJS(analytics_exports);
 var import_os = __toESM(require("os"), 1);
 
 // package.json
-var version = "3.45.0";
+var version = "3.46.0";
 
 // src/constants.ts
 var VERSION = version;

package/dist/analytics/analytics.js

@@ -1,7 +1,7 @@
 import {
   raiseEvent
-} from "../chunk-6XNMBNIU.js";
-import "../chunk-E4K4KTSR.js";
+} from "../chunk-JS6IYB55.js";
+import "../chunk-DOHA5HNJ.js";
 export {
   raiseEvent
 };

package/dist/analytics/log-build.cjs

@@ -140,7 +140,7 @@ var verifyRequiredFieldsAreInCatalogConfigFile = async (projectDirectory) => {
 var import_os = __toESM(require("os"), 1);
 
 // package.json
-var version = "3.45.0";
+var version = "3.46.0";
 
 // src/constants.ts
 var VERSION = version;

package/dist/analytics/log-build.js

@@ -1,9 +1,9 @@
 import {
   log_build_default
-} from "../chunk-2QK37BNF.js";
-import "../chunk-6XNMBNIU.js";
+} from "../chunk-FNOYJEUK.js";
+import "../chunk-JS6IYB55.js";
 import "../chunk-DAOXTQVS.js";
-import "../chunk-E4K4KTSR.js";
+import "../chunk-DOHA5HNJ.js";
 import "../chunk-6QENHZZP.js";
 export {
   log_build_default as default

package/dist/{chunk-E4K4KTSR.js → chunk-DOHA5HNJ.js}

@@ -1,5 +1,5 @@
 // package.json
-var version = "3.45.0";
+var version = "3.46.0";
 
 // src/constants.ts
 var VERSION = version;

package/dist/{chunk-2QK37BNF.js → chunk-FNOYJEUK.js}

@@ -1,6 +1,6 @@
 import {
   raiseEvent
-} from "./chunk-6XNMBNIU.js";
+} from "./chunk-JS6IYB55.js";
 import {
   countResources,
   serializeCounts

package/dist/{chunk-6XNMBNIU.js → chunk-JS6IYB55.js}

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-E4K4KTSR.js";
+} from "./chunk-DOHA5HNJ.js";
 
 // src/analytics/analytics.js
 import os from "os";

package/dist/{chunk-G6KYCMUM.js → chunk-TLLUDBO4.js}

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-E4K4KTSR.js";
+} from "./chunk-DOHA5HNJ.js";
 
 // src/utils/cli-logger.ts
 import pc from "picocolors";

package/dist/{chunk-KHL25572.js → chunk-X4AESI6E.js}

@@ -1,6 +1,6 @@
 import {
   logger
-} from "./chunk-G6KYCMUM.js";
+} from "./chunk-TLLUDBO4.js";
 import {
   cleanup,
   getEventCatalogConfigFile

package/dist/constants.cjs

@@ -25,7 +25,7 @@ __export(constants_exports, {
 module.exports = __toCommonJS(constants_exports);
 
 // package.json
-var version = "3.45.0";
+var version = "3.46.0";
 
 // src/constants.ts
 var VERSION = version;

package/dist/constants.js

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-E4K4KTSR.js";
+} from "./chunk-DOHA5HNJ.js";
 export {
   VERSION
 };

package/dist/eventcatalog.cjs

@@ -144,7 +144,7 @@ var verifyRequiredFieldsAreInCatalogConfigFile = async (projectDirectory) => {
 var import_picocolors = __toESM(require("picocolors"), 1);
 
 // package.json
-var version = "3.45.0";
+var version = "3.46.0";
 
 // src/constants.ts
 var VERSION = version;

package/dist/eventcatalog.config.d.cts

@@ -58,6 +58,28 @@ type DirectorySource = {
     loadUsers?: () => Promise<DirectoryEntry[]>;
     loadTeams?: () => Promise<DirectoryEntry[]>;
 };
+type SchemaEntry = {
+    id: string;
+    name?: string;
+    format?: string;
+    content: string;
+    source: {
+        provider: string;
+        id?: string;
+        url?: string;
+        ref?: string;
+        path?: string;
+        [key: string]: unknown;
+    };
+};
+type SchemaSource = {
+    type: 'schemas';
+    name: string;
+    canResolve: (id: string) => boolean;
+    resolve: (id: string, context?: {
+        messageFilePath?: string;
+    }) => Promise<SchemaEntry | undefined>;
+};
 type DirectoryConfig = {
     /**
      * External sources that sync users and teams into EventCatalog.
@@ -71,6 +93,12 @@ type DirectoryConfig = {
      */
     conflictStrategy?: 'local-wins' | 'source-wins' | 'error';
 };
+type SchemaConfig = {
+    /**
+     * External sources that resolve message schema references into the generated schemas collection.
+     */
+    sources?: SchemaSource[];
+};
 type AuthConfig = {
     enabled: boolean;
 };
@@ -221,6 +249,7 @@ interface Config {
         domains?: ResourceDependency[];
     };
     directory?: DirectoryConfig;
+    schemas?: SchemaConfig;
     mermaid?: {
         maxTextSize?: number;
         iconPacks?: string[];

package/dist/eventcatalog.config.d.ts

@@ -58,6 +58,28 @@ type DirectorySource = {
     loadUsers?: () => Promise<DirectoryEntry[]>;
     loadTeams?: () => Promise<DirectoryEntry[]>;
 };
+type SchemaEntry = {
+    id: string;
+    name?: string;
+    format?: string;
+    content: string;
+    source: {
+        provider: string;
+        id?: string;
+        url?: string;
+        ref?: string;
+        path?: string;
+        [key: string]: unknown;
+    };
+};
+type SchemaSource = {
+    type: 'schemas';
+    name: string;
+    canResolve: (id: string) => boolean;
+    resolve: (id: string, context?: {
+        messageFilePath?: string;
+    }) => Promise<SchemaEntry | undefined>;
+};
 type DirectoryConfig = {
     /**
      * External sources that sync users and teams into EventCatalog.
@@ -71,6 +93,12 @@ type DirectoryConfig = {
      */
     conflictStrategy?: 'local-wins' | 'source-wins' | 'error';
 };
+type SchemaConfig = {
+    /**
+     * External sources that resolve message schema references into the generated schemas collection.
+     */
+    sources?: SchemaSource[];
+};
 type AuthConfig = {
     enabled: boolean;
 };
@@ -221,6 +249,7 @@ interface Config {
         domains?: ResourceDependency[];
     };
     directory?: DirectoryConfig;
+    schemas?: SchemaConfig;
     mermaid?: {
         maxTextSize?: number;
         iconPacks?: string[];

package/dist/eventcatalog.js

@@ -1,7 +1,8 @@
 import {
-  runMigrations
-} from "./chunk-XUAF2H54.js";
-import "./chunk-CA4U2JP7.js";
+  log_build_default
+} from "./chunk-FNOYJEUK.js";
+import "./chunk-JS6IYB55.js";
+import "./chunk-DAOXTQVS.js";
 import {
   resolve_catalog_dependencies_default
 } from "./chunk-LHR4G2UO.js";
@@ -12,10 +13,9 @@ import {
   watch
 } from "./chunk-3H2RT3CM.js";
 import {
-  log_build_default
-} from "./chunk-2QK37BNF.js";
-import "./chunk-6XNMBNIU.js";
-import "./chunk-DAOXTQVS.js";
+  runMigrations
+} from "./chunk-XUAF2H54.js";
+import "./chunk-CA4U2JP7.js";
 import {
   catalogToAstro
 } from "./chunk-4SMA4HQ3.js";
@@ -28,13 +28,13 @@ import {
 } from "./chunk-B7HCX5HM.js";
 import {
   generate
-} from "./chunk-KHL25572.js";
+} from "./chunk-X4AESI6E.js";
 import {
   logger
-} from "./chunk-G6KYCMUM.js";
+} from "./chunk-TLLUDBO4.js";
 import {
   VERSION
-} from "./chunk-E4K4KTSR.js";
+} from "./chunk-DOHA5HNJ.js";
 import {
   getEventCatalogConfigFile,
   verifyRequiredFieldsAreInCatalogConfigFile

package/dist/generate.cjs

@@ -108,7 +108,7 @@ var getEventCatalogConfigFile = async (projectDirectory) => {
 var import_picocolors = __toESM(require("picocolors"), 1);
 
 // package.json
-var version = "3.45.0";
+var version = "3.46.0";
 
 // src/constants.ts
 var VERSION = version;

package/dist/generate.js

@@ -1,8 +1,8 @@
 import {
   generate
-} from "./chunk-KHL25572.js";
-import "./chunk-G6KYCMUM.js";
-import "./chunk-E4K4KTSR.js";
+} from "./chunk-X4AESI6E.js";
+import "./chunk-TLLUDBO4.js";
+import "./chunk-DOHA5HNJ.js";
 import "./chunk-6QENHZZP.js";
 export {
   generate

package/dist/utils/cli-logger.cjs

@@ -36,7 +36,7 @@ module.exports = __toCommonJS(cli_logger_exports);
 var import_picocolors = __toESM(require("picocolors"), 1);
 
 // package.json
-var version = "3.45.0";
+var version = "3.46.0";
 
 // src/constants.ts
 var VERSION = version;

package/dist/utils/cli-logger.js

@@ -1,7 +1,7 @@
 import {
   logger
-} from "../chunk-G6KYCMUM.js";
-import "../chunk-E4K4KTSR.js";
+} from "../chunk-TLLUDBO4.js";
+import "../chunk-DOHA5HNJ.js";
 export {
   logger
 };

package/eventcatalog/astro.config.mjs

@@ -19,6 +19,11 @@ import rehypeExpressiveCode from 'rehype-expressive-code';
 /** @type {import('bin/eventcatalog.config').Config} */
 import config from './eventcatalog.config';
 import expressiveCode from 'astro-expressive-code';
+// Expressive Code options (including the non-serializable `themeCssSelector`
+// function) live in ec.config.mjs. The `expressiveCode()` integration loads that
+// file automatically; the rehype plugin used by mdx() below needs it passed
+// explicitly, so we import it here to keep a single source of truth.
+import expressiveCodeConfig from './ec.config.mjs';
 import ecstudioWatcher from './integrations/ecstudio-watcher.mjs';
 import eventCatalogIntegration from './src/enterprise/integrations/eventcatalog-features.ts';
 
@@ -30,13 +35,6 @@ const isDevMode = process.env.EVENTCATALOG_DEV_MODE === 'true';
 const effectiveOutput = isDevMode ? 'server' : config.output || 'static';
 const searchType = config.search?.type || 'resource';
 
-const expressiveCodeConfig = {
-  themes: ['github-light', 'github-dark'],
-  defaultProps: {
-    wrap: true,
-  },
-};
-
 const markdownRemarkPlugins = [remarkDirective, remarkDirectives, remarkComment, mermaid, plantuml];
 const mdxRemarkPlugins = [...markdownRemarkPlugins, remarkResourceRef];
 
@@ -78,9 +76,8 @@ export default defineConfig({
   devToolbar: { enabled: false },
   integrations: [
     react(),
-    expressiveCode({
-      ...expressiveCodeConfig,
-    }),
+    // Options are loaded automatically from ec.config.mjs.
+    expressiveCode(),
     mdx({
       // https://docs.astro.build/en/guides/integrations-guide/mdx/#optimize
       optimize: config.mdxOptimize || false,

package/eventcatalog/ec.config.mjs

@@ -0,0 +1,20 @@
+import { defineEcConfig } from 'astro-expressive-code';
+
+// Expressive Code configuration lives in this dedicated file (rather than inline
+// in astro.config.mjs) because it contains non-serializable options such as the
+// `themeCssSelector` function. Astro's `<Code>` component (used on the print
+// pages) requires Expressive Code options coming from the Astro config to be
+// JSON-serializable, so functions must be defined here instead.
+//
+// `useDarkModeMediaQuery: false` + `themeCssSelector` make code blocks follow
+// EventCatalog's own `data-theme` toggle instead of the OS `prefers-color-scheme`
+// media query, so they stay readable when the catalog theme and the OS
+// preference disagree (see issue #2607).
+export default defineEcConfig({
+  themes: ['github-light', 'github-dark'],
+  useDarkModeMediaQuery: false,
+  themeCssSelector: (theme) => `[data-theme='${theme.type}']`,
+  defaultProps: {
+    wrap: true,
+  },
+});

package/eventcatalog/src/components/MDX/SchemaViewer/SchemaViewerPortal.tsx

@@ -5,7 +5,7 @@ const SchemaViewerPortal = (props: any) => {
 
   return (
     <div
-      id={`${props.id}-${props.file}-SchemaViewer-portal`}
+      data-schema-viewer-portal-id={props.id}
       data-expand={expandBool ? 'true' : 'false'}
       data-max-height={props.maxHeight}
       data-search={searchBool ? 'true' : 'false'}

package/eventcatalog/src/components/MDX/SchemaViewer/SchemaViewerRoot.astro

@@ -1,13 +1,13 @@
 ---
-const { id, filePath } = Astro.props;
+const { id, filePath, collection, version } = Astro.props;
 import fs from 'node:fs/promises';
-import { existsSync } from 'fs';
-import yaml from 'js-yaml';
+import { getCollection } from 'astro:content';
 import JSONSchemaViewer from '@components/SchemaExplorer/JSONSchemaViewer';
 import AvroSchemaViewer from '@components/SchemaExplorer/AvroSchemaViewer';
 import Admonition from '../Admonition';
 import { getMDXComponentsByName } from '@utils/markdown';
-import { getAbsoluteFilePathForAstroFile, resolveProjectPath, isAvroSchema } from '@utils/files';
+import { resolveProjectPath } from '@utils/files';
+import { resolveSchemaViewer } from './schema-viewer-utils';
 
 let schemas = [];
 
@@ -15,45 +15,11 @@ try {
   const absoluteFilePath = resolveProjectPath(filePath);
   const file = await fs.readFile(absoluteFilePath, 'utf-8');
   const schemaViewers = getMDXComponentsByName(file, 'SchemaViewer');
+  const collectionSchemas = collection && version ? await getCollection('schemas') : [];
 
-  // Loop around all the possible SchemaViewers in the file.
-  const getAllComponents = schemaViewers.map(async (schemaViewerProps: any, index: number) => {
-    const schemaPath = getAbsoluteFilePathForAstroFile(filePath, schemaViewerProps.file);
-    const exists = existsSync(schemaPath);
-    let schema;
-    let render = true;
-    let isAvro = false;
-
-    if (exists) {
-      // Check if this is an Avro schema file
-      isAvro = isAvroSchema(schemaPath);
-
-      // Load the schema for the component
-      schema = await fs.readFile(schemaPath, 'utf-8');
-
-      if (schemaPath.endsWith('.yml') || schemaPath.endsWith('.yaml')) {
-        schema = yaml.load(schema);
-      } else {
-        schema = JSON.parse(schema);
-
-        // For non-Avro schemas, let JSON schema control if the component should be rendered
-        if (!isAvro && schema['x-eventcatalog-render-schema-viewer'] !== undefined) {
-          render = schema['x-eventcatalog-render-schema-viewer'];
-        }
-      }
-    }
-
-    return {
-      id: schemaViewerProps.id || id,
-      exists,
-      schema,
-      schemaPath,
-      isAvroSchema: isAvro,
-      ...schemaViewerProps,
-      render,
-      index,
-    };
-  });
+  const getAllComponents = schemaViewers.map((schemaViewerProps: any, index: number) =>
+    resolveSchemaViewer({ id, version, collection, filePath, schemaViewerProps, collectionSchemas, index })
+  );
 
   schemas = await Promise.all(getAllComponents);
 } catch (error) {
@@ -71,8 +37,10 @@ try {
           <div>
             {schema.exists && (
               <div
-                id={`${schema.id}-${schema.file}-SchemaViewer-client`}
+                id={`${schema.id}-${schema.index}-SchemaViewer-client`}
                 class="not-prose my-4"
+                data-schema-viewer-client-id={schema.id}
+                data-schema-viewer-index={schema.index}
                 data-expand={schema.expand ? 'true' : 'false'}
                 data-search={schema.search !== false ? 'true' : 'false'}
               >
@@ -105,7 +73,11 @@ try {
               <Admonition type="warning">
                 <div>
                   <span class="block font-bold">{`<SchemaViewer/>`} failed to load</span>
-                  <span class="block">Tried to load schema from {schema.schemaPath}, but no schema can be found</span>
+                  <span class="block">
+                    {schema.parseError
+                      ? `Tried to parse schema from ${schema.schemaPath}, but it failed: ${schema.parseError}`
+                      : `Tried to load schema from ${schema.schemaPath || schema.file || 'the message schema collection'}, but no schema can be found`}
+                  </span>
                 </div>
               </Admonition>
             )}
@@ -120,9 +92,9 @@ try {
   // and then we can move the SchemaViewerClient to that container?
 
   function moveSchemaViewerToPortal(schema) {
-    const portalId = `${schema.id}-${schema.file}-SchemaViewer-portal`;
-    const schemaViewerContainer = document.getElementById(portalId);
-    const schemaViewerClient = document.getElementById(`${schema.id}-${schema.file}-SchemaViewer-client`);
+    const schemaViewerContainers = document.querySelectorAll(`[data-schema-viewer-portal-id="${schema.id}"]`);
+    const schemaViewerContainer = schemaViewerContainers[schema.index];
+    const schemaViewerClient = document.getElementById(`${schema.id}-${schema.index}-SchemaViewer-client`);
 
     if (schemaViewerContainer && schemaViewerClient) {
       // Get attributes from the portal

package/eventcatalog/src/components/MDX/SchemaViewer/schema-viewer-utils.spec.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest';
+import { resolveSchemaViewer } from './schema-viewer-utils';
+
+const currentMessageSchema = {
+  id: 'schema:events:OrderPlaced:1.0.0:git://contracts/events/OrderPlaced.schema.json',
+  data: {
+    ref: 'git://contracts/events/OrderPlaced.schema.json',
+    format: 'jsonschema',
+    content: '{"type":"object","title":"OrderPlaced"}',
+    default: true,
+    message: {
+      collection: 'events',
+      id: 'OrderPlaced',
+      version: '1.0.0',
+    },
+  },
+};
+
+describe('resolveSchemaViewer', () => {
+  it('uses the current message default schema when no file is set', async () => {
+    const schema = await resolveSchemaViewer({
+      id: 'OrderPlaced',
+      version: '1.0.0',
+      collection: 'events',
+      filePath: 'events/OrderPlaced/index.mdx',
+      schemaViewerProps: {},
+      collectionSchemas: [currentMessageSchema],
+      index: 0,
+    });
+
+    expect(schema.exists).toBe(true);
+    expect(schema.schema.title).toBe('OrderPlaced');
+    expect(schema.schemaPath).toBe('git://contracts/events/OrderPlaced.schema.json');
+  });
+
+  it('does not use the schema collection when a file is set and missing', async () => {
+    const schema = await resolveSchemaViewer({
+      id: 'OrderPlaced',
+      version: '1.0.0',
+      collection: 'events',
+      filePath: 'events/OrderPlaced/index.mdx',
+      schemaViewerProps: {
+        file: 'missing-schema.json',
+      },
+      collectionSchemas: [currentMessageSchema],
+      index: 0,
+    });
+
+    expect(schema.exists).toBe(false);
+    expect(schema.schema).toBeUndefined();
+    expect(schema.schemaKey).toBe('missing-schema.json');
+  });
+});

package/eventcatalog/src/components/MDX/SchemaViewer/schema-viewer-utils.ts

@@ -0,0 +1,133 @@
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { load as loadYaml } from 'js-yaml';
+import { getAbsoluteFilePathForAstroFile, isAvroSchema } from '../../../utils/files';
+
+type SchemaViewerProps = {
+  id?: string;
+  file?: string;
+  [key: string]: any;
+};
+
+type CollectionSchema = {
+  id: string;
+  data: {
+    content?: string;
+    file?: string;
+    filePath?: string;
+    ref?: string;
+    format?: string;
+    default?: boolean;
+    source?: {
+      path?: string;
+      branch?: string;
+    };
+    message?: {
+      collection: string;
+      id: string;
+      version: string;
+    };
+  };
+};
+
+type ResolveSchemaViewerOptions = {
+  id: string;
+  version?: string;
+  collection?: string;
+  filePath: string;
+  schemaViewerProps: SchemaViewerProps;
+  collectionSchemas: CollectionSchema[];
+  index: number;
+};
+
+export const getSchemaViewerKey = (schemaViewerProps: SchemaViewerProps) => schemaViewerProps.file || 'default';
+
+const isYamlSchema = (schemaPath?: string, format?: string) =>
+  schemaPath?.endsWith('.yml') || schemaPath?.endsWith('.yaml') || format === 'yaml';
+
+const isAvroSchemaReference = (schemaPath?: string, format?: string) =>
+  format === 'avro' || (schemaPath ? isAvroSchema(schemaPath) : false);
+
+const parseSchemaContent = (content: string, schemaPath?: string, format?: string) => {
+  if (isYamlSchema(schemaPath, format)) return loadYaml(content);
+  return JSON.parse(content);
+};
+
+const shouldRenderSchema = (schema: any, isAvro: boolean) => {
+  if (isAvro) return true;
+  return schema?.['x-eventcatalog-render-schema-viewer'] !== undefined ? schema['x-eventcatalog-render-schema-viewer'] : true;
+};
+
+const getCollectionSchemaForViewer = ({
+  collectionSchemas,
+  collection,
+  id,
+  version,
+}: Pick<ResolveSchemaViewerOptions, 'collectionSchemas' | 'collection' | 'id' | 'version'>) => {
+  if (!collection || !version) return undefined;
+
+  const resourceSchemas = collectionSchemas.filter((schema) => {
+    const message = schema.data.message;
+    if (!message) return false;
+    return message.collection === collection && message.id === id && message.version === version;
+  });
+
+  return resourceSchemas.find((schema) => schema.data.default) || resourceSchemas[0];
+};
+
+const getCollectionSchemaPath = (schema?: CollectionSchema) =>
+  schema?.data.filePath || schema?.data.file || schema?.data.source?.path || schema?.data.ref;
+
+export const resolveSchemaViewer = async ({
+  id,
+  version,
+  collection,
+  filePath,
+  schemaViewerProps,
+  collectionSchemas,
+  index,
+}: ResolveSchemaViewerOptions) => {
+  const schemaKey = getSchemaViewerKey(schemaViewerProps);
+  const localSchemaPath = schemaViewerProps.file ? getAbsoluteFilePathForAstroFile(filePath, schemaViewerProps.file) : undefined;
+  const localSchemaExists = localSchemaPath ? existsSync(localSchemaPath) : false;
+
+  let schema;
+  let render = true;
+  let isAvro = false;
+  let schemaPath = localSchemaPath;
+  let parseError;
+
+  if (localSchemaExists && localSchemaPath) {
+    isAvro = isAvroSchema(localSchemaPath);
+    const content = await readFile(localSchemaPath, 'utf-8');
+    schema = parseSchemaContent(content, localSchemaPath);
+    render = shouldRenderSchema(schema, isAvro);
+  } else if (!schemaViewerProps.file) {
+    const collectionSchema = getCollectionSchemaForViewer({ collectionSchemas, collection, id, version });
+    const content = collectionSchema?.data.content;
+    schemaPath = getCollectionSchemaPath(collectionSchema);
+
+    if (content) {
+      try {
+        isAvro = isAvroSchemaReference(schemaPath, collectionSchema?.data.format);
+        schema = parseSchemaContent(content, schemaPath, collectionSchema?.data.format);
+        render = shouldRenderSchema(schema, isAvro);
+      } catch (error) {
+        parseError = error instanceof Error ? error.message : 'Unknown parsing error';
+      }
+    }
+  }
+
+  return {
+    id: schemaViewerProps.id || id,
+    exists: localSchemaExists || schema !== undefined,
+    schema,
+    schemaPath,
+    schemaKey,
+    isAvroSchema: isAvro,
+    parseError,
+    ...schemaViewerProps,
+    render,
+    index,
+  };
+};

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/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.0",
   "publishConfig": {
     "access": "public"
   },
@@ -74,7 +74,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 +112,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": {