@api-client/core 0.14.0 → 0.14.2

package/src/modeling/Semantics.ts

@@ -0,0 +1,195 @@
+/* eslint-disable max-len */
+import type { DomainPropertyType } from './DataFormat.js'
+
+/**
+ * Defines the names for all available data semantics.
+ * Using a string enum makes it easy to add or remove semantics in a single place.
+ */
+export enum SemanticType {
+  // Entity-Level Semantics
+  /**
+   * Designates a Data Entity that represents users of the system.
+   */
+  User = 'https://apinow.app/semantics/entities/#User',
+
+  // Property-Level Semantics
+  CreatedTimestamp = 'https://apinow.app/semantics/properties/#CreatedTimestamp',
+  UpdatedTimestamp = 'https://apinow.app/semantics/properties/#UpdatedTimestamp',
+  DeletedTimestamp = 'https://apinow.app/semantics/properties/#DeletedTimestamp',
+  DeletedFlag = 'https://apinow.app/semantics/properties/#DeletedFlag',
+  PublicUniqueName = 'https://apinow.app/semantics/properties/#PublicUniqueName',
+  /**
+   * Designates a Data Property as the `role` of a user within the system.
+   * This is used to define the user's permissions and access levels.
+   * For example, a user with the role of "admin" would have elevated permissions
+   * compared to a user with the role of "guest".
+   * Roles are defined on the entity as enums, or as a string property with a controlled vocabulary.
+   */
+  UserRole = 'https://apinow.app/semantics/entities/#UserRole',
+  // Association-Level Semantics
+  ResourceOwnerIdentifier = 'https://apinow.app/semantics/associations/#ResourceOwnerIdentifier',
+}
+
+/**
+ * Defines the scope at which a semantic can be applied.
+ */
+export enum SemanticScope {
+  Entity = 'Entity',
+  Property = 'Property',
+  Association = 'Association',
+}
+
+/**
+ * A base interface for all Data Semantics, containing common properties.
+ * A semantic is an annotation applied to a Data Entity, Property, or Association
+ * to provide additional context or constraints.
+ * This interface is extended by more specific semantic types.
+ */
+interface BaseDataSemantic {
+  /**
+   * A unique identifier for the semantic definition.
+   */
+  id: SemanticType
+  /**
+   * A human-readable name for the semantic.
+   */
+  displayName: string
+  /**
+   * A description of the semantic's purpose and impact.
+   */
+  description: string
+  /**
+   * Specifies whether the semantic applies to an Entity, Property, or Association.
+   */
+  scope: SemanticScope
+}
+
+/**
+ * Represents a semantic that can be applied to an entire Data Entity.
+ */
+export interface EntitySemantic extends BaseDataSemantic {
+  scope: SemanticScope.Entity
+}
+
+/**
+ * Represents a semantic that can be applied to a single property.
+ */
+export interface PropertySemantic extends BaseDataSemantic {
+  scope: SemanticScope.Property
+  /**
+   * Optional array of data types this semantic can be applied to.
+   * Enforces constraints, e.g., DeletedTimestamp on a DateTime property.
+   */
+  applicableDataTypes?: DomainPropertyType[]
+}
+
+/**
+ * Represents a semantic that can be applied to an association between entities.
+ */
+export interface AssociationSemantic extends BaseDataSemantic {
+  scope: SemanticScope.Association
+}
+
+/**
+ * A type guard to check if a semantic is an EntitySemantic.
+ */
+export const isEntitySemantic = (semantic: DataSemantic): semantic is EntitySemantic =>
+  semantic.scope === SemanticScope.Entity
+
+/**
+ * A type guard to check if a semantic is a PropertySemantic.
+ */
+export const isPropertySemantic = (semantic: DataSemantic): semantic is PropertySemantic =>
+  semantic.scope === SemanticScope.Property
+
+/**
+ * A type guard to check if a semantic is a AssociationSemantic.
+ */
+export const isAssociationSemantic = (semantic: DataSemantic): semantic is AssociationSemantic =>
+  semantic.scope === SemanticScope.Association
+
+/**
+ * Union type for any kind of data semantic
+ */
+export type DataSemantic = EntitySemantic | PropertySemantic | AssociationSemantic
+
+/**
+ * A map to store the definitions of all available data semantics.
+ * This acts as a central registry for the application.
+ */
+export const DataSemantics: Record<SemanticType, DataSemantic> = {
+  // Entity-Level Definitions
+  [SemanticType.User]: {
+    id: SemanticType.User,
+    displayName: 'User Entity',
+    scope: SemanticScope.Entity,
+    description: 'Designates an entity that represents system users, crucial for authentication and authorization.',
+  },
+
+  // Property-Level Definitions
+  [SemanticType.CreatedTimestamp]: {
+    id: SemanticType.CreatedTimestamp,
+    displayName: 'Creation Timestamp',
+    scope: SemanticScope.Property,
+    description: "Marks a field as the one that contains the object's creation timestamp.",
+    applicableDataTypes: ['datetime'],
+  },
+  [SemanticType.UpdatedTimestamp]: {
+    id: SemanticType.UpdatedTimestamp,
+    displayName: 'Update Timestamp',
+    scope: SemanticScope.Property,
+    description: "Marks a field as the field that contains object's last modification timestamp.",
+    applicableDataTypes: ['datetime'],
+  },
+  [SemanticType.DeletedTimestamp]: {
+    id: SemanticType.DeletedTimestamp,
+    displayName: 'Soft Delete Timestamp',
+    scope: SemanticScope.Property,
+    description: "Marks a field as the field that contains object's deletion timestamp.",
+    applicableDataTypes: ['datetime'],
+  },
+  [SemanticType.DeletedFlag]: {
+    id: SemanticType.DeletedFlag,
+    displayName: 'Soft Delete Flag',
+    scope: SemanticScope.Property,
+    description: 'A boolean property that marks the object as deleted without physically removing it.',
+    applicableDataTypes: ['boolean'],
+  },
+  [SemanticType.ResourceOwnerIdentifier]: {
+    id: SemanticType.ResourceOwnerIdentifier,
+    displayName: 'Resource Owner Identifier',
+    scope: SemanticScope.Association,
+    description: 'Links a resource to a "User" entity instance, indicating ownership for access control.',
+  },
+  [SemanticType.PublicUniqueName]: {
+    id: SemanticType.PublicUniqueName,
+    displayName: 'Public Unique Name (Slug)',
+    scope: SemanticScope.Property,
+    description: 'A user-friendly, unique public identifier for a resource, often used in URLs.',
+    applicableDataTypes: ['string'],
+  },
+  [SemanticType.UserRole]: {
+    id: SemanticType.UserRole,
+    displayName: 'User Role Field',
+    scope: SemanticScope.Property,
+    description:
+      'A text field that is recognized by the runtime as a role of a user in the API. Used with the role-based authorization strategy.',
+    applicableDataTypes: ['string'],
+  },
+}
+
+/**
+ * Represents the application of a data semantic to a specific
+ * entity or property within a user's data model.
+ */
+export interface AppliedDataSemantic {
+  /**
+   * The unique identifier of the semantic being applied.
+   */
+  id: SemanticType
+
+  /**
+   * Optional configuration or values specific to this application.
+   */
+  config?: Record<string, unknown>
+}

