@api-client/core 0.18.48 → 0.18.50

package/data/models/example-generator-api.json

@@ -42062,9 +42062,6 @@
 "@id": "#209"
 },
 {
-"@id": "#206"
-},
-{
 "@id": "#191"
 },
 {
@@ -42080,6 +42077,9 @@
 "@id": "#203"
 },
 {
+"@id": "#206"
+},
+{
 "@id": "#209"
 }
 ],
@@ -42813,13 +42813,13 @@
 "@id": "#210"
 },
 {
-"@id": "#213"
+"@id": "#219"
 },
 {
-"@id": "#216"
+"@id": "#213"
 },
 {
-"@id": "#219"
+"@id": "#216"
 }
 ],
 "doc:root": false,
@@ -43436,7 +43436,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "addressType: 'REGISTERED-OFFICE-ADDRESS'\nstreetName: 'UITBREIDINGSTRAAT'\nhouseNumber: '84'\nhouseNumberAddition: '/1'\npostalCode: '2600'\ncity: 'BERCHEM (ANTWERPEN)'\ncountry: 'Belgium'\ncountryCode: 'BE'\nfullFormatedAddress: \"UITBREIDINGSTRAAT 84 /1, 2600 BERCHEM (ANTWERPEN), BELIUM\"\n",
+"doc:raw": "countryCode: \"BE\"\ngraydonEnterpriseId: 1057155523\nregistrationId: \"0422319093\"\nvatNumber: \"BE0422319093\"\ngraydonCompanyId: \"0422319093\"\nisBranchOffice: false\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -43457,7 +43457,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "code: '5'\ndescription: 'Limited company'\n",
+"doc:raw": "addressType: 'REGISTERED-OFFICE-ADDRESS'\nstreetName: 'UITBREIDINGSTRAAT'\nhouseNumber: '84'\nhouseNumberAddition: '/1'\npostalCode: '2600'\ncity: 'BERCHEM (ANTWERPEN)'\ncountry: 'Belgium'\ncountryCode: 'BE'\nfullFormatedAddress: \"UITBREIDINGSTRAAT 84 /1, 2600 BERCHEM (ANTWERPEN), BELIUM\"\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -43478,7 +43478,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "class: '3'\ndescription: '150 - 300'\nnumberOfFte: 5500\nnumberOfEmployees: 5232\n",
+"doc:raw": "code: '5'\ndescription: 'Limited company'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -43499,7 +43499,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "code: 'J'\ndescription: 'Information and communication'\n",
+"doc:raw": "class: '3'\ndescription: '150 - 300'\nnumberOfFte: 5500\nnumberOfEmployees: 5232\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -43520,7 +43520,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "code: '7487'\ndescription: 'Financial and insurance activities'\ntype: \"PRIMARY\"\nclassificationCode: 'BE_NACEBEL2008'\nactivityGroupCode: 'ABCDE'\n",
+"doc:raw": "code: 'J'\ndescription: 'Information and communication'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -43541,7 +43541,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "countryCode: \"BE\"\ngraydonEnterpriseId: 1057155523\nregistrationId: \"0422319093\"\nvatNumber: \"BE0422319093\"\ngraydonCompanyId: \"0422319093\"\nisBranchOffice: false\n",
+"doc:raw": "code: '7487'\ndescription: 'Financial and insurance activities'\ntype: \"PRIMARY\"\nclassificationCode: 'BE_NACEBEL2008'\nactivityGroupCode: 'ABCDE'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -44253,7 +44253,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "type: 'GENERAL'\ncountryDialCode : '+32'\nareaCode : '21'\nsubscriberNumber: '12.87.00'\nformatted: '+32-(0)21 302099'\n",
+"doc:raw": "-\n  type: 'GENERAL'\n  value: 'info@company.be'\n-\n  type: 'IT_DEPT'\n  value: 'it-service@company.be'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -44274,7 +44274,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "-\n  type: 'GENERAL'\n  value: 'info@company.be'\n-\n  type: 'IT_DEPT'\n  value: 'it-service@company.be'\n",
+"doc:raw": "type: \"GENERAL\"\nvalue: \"www.company.be\"\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -44295,7 +44295,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "type: \"GENERAL\"\nvalue: \"www.company.be\"\n",
+"doc:raw": "type: 'GENERAL'\ncountryDialCode : '+32'\nareaCode : '21'\nsubscriberNumber: '12.87.00'\nformatted: '+32-(0)21 302099'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -44756,32 +44756,32 @@
 {
 "@id": "#193/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#193",
-"sourcemaps:value": "[(1,0)-(10,0)]"
+"sourcemaps:value": "[(1,0)-(7,0)]"
 },
 {
 "@id": "#196/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#196",
-"sourcemaps:value": "[(1,0)-(3,0)]"
+"sourcemaps:value": "[(1,0)-(10,0)]"
 },
 {
 "@id": "#199/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#199",
-"sourcemaps:value": "[(1,0)-(5,0)]"
+"sourcemaps:value": "[(1,0)-(3,0)]"
 },
 {
 "@id": "#202/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#202",
-"sourcemaps:value": "[(1,0)-(3,0)]"
+"sourcemaps:value": "[(1,0)-(5,0)]"
 },
 {
 "@id": "#205/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#205",
-"sourcemaps:value": "[(1,0)-(6,0)]"
+"sourcemaps:value": "[(1,0)-(3,0)]"
 },
 {
 "@id": "#208/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#208",
-"sourcemaps:value": "[(1,0)-(7,0)]"
+"sourcemaps:value": "[(1,0)-(6,0)]"
 },
 {
 "@id": "#223/source-map/lexical/element_0",
@@ -45121,17 +45121,17 @@
 {
 "@id": "#215/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#215",
-"sourcemaps:value": "[(1,0)-(6,0)]"
+"sourcemaps:value": "[(1,0)-(7,0)]"
 },
 {
 "@id": "#218/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#218",
-"sourcemaps:value": "[(1,0)-(7,0)]"
+"sourcemaps:value": "[(1,0)-(3,0)]"
 },
 {
 "@id": "#221/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#221",
-"sourcemaps:value": "[(1,0)-(3,0)]"
+"sourcemaps:value": "[(1,0)-(6,0)]"
 },
 {
 "@id": "#338/source-map/synthesized-field/element_1",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@api-client/core",
   "description": "The API Client's core client library. Works in NodeJS and in a ES enabled browser.",
-  "version": "0.18.48",
+  "version": "0.18.50",
   "license": "Apache-2.0",
   "exports": {
     "./browser.js": {
@@ -99,7 +99,7 @@
     "chalk": "^5.4.1",
     "console-table-printer": "^2.11.2",
     "dompurify": "^3.2.6",
-    "jsdom": "^27.0.0",
+    "jsdom": "^28.0.0",
     "nanoid": "^5.1.5",
     "tslog": "^4.9.3",
     "ws": "^8.12.0",

package/src/mocking/README.md

@@ -0,0 +1,40 @@
+# Mocking Library (`src/mocking`)
+
+This directory contains the mocking infrastructure for the API Cloud Core. It provides realistic data generation for testing and demo purposes without requiring a real backend.
+
+## Key Components
+
+### `ProjectMock`
+The main entry point for mocking a project environment. It aggregates various sub-mocks to simulate a complete project context.
+
+**Usage:**
+```typescript
+import { ProjectMock } from './ProjectMock';
+
+const mock = new ProjectMock();
+// Access sub-mocks
+console.log(mock.user);
+console.log(mock.projectRequest);
+```
+
+### `ModelingMock` & `LegacyMock`
+Specialized mocks for specific domains:
+- `ModelingMock`: Logic for API domain modeling.
+- `LegacyMock`: Support for older systems or deprecated interfaces.
+
+## Directory Structure
+
+- **`lib/`**: Contains the individual mock implementations.
+    - `DataCatalog.ts`: Generates `DataCatalogSchema` objects using `faker`.
+    - `File.ts`, `User.ts`, `Request.ts`: Other domain-specific entities.
+    - **Pattern**: Classes in `lib/` usually provide methods like `entityName(init)` and `entityNames(size, init)` to generate single or multiple mock objects.
+- **`legacy/`**: Old mock implementations kept for backward compatibility. Use with caution.
+
+## Developing Mocks
+
+When adding a new mock:
+1. Create a class in `lib/` (e.g., `NewEntity.ts`).
+2. Use `@faker-js/faker` for realistic random data.
+3. Allow overrides via a partial `init` parameter.
+4. Export single and list generation methods.
+5. Register it in `ProjectMock.ts` if it belongs to the global project context.

package/src/mocking/lib/DataCatalog.ts

@@ -53,10 +53,10 @@ export class DataCatalog {
    * @param size Number of data catalogs to generate. Default is 25.
    * @returns List of random data catalogs
    */
-  dataCatalogs(size = 25): DataCatalogSchema[] {
+  dataCatalogs(size = 25, init?: Partial<DataCatalogSchema>): DataCatalogSchema[] {
     const result = []
     for (let i = 0; i < size; i++) {
-      result.push(this.dataCatalog())
+      result.push(this.dataCatalog(init))
     }
     return result
   }
@@ -97,10 +97,10 @@ export class DataCatalog {
    * @param size Number of data catalog versions to generate. Default is 25.
    * @returns List of random data catalog versions.
    */
-  dataCatalogVersions(size = 25): DataCatalogVersionSchema[] {
+  dataCatalogVersions(size = 25, init?: Partial<DataCatalogVersionSchema>): DataCatalogVersionSchema[] {
     const result = []
     for (let i = 0; i < size; i++) {
-      result.push(this.dataCatalogVersion())
+      result.push(this.dataCatalogVersion(init))
     }
     return result
   }
@@ -129,10 +129,10 @@ export class DataCatalog {
    * @param size Number of data catalogs to generate. Default is 3.
    * @returns List of random data catalogs with versions.
    */
-  dataCatalogsWithVersion(size = 3): DataCatalogSchemaWithVersion[] {
+  dataCatalogsWithVersion(size = 3, init?: Partial<DataCatalogSchemaWithVersion>): DataCatalogSchemaWithVersion[] {
     const result = []
     for (let i = 0; i < size; i++) {
-      result.push(this.dataCatalogWithVersion())
+      result.push(this.dataCatalogWithVersion(init))
     }
     return result
   }
@@ -156,10 +156,10 @@ export class DataCatalog {
    * @param size Number of data catalog version info objects to generate. Default is 5.
    * @returns List of random data catalog version info objects.
    */
-  versionInfos(size = 5): DataCatalogVersionInfo[] {
+  versionInfos(size = 5, init?: Partial<DataCatalogVersionInfo>): DataCatalogVersionInfo[] {
     const result = []
     for (let i = 0; i < size; i++) {
-      result.push(this.versionInfo())
+      result.push(this.versionInfo(init))
     }
     return result
   }

package/src/mocking/lib/File.ts

@@ -15,7 +15,7 @@ export class File {
       kind = faker.helpers.arrayElement([ProjectKind, DomainFileKind, CertificateFileKind, ApiFileKind] as const),
       info = { name: faker.system.fileName() },
     } = init
-    return CoreFile.createSchema({ kind, info })
+    return CoreFile.createSchema({ ...init, kind, info })
   }
 
   /**
@@ -23,10 +23,10 @@ export class File {
    * @param size Number of files to generate. Default is 25.
    * @returns List of random files
    */
-  files(size = 25): IFile[] {
+  files(size = 25, init?: Partial<IFile>): IFile[] {
     const result = []
     for (let i = 0; i < size; i++) {
-      result.push(this.file())
+      result.push(this.file(init))
     }
     return result
   }
@@ -45,10 +45,10 @@ export class File {
    * @param size Number of folders to generate. Default is 25.
    * @returns List of random folders
    */
-  folders(size = 25): IFile[] {
+  folders(size = 25, init?: Partial<IFile>): IFile[] {
     const result = []
     for (let i = 0; i < size; i++) {
-      result.push(this.folder())
+      result.push(this.folder(init))
     }
     return result
   }

package/src/mocking/lib/Group.ts

@@ -42,10 +42,10 @@ export class Group {
    * @param size Number of organizations to generate. Default is 25.
    * @returns List of random organizations
    */
-  groups(size = 25): GroupSchema[] {
+  groups(size = 25, init?: Partial<GroupSchema>): GroupSchema[] {
     const result = []
     for (let i = 0; i < size; i++) {
-      result.push(this.group())
+      result.push(this.group(init))
     }
     return result
   }

package/src/mocking/lib/Invitation.ts

@@ -48,10 +48,10 @@ export class Invitation {
    * @param size Number of invitations to generate. Default is 25.
    * @returns List of random invitations
    */
-  invitations(size = 25): InvitationSchema[] {
+  invitations(size = 25, init?: Partial<InvitationSchema>): InvitationSchema[] {
     const result = []
     for (let i = 0; i < size; i++) {
-      result.push(this.invitation())
+      result.push(this.invitation(init))
     }
     return result
   }

package/src/mocking/lib/Organization.ts

@@ -32,10 +32,10 @@ export class Organization {
    * @param size Number of organizations to generate. Default is 25.
    * @returns List of random organizations
    */
-  organizations(size = 25): IOrganization[] {
+  organizations(size = 25, init?: Partial<IOrganization>): IOrganization[] {
     const result = []
     for (let i = 0; i < size; i++) {
-      result.push(this.organization())
+      result.push(this.organization(init))
     }
     return result
   }

package/src/mocking/lib/Patch.ts

@@ -41,10 +41,10 @@ export class Patch {
    * @param size Number of invitations to generate. Default is 25.
    * @returns List of random invitations
    */
-  mediaPatchRevisions(size = 25): MediaPatchRevision[] {
+  mediaPatchRevisions(size = 25, init?: Partial<MediaPatchRevision>): MediaPatchRevision[] {
     const result = []
     for (let i = 0; i < size; i++) {
-      result.push(this.mediaPatchRevision())
+      result.push(this.mediaPatchRevision(init))
     }
     return result
   }

package/src/mocking/lib/Trash.ts

@@ -37,10 +37,10 @@ export class Trash {
    * @param size Number of invitations to generate. Default is 25.
    * @returns List of random invitations
    */
-  trashEntries(size = 25): CoreTrashEntry[] {
+  trashEntries(size = 25, init?: Partial<CoreTrashEntry>): CoreTrashEntry[] {
     const result = []
     for (let i = 0; i < size; i++) {
-      result.push(this.trashEntry())
+      result.push(this.trashEntry(init))
     }
     return result
   }

package/src/modeling/ApiModel.ts

@@ -280,6 +280,16 @@ export class ApiModel extends DependentModel {
     } else if (domain) {
       throw new Error(`Invalid domain provided. Expected a DataDomain instance or schema.`)
     }
+    // Note that since we're using the `DependentModel` class, but the API Model can have only one dependency,
+    // we keep the reference to the data domain under the `dependencyList` property.
+    // It is all handled by the parent class `DependentModel`. This way we simplify the dependency management (loading)
+    // process when the API model is loaded from the API.
+    if (domain) {
+      if (!domain.info.version) {
+        throw new Error(`Domain ${domain.key} must have a version.`)
+      }
+      init.dependencyList = [{ key: domain.key, version: domain.info.version }]
+    }
     super(init.dependencyList, instances)
     this.kind = init.kind
     this.key = init.key
@@ -380,6 +390,12 @@ export class ApiModel extends DependentModel {
   /**
    * Exposes a new entity in the API model.
    * If the entity already exists, it returns the existing one.
+   *
+   * The logic regarding exposing an entity:
+   * - If the entity is already exposed as a root entity, it returns the existing one.
+   * - If the entity has an association, we expose that entity as a nested entity (by setting the parent property).
+   * - If the associated entity is already exposed as a root entity, we do not follow the association.
+   *
    * @param entity The entity key and domain to expose.
    * @returns The exposed entity.
    */
@@ -403,8 +419,18 @@ export class ApiModel extends DependentModel {
     }
     const name = domainEntity.info.name || ''
     const segment = pluralize(name.toLocaleLowerCase())
-    const relativeCollectionPath = `/${segment}`
-    const relativeResourcePath = `/${segment}/{id}`
+    let relativeCollectionPath = `/${segment}`
+    let relativeResourcePath = `/${segment}/{id}`
+
+    // Check for root path collision and resolve by appending a number
+    let counter = 1
+    const originalCollectionPath = relativeCollectionPath
+    while (this.exposes.some((e) => e.isRoot && e.collectionPath === relativeCollectionPath)) {
+      relativeCollectionPath = `${originalCollectionPath}-${counter}`
+      relativeResourcePath = `${relativeCollectionPath}/{id}`
+      counter++
+    }
+
     const newEntity: ExposedEntitySchema = {
       kind: ExposedEntityKind,
       key: nanoid(),
@@ -444,12 +470,7 @@ export class ApiModel extends DependentModel {
       return
     }
     const maxDepth = options.maxDepth ?? 6
-    const visited = new Set<string>()
-    // Add parent entity's key to the visited set so we won't skip it when traversing
-    // associations.
-    visited.add(createDomainKey(parentExposure.entity))
-
-    const follow = (currentEntity: AssociationTarget, parentKey: string, depth: number) => {
+    const follow = (currentEntity: AssociationTarget, parentKey: string, depth: number, currentPath: string[]) => {
       // Find the domain entity
       const domainEntity = domain.findEntity(currentEntity.key, currentEntity.domain)
       if (!domainEntity) return
@@ -462,24 +483,45 @@ export class ApiModel extends DependentModel {
             continue
           }
 
-          // Create unique identifier for circular detection
-          const visitKey = createDomainKey(target)
-          if (visited.has(visitKey)) {
-            continue // Skip circular references
+          const targetKeys = createDomainKey(target)
+          // Circular dependency check: if this entity is already in our *current* traversal path
+          if (currentPath.includes(targetKeys)) {
+            continue
           }
-          visited.add(visitKey)
-
-          // Check if this nested exposure already exists
-          const existingNested = this.exposes.find(
-            (e) =>
-              !e.isRoot &&
-              e.entity.key === target.key &&
-              e.entity.domain === target.domain &&
-              e.parent?.key === parentKey
-          )
-
-          if (existingNested) {
-            continue // Already exposed under this parent
+
+          // Check if this entity is ALREADY exposed anywhere in the model
+          const existingExposure = this.getExposedEntity(target)
+
+          if (existingExposure) {
+            // If it's already exposed and NOT root (i.e., it's currently a nested child of someone else),
+            // promote it to ROOT to avoid duplicating it or deeply nesting it in multiple places.
+            if (!existingExposure.isRoot) {
+              // 1. Calculate new root paths (handling collisions)
+              const targetDomEntity = domain.findEntity(target.key, target.domain)
+              if (targetDomEntity) {
+                const name = targetDomEntity.info.name || ''
+                const segment = pluralize(name.toLocaleLowerCase())
+                let relativeCollectionPath = `/${segment}`
+                let relativeResourcePath = `/${segment}/{id}`
+
+                let counter = 1
+                const originalCollectionPath = relativeCollectionPath
+                while (this.exposes.some((e) => e.isRoot && e.collectionPath === relativeCollectionPath)) {
+                  relativeCollectionPath = `${originalCollectionPath}-${counter}`
+                  relativeResourcePath = `${relativeCollectionPath}/{id}`
+                  counter++
+                }
+
+                // 2. Update properties to make it root
+                existingExposure.isRoot = true
+                existingExposure.parent = undefined
+                existingExposure.collectionPath = relativeCollectionPath
+                existingExposure.resourcePath = relativeResourcePath
+                existingExposure.hasCollection = true
+              }
+            }
+            // Whether it was already root or we just promoted it, we stop following here.
+            continue
           }
 
           // Find the target domain entity for path generation
@@ -516,27 +558,30 @@ export class ApiModel extends DependentModel {
             nestedExposure.truncated = true
           } else {
             // Recursively follow associations
-            follow(target, nestedExposure.key, depth + 1)
+            follow(target, nestedExposure.key, depth + 1, [...currentPath, targetKeys])
           }
         }
       }
     }
 
     // Start following from the root exposure
-    follow(parentExposure.entity, parentExposure.key, 0)
+    // Initial path contains the root entity itself
+    const rootKey = createDomainKey(parentExposure.entity)
+    follow(parentExposure.entity, parentExposure.key, 0, [rootKey])
   }
 
   /**
    * Removes an exposed entity from the API model.
-   * @param entity The entity to remove.
+   * This also removes any nested exposed entities that are children of the removed entity.
+   *
+   * @param key The key of the exposed entity to remove.
    */
-  removeEntity(entity: AssociationTarget): void {
-    const current = this.exposes.find((e) => e.entity.key === entity.key && e.entity.domain === entity.domain)
-    if (!current) {
-      return
+  removeExposedEntity(key: string): void {
+    const index = this.exposes.findIndex((e) => e.key === key)
+    if (index < 0) {
+      throw new Error(`Exposed entity with key "${key}" not found.`)
     }
-    this.removeWithChildren(current.key)
-    this.notifyChange()
+    this.removeWithChildren(key)
   }
 
   private removeWithChildren(key: string): void {
@@ -573,11 +618,11 @@ export class ApiModel extends DependentModel {
   }
 
   /**
-   * Clears the API model for a new entity change.
+   * Clears the API model for a new data domain change.
    * This method resets the dependencies, exposes, user,
    * authentication, authorization, and session properties.
    */
-  cleanForEntityChange(): void {
+  cleanForDomainChange(): void {
     this.dependencies.clear()
     this.dependencyList = []
     this.exposes = []
@@ -606,7 +651,7 @@ export class ApiModel extends DependentModel {
     if (!domain.info.version) {
       throw new Error(`Cannot attach DataDomain without a version. Please set the version in the domain info.`)
     }
-    this.cleanForEntityChange()
+    this.cleanForDomainChange()
     this.dependencies.set(domain.key, domain)
     this.dependencyList = [{ key: domain.key, version: domain.info.version }]
     this.notifyChange()

package/src/modeling/ExposedEntity.ts

@@ -16,6 +16,15 @@ import type {
 /**
  * A class that specializes in representing an exposed Data Entity within an API Model.
  *
+ * ## Design Note
+ * This class enforces strict path constraints (e.g., single-segment collection paths like `/users`,
+ * two-segment resource paths like `/users/{id}`).
+ * This is an intentional design choice to support a UI paradigm for non-technical users, ensuring that
+ * path segments are configured individually at each level of the exposure hierarchy.
+ *
+ * Flexibility is achieved by chaining exposed entities (parent/child relationships), where the final
+ * absolute path is composed of all ancestral paths. See `getAbsoluteResourcePath()` and `getAbsoluteCollectionPath()`.
+ *
  * @fires change - Emitted when the exposed entity has changed.
  */
 export class ExposedEntity extends EventTarget {
@@ -250,6 +259,17 @@ export class ExposedEntity extends EventTarget {
       throw new Error(`Collection path must contain exactly one segment. Received: "${path}"`)
     }
     const normalizedCollection = `/${segments[0]}`
+
+    // Check for collision if this is a root entity
+    if (this.isRoot) {
+      const collision = this.api.exposes.find(
+        (e) => e.isRoot && e.key !== this.key && e.collectionPath === normalizedCollection
+      )
+      if (collision) {
+        throw new Error(`Collection path "${normalizedCollection}" is already in use by another root entity.`)
+      }
+    }
+
     // Preserve current parameter name if present, otherwise default to {id}
     let param = '{id}'
     if (this.resourcePath) {
@@ -309,6 +329,14 @@ export class ExposedEntity extends EventTarget {
         `Resource path must contain exactly two segments when no collection is present. Received: "${cleaned}"`
       )
     }
+    // Check for collision if this is a root entity (singleton case)
+    if (this.isRoot) {
+      const collision = this.api.exposes.find((e) => e.isRoot && e.key !== this.key && e.resourcePath === cleaned)
+      if (collision) {
+        throw new Error(`Resource path "${cleaned}" is already in use by another root entity.`)
+      }
+    }
+
     if (this.resourcePath !== cleaned) {
       this.resourcePath = `/${segments[0]}/${segments[1]}`
     }

package/src/models/README.md

@@ -7,14 +7,15 @@
 Data models should only contain the data related to the functionality, and not view.
 Each application should keep separate metadata related to the view configuration.
 
-### Translatable from a YAML format
-
-We aim to be interoperable with AMF so when designing a data model first design a YAML example with the data and then create a type definition. Additionally, you need to design an AML dialect for the data.
-
 ### The "kind" as the object type identifier
 
 Each data object that can exist by itself or in multiple contexts' should contain the `kind` property that uniquely identifies the type. For example, the `HttpProject` class has the `Core#HttpProject`. These kinds are used by other libraries to identify which data types they are given as the input.
+Kinds are defined in the `src/models/kinds.ts` file.
 
 ### Validation
 
 THe data models should contain validators that produce the validation report. This ensures the support libraries can perform a validation of the data model they are receiving as an input to keep integrity of the data.
+
+## The "store" models
+
+All models under the `src/models/store` directory are considered "API" related models. For example, the `File` model is used to describe the file object in the API, but it is not used as any application's core data model.