@eventcatalog/core 4.3.1 → 4.3.2

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 = "4.3.1";
+var version = "4.3.2";
 
 // src/constants.ts
 var VERSION = version;

package/dist/analytics/analytics.js

@@ -1,7 +1,7 @@
 import {
   raiseEvent
-} from "../chunk-GC6SSPJI.js";
-import "../chunk-E3KVC4LF.js";
+} from "../chunk-BYH34SOZ.js";
+import "../chunk-W4UBACYZ.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 = "4.3.1";
+var version = "4.3.2";
 
 // src/constants.ts
 var VERSION = version;

package/dist/analytics/log-build.js

@@ -1,9 +1,9 @@
 import {
   log_build_default
-} from "../chunk-ZYVGVWMQ.js";
+} from "../chunk-25RQCO2H.js";
 import "../chunk-K2XIENVT.js";
-import "../chunk-GC6SSPJI.js";
-import "../chunk-E3KVC4LF.js";
+import "../chunk-BYH34SOZ.js";
+import "../chunk-W4UBACYZ.js";
 import "../chunk-6QENHZZP.js";
 export {
   log_build_default as default

package/dist/{chunk-ZYVGVWMQ.js → chunk-25RQCO2H.js}

@@ -4,7 +4,7 @@ import {
 } from "./chunk-K2XIENVT.js";
 import {
   raiseEvent
-} from "./chunk-GC6SSPJI.js";
+} from "./chunk-BYH34SOZ.js";
 import {
   getEventCatalogConfigFile,
   verifyRequiredFieldsAreInCatalogConfigFile

package/dist/{chunk-GC6SSPJI.js → chunk-BYH34SOZ.js}

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

package/dist/{chunk-GC7WNQP6.js → chunk-T6UEDS2J.js}

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

package/dist/{chunk-E3KVC4LF.js → chunk-W4UBACYZ.js}

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

package/dist/{chunk-UXHV3GN7.js → chunk-YBNWZEFQ.js}

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

package/dist/constants.cjs

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

package/dist/constants.js

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

package/dist/docs/development/guides/resources/entities/03-model-entity-relationships.md

@@ -42,8 +42,11 @@ Use these fields on an entity property:
 
 - `references`: The id of the entity being referenced.
 - `referencesIdentifier`: The property on the referenced entity that this property matches.
+- `referenceTarget`: Set to `entity` when the relationship should point to the referenced entity as a whole.
 - `relationType`: The relationship label, such as `belongsTo`, `hasOne`, `hasMany`, or a business-specific label.
 
+`referenceTarget` is opt-in. When it is omitted, EventCatalog retains the existing behavior of targeting `referencesIdentifier`, the referenced entity's `identifier`, or its first property.
+
 ## Example relationship
 
 ```md title="/entities/order/index.mdx"
@@ -83,6 +86,49 @@ properties:
 
 This tells EventCatalog that `order.customerId` references the `customer.customerId` identifier.
 
+## Reference a whole entity
+
+Use `referenceTarget: entity` when the relationship is to the entity rather than one of its properties.
+
+```yaml
+properties:
+  - name: customer
+    type: object
+    references: customer
+    referenceTarget: entity
+    relationType: placedBy
+```
+
+This renders the relationship against the `Customer` entity header. Existing relationships that omit `referenceTarget` continue to use property-level targeting.
+
+## Model embedded objects
+
+Use nested `properties` for a value object that only exists as part of its parent entity. Embedded objects have no entity id and cannot be referenced independently from elsewhere in the catalog.
+
+```yaml
+properties:
+  - name: deliveryAddress
+    type: object
+    properties:
+      - name: line1
+        type: string
+        required: true
+      - name: city
+        type: string
+        required: true
+  - name: adjustments
+    type: array
+    items:
+      type: object
+      properties:
+        - name: reason
+          type: string
+        - name: amount
+          type: decimal
+```
+
+Embedded properties appear inside their parent entity rather than as separate nodes in entity maps.
+
 ## Relationship direction
 
 Define the relationship where the reference exists.

package/dist/docs/development/guides/resources/entities/06-reference.md

@@ -258,9 +258,13 @@ attachments:
 | `description` | `string` | Description of the property. |
 | `references` | `string` | Entity id referenced by this property. |
 | `referencesIdentifier` | `string` | Identifier property on the referenced entity. |
+| `referenceTarget` | `entity` | Targets the referenced entity as a whole instead of one of its properties. |
 | `relationType` | `string` | Relationship label shown in entity maps. |
 | `enum` | `array` | Allowed string values. |
-| `items` | `object` | Item type for array properties. |
+| `properties` | `array` | Nested properties for an embedded object. |
+| `items` | `object` | Item type and optional nested properties for array properties. |
+
+Property definitions are recursive, so embedded objects and arrays of embedded objects can contain their own `properties`. Embedded objects are owned by their parent entity and are not independently referenceable catalog resources.
 
 ## EntityPropertiesTable component
 

package/dist/eventcatalog.cjs

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

package/dist/eventcatalog.js

@@ -1,6 +1,6 @@
 import {
   log_build_default
-} from "./chunk-ZYVGVWMQ.js";
+} from "./chunk-25RQCO2H.js";
 import "./chunk-K2XIENVT.js";
 import {
   runMigrations
@@ -14,10 +14,10 @@ import {
 } from "./chunk-B7HCX5HM.js";
 import {
   generate
-} from "./chunk-UXHV3GN7.js";
+} from "./chunk-YBNWZEFQ.js";
 import {
   logger
-} from "./chunk-GC7WNQP6.js";
+} from "./chunk-T6UEDS2J.js";
 import {
   resolve_catalog_dependencies_default
 } from "./chunk-LHR4G2UO.js";
@@ -27,7 +27,7 @@ import {
 import {
   watch
 } from "./chunk-CAJUIMDJ.js";
-import "./chunk-GC6SSPJI.js";
+import "./chunk-BYH34SOZ.js";
 import {
   createAstroDevLineFilter,
   createAstroLineFilter
@@ -38,7 +38,7 @@ import {
 import "./chunk-W5JQON7Z.js";
 import {
   VERSION
-} from "./chunk-E3KVC4LF.js";
+} from "./chunk-W4UBACYZ.js";
 import {
   linkCoreNodeModules,
   resolveInstalledCoreNodeModules

package/dist/generate.cjs

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

package/dist/generate.js

@@ -1,8 +1,8 @@
 import {
   generate
-} from "./chunk-UXHV3GN7.js";
-import "./chunk-GC7WNQP6.js";
-import "./chunk-E3KVC4LF.js";
+} from "./chunk-YBNWZEFQ.js";
+import "./chunk-T6UEDS2J.js";
+import "./chunk-W4UBACYZ.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 = "4.3.1";
+var version = "4.3.2";
 
 // src/constants.ts
 var VERSION = version;

package/dist/utils/cli-logger.js

@@ -1,7 +1,7 @@
 import {
   logger
-} from "../chunk-GC7WNQP6.js";
-import "../chunk-E3KVC4LF.js";
+} from "../chunk-T6UEDS2J.js";
+import "../chunk-W4UBACYZ.js";
 export {
   logger
 };

package/eventcatalog/src/components/MDX/EntityPropertiesTable/EntityPropertiesTable.astro

@@ -8,12 +8,31 @@ type EntityProperty = {
   type: string;
   required?: boolean;
   description?: string;
+  references?: string;
+  referencesIdentifier?: string;
+  referenceTarget?: 'entity';
   enum?: string[];
+  properties?: EntityProperty[];
   items?: {
     type: string;
+    properties?: EntityProperty[];
   };
 };
 
+type EntityPropertyRow = {
+  property: EntityProperty;
+  depth: number;
+};
+
+const getNestedProperties = (property: EntityProperty) =>
+  property.properties || (property.type === 'array' ? property.items?.properties : undefined) || [];
+
+const flattenProperties = (entityProperties: EntityProperty[], depth = 0): EntityPropertyRow[] =>
+  entityProperties.flatMap((property) => [{ property, depth }, ...flattenProperties(getNestedProperties(property), depth + 1)]);
+
+const getPropertyTypeLabel = (property: EntityProperty) =>
+  property.type === 'array' && property.items ? `${property.items.type}[]` : property.type;
+
 // Expects a CollectionEntry for 'entities'.
 // The actual properties structure might differ slightly from the base type,
 // so we handle it below.
@@ -22,6 +41,7 @@ export interface Props extends CollectionEntry<'entities'> {}
 const { data, collection } = Astro.props;
 // Cast the properties to our expected type for use in the template
 const properties = data?.properties as EntityProperty[] | undefined;
+const propertyRows = flattenProperties(properties || []);
 const isComponentEnabled = collection === 'entities';
 ---
 
@@ -56,23 +76,23 @@ const isComponentEnabled = collection === 'entities';
             <th scope="col" class="py-3 px-6 min-w-[250px]">
               Description
             </th>
+            <th scope="col" class="py-3 px-6 min-w-[180px]">
+              Reference
+            </th>
           </tr>
         </thead>
         <tbody>
-          {properties.map((prop) => (
+          {propertyRows.map(({ property: prop, depth }) => (
             <tr class="bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))] border-b border-[rgb(var(--ec-page-border))] hover:bg-[rgb(var(--ec-content-hover))] align-top">
-              <td class="py-4 px-6 font-medium text-[rgb(var(--ec-page-text))] whitespace-nowrap">
+              <td
+                class="py-4 pr-6 font-medium text-[rgb(var(--ec-page-text))] whitespace-nowrap"
+                style={`padding-left: ${24 + depth * 20}px`}
+              >
+                {depth > 0 && <span class="mr-1 text-[rgb(var(--ec-icon-color))]">↳</span>}
                 <code class="text-sm bg-[rgb(var(--ec-content-hover))] rounded px-1 py-0.5">{prop.name}</code>
               </td>
               <td class="py-4 px-6 text-[rgb(var(--ec-page-text-muted))]">
-                {prop.type === 'array' && prop.items ? (
-                  <span>
-                    array&lt;<code class="text-sm bg-[rgb(var(--ec-content-hover))] rounded px-1 py-0.5">{prop.items.type}</code>
-                    &gt;
-                  </span>
-                ) : (
-                  <code class="text-sm bg-[rgb(var(--ec-content-hover))] rounded px-1 py-0.5">{prop.type}</code>
-                )}
+                <code class="text-sm bg-[rgb(var(--ec-content-hover))] rounded px-1 py-0.5">{getPropertyTypeLabel(prop)}</code>
                 {prop.enum && (
                   <div class="text-xs text-[rgb(var(--ec-page-text-muted))] mt-2">
                     <span class="font-semibold block mb-1">Enum:</span>
@@ -100,6 +120,22 @@ const isComponentEnabled = collection === 'entities';
               <td class="py-4 px-6 text-[rgb(var(--ec-page-text-muted))]">
                 {prop.description || <span class="text-[rgb(var(--ec-icon-color))] italic">No description provided.</span>}
               </td>
+              <td class="py-4 px-6 text-[rgb(var(--ec-page-text-muted))]">
+                {prop.references ? (
+                  <div class="flex flex-col gap-1">
+                    <code class="text-sm bg-[rgb(var(--ec-content-hover))] rounded px-1 py-0.5 w-fit">{prop.references}</code>
+                    <span class="text-xs">
+                      {prop.referenceTarget === 'entity'
+                        ? 'Whole entity'
+                        : prop.referencesIdentifier
+                          ? `Property: ${prop.referencesIdentifier}`
+                          : 'Identifier or first property'}
+                    </span>
+                  </div>
+                ) : (
+                  <span class="text-[rgb(var(--ec-icon-color))]">—</span>
+                )}
+              </td>
             </tr>
           ))}
         </tbody>

package/eventcatalog/src/content.config.ts

@@ -963,6 +963,44 @@ const ubiquitousLanguages = defineCollection({
   }),
 });
 
+interface EntityPropertySchema {
+  name: string;
+  type: string;
+  required?: boolean;
+  description?: string;
+  references?: string;
+  referencesIdentifier?: string;
+  referenceTarget?: 'entity';
+  relationType?: string;
+  enum?: string[];
+  properties?: EntityPropertySchema[];
+  items?: {
+    type: string;
+    properties?: EntityPropertySchema[];
+  };
+}
+
+const entityPropertySchema: z.ZodType<EntityPropertySchema> = z.lazy(() =>
+  z.object({
+    name: z.string(),
+    type: z.string(),
+    required: z.boolean().optional(),
+    description: z.string().optional(),
+    references: z.string().optional(),
+    referencesIdentifier: z.string().optional(),
+    referenceTarget: z.literal('entity').optional(),
+    relationType: z.string().optional(),
+    enum: z.array(z.string()).optional(),
+    properties: z.array(entityPropertySchema).optional(),
+    items: z
+      .object({
+        type: z.string(),
+        properties: z.array(entityPropertySchema).optional(),
+      })
+      .optional(),
+  })
+);
+
 const entities = defineCollection({
   loader: globWithSafeWatcher({
     pattern: withIgnoredBuildArtifacts(['**/entities/*/index.(md|mdx)', '**/entities/*/versioned/*/index.(md|mdx)']),
@@ -976,25 +1014,7 @@ const entities = defineCollection({
       .object({
         aggregateRoot: z.boolean().optional(),
         identifier: z.string().optional(),
-        properties: z
-          .array(
-            z.object({
-              name: z.string(),
-              type: z.string(),
-              required: z.boolean().optional(),
-              description: z.string().optional(),
-              references: z.string().optional(),
-              referencesIdentifier: z.string().optional(),
-              relationType: z.string().optional(),
-              enum: z.array(z.string()).optional(),
-              items: z
-                .object({
-                  type: z.string(),
-                })
-                .optional(),
-            })
-          )
-          .optional(),
+        properties: z.array(entityPropertySchema).optional(),
         services: z.array(reference('services')).optional(),
         domains: z.array(reference('domains')).optional(),
         detailsPanel: z

package/eventcatalog/src/utils/node-graphs/domain-entity-map.ts

@@ -10,12 +10,19 @@ import { getServices, type Service } from '@utils/collections/services';
 
 const elk = new ELK();
 
+export const ENTITY_TARGET_HANDLE_ID = '__eventcatalog-entity-target';
+
 const getReferencedEntityId = (property: any, entityMap: Map<string, Entity[]>) => {
   if (property.references) return property.references;
   if (property.type === 'array' && property.items?.type && entityMap.has(property.items.type)) return property.items.type;
   return undefined;
 };
 
+const getReferencePropertyNames = (entity: Entity, entityMap: Map<string, Entity[]>) =>
+  entity.data.properties
+    ?.filter((property: any) => getReferencedEntityId(property, entityMap))
+    .map((property: any) => property.name) ?? [];
+
 const getRelationType = (property: any) => {
   if (property.relationType) return property.relationType;
   if (property.type === 'array' && property.items?.type) return 'hasMany';
@@ -64,7 +71,14 @@ export const getNodesAndEdges = async ({ id, version, entities, type = 'domains'
       id: nodeId,
       type: 'entities',
       position: { x: 0, y: 0 },
-      data: { label: entity.data.name, entity, domainName: resource?.data.name, domainId: resource?.data.id },
+      data: {
+        label: entity.data.name,
+        entity,
+        domainName: resource?.data.name,
+        domainId: resource?.data.id,
+        entityTargetHandle: ENTITY_TARGET_HANDLE_ID,
+        referencePropertyNames: getReferencePropertyNames(entity, entityMap),
+      },
     });
   }
 
@@ -116,6 +130,8 @@ export const getNodesAndEdges = async ({ id, version, entities, type = 'domains'
             externalToDomain: true,
             domainName: domainName,
             domainId: domainId,
+            entityTargetHandle: ENTITY_TARGET_HANDLE_ID,
+            referencePropertyNames: getReferencePropertyNames(externalEntity, entityMap),
           },
         });
         addedExternalEntities.push(externalEntity);
@@ -151,9 +167,12 @@ export const getNodesAndEdges = async ({ id, version, entities, type = 'domains'
         // Use the property name as the source handle
         const sourceHandle = `${referenceProperty.name}-source`;
 
-        // Use referencesIdentifier if provided, otherwise use identifier or first property
+        // Whole-entity targeting is explicit so existing catalogs retain their
+        // identifier/first-property fallback behavior.
         let targetHandle = '';
-        if (referenceProperty.referencesIdentifier) {
+        if (referenceProperty.referenceTarget === 'entity') {
+          targetHandle = ENTITY_TARGET_HANDLE_ID;
+        } else if (referenceProperty.referencesIdentifier) {
           targetHandle = `${referenceProperty.referencesIdentifier}-target`;
         } else if (referencedEntity.data.identifier) {
           targetHandle = `${referencedEntity.data.identifier}-target`;
@@ -211,8 +230,8 @@ export const getNodesAndEdges = async ({ id, version, entities, type = 'domains'
   // Prepare ELK graph structure
   const elkNodes = nodes.map((node: any) => ({
     id: node.id,
-    width: 280,
-    height: 200,
+    width: 220,
+    height: Math.max(120, 72 + (node.data.entity.data.properties?.length ?? 0) * 40),
   }));
 
   const elkEdges = edges.map((edge: any) => ({
@@ -225,12 +244,10 @@ export const getNodesAndEdges = async ({ id, version, entities, type = 'domains'
     id: 'root',
     layoutOptions: {
       'elk.algorithm': 'force',
-      'elk.force.repulsivePower': '2.0',
-      'elk.force.iterations': '500',
-      'elk.spacing.nodeNode': '150',
-      'elk.spacing.edgeNode': '75',
-      'elk.spacing.edgeEdge': '30',
-      'elk.padding': '[top=50,left=50,bottom=50,right=50]',
+      'elk.force.iterations': '300',
+      'elk.spacing.nodeNode': '45',
+      'elk.spacing.componentComponent': '50',
+      'elk.padding': '[top=30,left=30,bottom=30,right=30]',
       'elk.separateConnectedComponents': 'true',
     },
     children: elkNodes,

package/package.json

@@ -7,7 +7,7 @@
   },
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
-  "version": "4.3.1",
+  "version": "4.3.2",
   "publishConfig": {
     "access": "public"
   },
@@ -116,9 +116,9 @@
     "update-notifier": "^7.3.1",
     "uuid": "^10.0.0",
     "zod": "^4.3.6",
-    "@eventcatalog/sdk": "2.26.2",
-    "@eventcatalog/visualiser": "^4.1.0",
-    "@eventcatalog/linter": "1.1.7"
+    "@eventcatalog/linter": "1.1.8",
+    "@eventcatalog/visualiser": "^4.1.1",
+    "@eventcatalog/sdk": "2.26.3"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.9",