package/src/modeling/graph.md

@@ -4,20 +4,20 @@
 
 ```plain
 DataDomain (Root container)
-  ├── DataNamespace (logical grouping)
-  │   └── DataModel
-  │       └── DataEntity
+  ├── DomainNamespace (logical grouping)
+  │   └── DomainModel
+  │       └── DomainEntity
   │           ├── Property (name, type, ...)
   │           ├── Association (name, cardinality, target Entity)
-  │           └── ParentEntity (reference to another DataEntity)
-  ├── DataModel
-  │   └── DataEntity
+  │           └── ParentEntity (reference to another DomainEntity)
+  ├── DomainModel
+  │   └── DomainEntity
   │       ├── Property
   │       ├── Association
   │       └── ParentEntity
-  └── ForeignDataNamespace (immutable, imported from another DataDomain)
-      └── DataModel
-          └── DataEntity
+  └── ForeignDomainNamespace (immutable, imported from another DataDomain)
+      └── DomainModel
+          └── DomainEntity
               ├── Property
               ├── Association
               └── ParentEntity
@@ -31,11 +31,11 @@ Here's a breakdown of how each element is represented in the graph:
 
 **Nodes:**
 
-* **Namespace:** Represents a `DataNamespace`. It's a container for models and other namespaces.
-* **Model:** Represents a `DataModel`. It's a container for entities.
-* **Entity:** Represents a `DataEntity`. It's the fundamental building block, defining a specific type of data.
-* **Property:** Represents a `DataProperty`. It's an attribute of an entity.
-* **Association:** Represents a `DataAssociation`. It defines a relationship between entities.
+* **Namespace:** Represents a `DomainNamespace`. It's a container for models and other namespaces.
+* **Model:** Represents a `DomainModel`. It's a container for entities.
+* **Entity:** Represents a `DomainEntity`. It's the fundamental building block, defining a specific type of data.
+* **Property:** Represents a `DomainProperty`. It's an attribute of an entity.
+* **Association:** Represents a `DomainAssociation`. It defines a relationship between entities.
 
 **Edges:**
 

package/src/modeling/readme.md

@@ -4,53 +4,53 @@
 
 At the heart of this data modeling system are the following fundamental concepts.
 
-### DataNamespace
+### DomainNamespace
 
 This is the top-level container, representing a logical grouping of data. Think of it as a "domain" or a "schema" in a database. It can contain:
 
-- `DataModels`: Logical groupings of entities.
+- `DomainModels`: Logical groupings of entities.
 - `DataEntities`: The basic building blocks, representing individual data structures.
 - `DataProperties`: Attributes of entities (e.g., name, age, address).
-- `DataAssociations`: Relationships between entities (e.g., a user has an address).
+- `DomainAssociations`: Relationships between entities (e.g., a user has an address).
 - `Sub-namespaces`: Namespaces can be nested within each other, creating a hierarchical structure.
 - `Foreign Namespaces`: References to external namespaces, enabling the use of entities defined elsewhere.
 - `Tags`: Common tags for the entire namespace.
 
-### DataModel
+### DomainModel
 
-A logical grouping of `DataEntity` instances. It represents a specific data structure, like a "Product" or "User" model. A `DataModel` can contain multiple `DataEntity` instances.
+A logical grouping of `DomainEntity` instances. It represents a specific data structure, like a "Product" or "User" model. A `DomainModel` can contain multiple `DomainEntity` instances.
 
-### DataEntity
+### DomainEntity
 
 The fundamental building block of the data model. It represents a specific type of data, like a "User," "Product," or "Address."
 
-- `Properties`: DataProperty instances that describe the attributes of the entity.
-- `Associations`: DataAssociation instances that define relationships to other entities.
+- `Properties`: DomainProperty instances that describe the attributes of the entity.
+- `Associations`: DomainAssociation instances that define relationships to other entities.
 - `Parents`: An entity can inherit from other entities, creating a hierarchy.
 - `Fields`: Ordered list of properties and associations.
 - `Tags`: Optional tags for the UI.
-- `Taxonomy`: Reserved for future use.
+- `Semantics`: A system of predefined, meaningful labels or classifications that can be applied to Data Entities or their individual properties.
 - `Deprecated`: Whether the entity is deprecated.
 - `Schema`: The schema allowing to translate the model into a specific format (like JSON, RAML, XML, etc.)
 
-### DataProperty
+### DomainProperty
 
-Represents an attribute of a `DataEntity`. It has a name, a data type (e.g., string, number, boolean), and optional constraints (e.g., required, multiple, min/max values).
+Represents an attribute of a `DomainEntity`. It has a name, a data type (e.g., string, number, boolean), and optional constraints (e.g., required, multiple, min/max values).
 
 - `Type`: The data type of the property.
 - `Schema`: The general schema definition of this property.
 - `Bindings`: The list of bindings for this property.
 - `Tags`: Optional tags for the UI.
-- `Taxonomy`: Reserved for future use.
+- `Semantics`: A system of predefined, meaningful labels or classifications that can be applied to Data Entities or their individual properties.
 - `Deprecated`: Whether the property is deprecated.
 - `Primary`: Whether this property describes a primary key of the entity.
 - `Index`: Whether this property describes an indexed property of the entity.
 - `ReadOnly`: Whether the property is read only in the schema.
 - `WriteOnly`: Whether the property is write only in the schema.
 
-### DataAssociation
+### DomainAssociation
 
-Defines a relationship between `DataEntity` instances. It specifies the target entities and the nature of the relationship (e.g., one-to-one, one-to-many).
+Defines a relationship between `DomainEntity` instances. It specifies the target entities and the nature of the relationship (e.g., one-to-one, one-to-many).
 
 - `Targets`: The list of target entities.
 - `Multiple`: Whether the association allows multiple target entities.
@@ -67,24 +67,24 @@ Defines a translation from a data model to a specific format (like JSON, RAML, X
 
 Here's how these components work together to structure a data domain:
 
-1. **Root Namespace**: You start with a `DataNamespace`, which acts as the root of your data domain. This namespace is the top-level container for all other elements.
+1. **Root Namespace**: You start with a `DomainNamespace`, which acts as the root of your data domain. This namespace is the top-level container for all other elements.
 
 1. **Sub-namespaces (Optional)**: You can create sub-namespaces within the root namespace to further organize your data. This is useful for large domains with many entities and relationships.
 
-1. **Data Models**: Within a namespace (or sub-namespace), you define `DataModel` instances. Each `DataModel` represents a specific area of your domain. For example, you might have a "User Management" `DataModel`, a "Product Catalog" `DataModel`, and an "Order Processing" `DataModel`.
+1. **Data Models**: Within a namespace (or sub-namespace), you define `DomainModel` instances. Each `DomainModel` represents a specific area of your domain. For example, you might have a "User Management" `DomainModel`, a "Product Catalog" `DomainModel`, and an "Order Processing" `DomainModel`.
 
-1. **Data Entities**: Inside each `DataModel`, you define `DataEntity` instances. These are the core data structures. For example, in the "User Management" `DataModel`, you might have `DataEntity` instances for "User," "Role," and "Permission."
+1. **Data Entities**: Inside each `DomainModel`, you define `DomainEntity` instances. These are the core data structures. For example, in the "User Management" `DomainModel`, you might have `DomainEntity` instances for "User," "Role," and "Permission."
 
-1. **Data Properties**: Each `DataEntity` has `DataProperty` instances that describe its attributes. For example, the "User" `DataEntity` might have `DataProperty` instances for "firstName" (string), "lastName" (string), "email" (string), "age" (number), etc.
+1. **Data Properties**: Each `DomainEntity` has `DomainProperty` instances that describe its attributes. For example, the "User" `DomainEntity` might have `DomainProperty` instances for "firstName" (string), "lastName" (string), "email" (string), "age" (number), etc.
 
-1. **Data Associations**: You use `DataAssociation` instances to define relationships between `DataEntity` instances. For example:
+1. **Data Associations**: You use `DomainAssociation` instances to define relationships between `DomainEntity` instances. For example:
 
    - A "User" has an "Address" (one-to-one).
    - A "User" has multiple "Roles" (one-to-many).
    - A "Product" belongs to a "Category" (many-to-one).
    - An "Order" contains multiple "Order Items" (one-to-many).
 
-1. **Inheritance**: `DataEntity` instances can inherit from other `DataEntity` instances using the parents property. This allows you to create a hierarchy of entities and reuse common properties and associations.
+1. **Inheritance**: `DomainEntity` instances can inherit from other `DomainEntity` instances using the parents property. This allows you to create a hierarchy of entities and reuse common properties and associations.
 
 1. **Foreign Namespaces**: You can reference entities from other namespaces using the foreign property of the root namespace. This allows you to reuse data structures defined elsewhere.
 
@@ -109,18 +109,18 @@ Let's imagine a simple e-commerce domain:
         - **Data Association**: `address` (references `Address` entity)
       - **Data Entity**: `Address`
         - **Data Properties**: `street` (string), `city` (string), `zipCode` (string), `country` (string)
-  - **Foreign Namespace**: `Taxonomy` (defined elsewhere)
-    - **Data Model**: `Taxonomy`
-      - **Data Entity**: `TaxonomyItem`
+  - **Foreign Namespace**: `Semantics` (defined elsewhere)
+    - **Data Model**: `Semantics`
+      - **Data Entity**: `SemanticsItem`
 
 ### Key Relationships
 
-- **Namespace-Model**: A `DataNamespace` contains `DataModel` instances.
-- **Model-Entity**: A `DataModel` contains `DataEntity` instances.
-- **Entity-Property**: A `DataEntity` has `DataProperty` instances.
-- **Entity-Association**: A `DataEntity` has `DataAssociation` instances.
-- **Entity-Parent**: A `DataEntity` can have `DataEntity` instances as parents.
-- **Namespace-Foreign**: A `DataNamespace` can have references to `DataNamespace` instances.
+- **Namespace-Model**: A `DomainNamespace` contains `DomainModel` instances.
+- **Model-Entity**: A `DomainModel` contains `DomainEntity` instances.
+- **Entity-Property**: A `DomainEntity` has `DomainProperty` instances.
+- **Entity-Association**: A `DomainEntity` has `DomainAssociation` instances.
+- **Entity-Parent**: A `DomainEntity` can have `DomainEntity` instances as parents.
+- **Namespace-Foreign**: A `DomainNamespace` can have references to `DomainNamespace` instances.
 
 ## Summary
 

package/src/models/kinds.ts

@@ -20,28 +20,3 @@ export const DataCatalogKind = 'Core#DataCatalog'
 export const DataCatalogVersionKind = 'Core#DataCatalogVersion'
 export const OrganizationKind = 'Core#Organization'
 export const InvitationKind = 'Core#Invitation'
-
-/**
- * @deprecated Not used anymore.
- */
-export const DataFileKind = 'Core#DataFile'
-/**
- * @deprecated Not used anymore.
- */
-export const DataNamespaceKind = 'Data#DataNamespace'
-/**
- * @deprecated Not used anymore.
- */
-export const DataModelKind = 'Data#DataModel'
-/**
- * @deprecated Not used anymore.
- */
-export const DataEntityKind = 'Data#DataEntity'
-/**
- * @deprecated Not used anymore.
- */
-export const DataAssociationKind = 'Data#DataAssociation'
-/**
- * @deprecated Not used anymore.
- */
-export const DataPropertyKind = 'Data#DataProperty'

package/src/models/store/data_catalog.ts

@@ -23,7 +23,7 @@ export interface PublishedDataDomain {
    */
   version: string
   /**
-   * Key of the referenced `DataNamespace` document.
+   * Key of the referenced `DomainNamespace` document.
    * Essentially this is a document id.
    */
   fid: string

package/tests/unit/modeling/data_domain_change_observers.spec.ts

@@ -1,5 +1,6 @@
 import { test } from '@japa/runner'
 import { DataDomain, DataFormat } from '../../../src/index.js'
+import { SemanticType } from '../../../src/modeling/Semantics.js'
 
 test.group('DataDomain change observers', () => {
   test('does not notifies a change when initializing a domain', async ({ assert }) => {
@@ -276,24 +277,24 @@ test.group('DomainEntity change observers', () => {
     await assert.dispatchCount(domain, 'change', 1, { timeout: 1 })
   })
 
-  test('notifies a change when adding a taxonomy', async ({ assert, sleep }) => {
+  test('notifies a change when adding a semantics', async ({ assert, sleep }) => {
     const domain = new DataDomain()
     const n1 = domain.addNamespace()
     const m1 = n1.addModel()
     const e1 = m1.addEntity()
     await sleep(1)
-    e1.taxonomy.push('test')
+    e1.semantics.push({ id: SemanticType.User })
     await assert.dispatchCount(domain, 'change', 1, { timeout: 1 })
   })
 
-  test('notifies a change when removing a taxonomy', async ({ assert, sleep }) => {
+  test('notifies a change when removing a semantics', async ({ assert, sleep }) => {
     const domain = new DataDomain()
     const n1 = domain.addNamespace()
     const m1 = n1.addModel()
     const e1 = m1.addEntity()
-    e1.taxonomy.push('test')
+    e1.semantics.push({ id: SemanticType.User })
     await sleep(1)
-    e1.taxonomy.pop()
+    e1.semantics.pop()
     await assert.dispatchCount(domain, 'change', 1, { timeout: 1 })
   })
 
@@ -508,26 +509,26 @@ test.group('DomainProperty change observers', () => {
     await assert.dispatchCount(domain, 'change', 1, { timeout: 1 })
   })
 
-  test('notifies a change when adding a taxonomy', async ({ assert, sleep }) => {
+  test('notifies a change when adding a semantics', async ({ assert, sleep }) => {
     const domain = new DataDomain()
     const n1 = domain.addNamespace()
     const m1 = n1.addModel()
     const e1 = m1.addEntity()
     const p1 = e1.addProperty()
     await sleep(1)
-    p1.taxonomy.push('test')
+    p1.semantics.push({ id: SemanticType.CreatedTimestamp })
     await assert.dispatchCount(domain, 'change', 1, { timeout: 1 })
   })
 
-  test('notifies a change when removing a taxonomy', async ({ assert, sleep }) => {
+  test('notifies a change when removing a semantics', async ({ assert, sleep }) => {
     const domain = new DataDomain()
     const n1 = domain.addNamespace()
     const m1 = n1.addModel()
     const e1 = m1.addEntity()
     const p1 = e1.addProperty()
-    p1.taxonomy.push('test')
+    p1.semantics.push({ id: SemanticType.CreatedTimestamp })
     await sleep(1)
-    p1.taxonomy.pop()
+    p1.semantics.pop()
     await assert.dispatchCount(domain, 'change', 1, { timeout: 1 })
   })
 

package/tests/unit/modeling/data_domain_entities.spec.ts

@@ -1,6 +1,7 @@
 import { test } from '@japa/runner'
 import { DataDomain } from '../../../src/modeling/DataDomain.js'
 import { DomainEntity } from '../../../src/modeling/DomainEntity.js'
+import { SemanticType } from '../../../src/modeling/Semantics.js'
 
 test.group('DataDomain.addEntity()', () => {
   test('addEntity adds an entity to the graph', ({ assert }) => {
@@ -70,7 +71,7 @@ test.group('DataDomain.addEntity()', () => {
     assert.throws(() => {
       // @ts-expect-error For testing purposes, we are passing undefined
       dataDomain.addEntity(undefined, { key: 'test-entity' })
-    }, `An entity expects a DataModel parent`)
+    }, `An entity expects a DomainModel parent`)
   })
 
   test('addEntity throws when adding the same entity twice', ({ assert }) => {
@@ -328,6 +329,133 @@ test.group('DataDomain.findEntity()', () => {
   })
 })
 
+test.group('DomainEntity.addSemantic()', () => {
+  test('adds a new semantic to the entity', ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel({ key: 'test-model' })
+    const entity = dataDomain.addEntity(model.key, { key: 'test-entity' })
+    const semantic = { id: SemanticType.User }
+    entity.addSemantic(semantic)
+    assert.deepInclude(entity.semantics, semantic)
+  })
+
+  test('updates an existing semantic', ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel({ key: 'test-model' })
+    const entity = dataDomain.addEntity(model.key, { key: 'test-entity' })
+    const semantic1 = { id: SemanticType.User, config: { value: 'old' } }
+    const semantic2 = { id: SemanticType.User, config: { value: 'new' } }
+    entity.addSemantic(semantic1)
+    entity.addSemantic(semantic2)
+    assert.lengthOf(entity.semantics, 1)
+    assert.deepInclude(entity.semantics, semantic2)
+  })
+
+  test('throws an error if the semantic is not an entity semantic', ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel({ key: 'test-model' })
+    const entity = dataDomain.addEntity(model.key, { key: 'test-entity' })
+    const semantic = { id: SemanticType.CreatedTimestamp } // CreatedTimestamp is a Property semantic
+    assert.throws(() => {
+      entity.addSemantic(semantic)
+    }, `Invalid semantic type: ${SemanticType.CreatedTimestamp}. Expected an entity semantic.`)
+  })
+
+  test('notifies change when adding a new semantic', async ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel({ key: 'test-model' })
+    const entity = dataDomain.addEntity(model.key, { key: 'test-entity' })
+    const semantic = { id: SemanticType.User }
+    entity.addSemantic(semantic)
+    await assert.dispatches(dataDomain, 'change', { timeout: 20 })
+  })
+
+  test('notifies change when updating an existing semantic', async ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel({ key: 'test-model' })
+    const entity = dataDomain.addEntity(model.key, { key: 'test-entity' })
+    const semantic1 = { id: SemanticType.User, config: { value: 'old' } }
+    const semantic2 = { id: SemanticType.User, config: { value: 'new' } }
+    entity.addSemantic(semantic1)
+    // Clear the event queue before the second add
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    entity.addSemantic(semantic2)
+    await assert.dispatches(dataDomain, 'change', { timeout: 20 })
+  })
+})
+
+test.group('DomainEntity.removeSemantic()', () => {
+  test('removes an existing semantic from the entity', ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel({ key: 'test-model' })
+    const entity = dataDomain.addEntity(model.key, { key: 'test-entity' })
+    const semantic = { id: SemanticType.User }
+    entity.addSemantic(semantic)
+    assert.deepInclude(entity.semantics, semantic)
+    entity.removeSemantic(SemanticType.User)
+    assert.notDeepInclude(entity.semantics, semantic)
+    assert.lengthOf(entity.semantics, 0)
+  })
+
+  test('does nothing if the semantic to remove does not exist', ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel({ key: 'test-model' })
+    const entity = dataDomain.addEntity(model.key, { key: 'test-entity' })
+    const semantic = { id: SemanticType.User }
+    entity.addSemantic(semantic)
+    const initialSemantics = [...entity.semantics]
+    entity.removeSemantic('non-existent-semantic-id' as SemanticType)
+    assert.deepEqual(entity.semantics, initialSemantics)
+  })
+
+  test('notifies change when a semantic is removed', async ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel({ key: 'test-model' })
+    const entity = dataDomain.addEntity(model.key, { key: 'test-entity' })
+    const semantic = { id: SemanticType.User }
+    entity.addSemantic(semantic)
+    // Clear the event queue before removal
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    entity.removeSemantic(SemanticType.User)
+    await assert.dispatches(dataDomain, 'change', { timeout: 20 })
+  })
+
+  test('does not notify change if the semantic to remove does not exist', async ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel({ key: 'test-model' })
+    const entity = dataDomain.addEntity(model.key, { key: 'test-entity' })
+    // Clear the event queue before removal
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    entity.removeSemantic('non-existent-semantic-id' as SemanticType)
+    await assert.notDispatches(dataDomain, 'change', { timeout: 20 })
+  })
+})
+
+test.group('DomainEntity.hasSemantic()', () => {
+  test('returns true if the entity has the specified semantic', ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel({ key: 'test-model' })
+    const entity = dataDomain.addEntity(model.key, { key: 'test-entity' })
+    const semantic = { id: SemanticType.User }
+    entity.addSemantic(semantic)
+    assert.isTrue(entity.hasSemantic(SemanticType.User))
+  })
+
+  test('returns false if the entity does not have the specified semantic', ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel({ key: 'test-model' })
+    const entity = dataDomain.addEntity(model.key, { key: 'test-entity' })
+    assert.isFalse(entity.hasSemantic(SemanticType.User))
+  })
+
+  test('returns false for an empty semantics array', ({ assert }) => {
+    const dataDomain = new DataDomain()
+    const model = dataDomain.addModel({ key: 'test-model' })
+    const entity = dataDomain.addEntity(model.key, { key: 'test-entity' })
+    assert.isFalse(entity.hasSemantic(SemanticType.User))
+  })
+})
+
 test.group('DataDomain.moveEntity()', () => {
   test('moves an entity from one model to another', ({ assert }) => {
     const dataDomain = new DataDomain()

package/tests/unit/modeling/data_domain_property.spec.ts

@@ -67,7 +67,7 @@ test.group('DataDomain.addProperty()', () => {
     assert.throws(() => {
       // @ts-expect-error For testing purposes, we are passing undefined
       dataDomain.addProperty(undefined)
-    }, 'A property expects a DataEntity parent')
+    }, 'A property expects a DomainEntity parent')
   })
 
   test('addProperty throws when adding property to a foreign entity', ({ assert }) => {