@api-client/core 0.16.1 → 0.17.0

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

@@ -42062,6 +42062,9 @@
 "@id": "#209"
 },
 {
+"@id": "#200"
+},
+{
 "@id": "#191"
 },
 {
@@ -42071,9 +42074,6 @@
 "@id": "#197"
 },
 {
-"@id": "#200"
-},
-{
 "@id": "#203"
 },
 {
@@ -43436,7 +43436,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "countryCode: \"BE\"\ngraydonEnterpriseId: 1057155523\nregistrationId: \"0422319093\"\nvatNumber: \"BE0422319093\"\ngraydonCompanyId: \"0422319093\"\nisBranchOffice: false\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": [
 {
@@ -43457,7 +43457,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": "code: '5'\ndescription: 'Limited company'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -43478,7 +43478,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "code: '5'\ndescription: 'Limited company'\n",
+"doc:raw": "class: '3'\ndescription: '150 - 300'\nnumberOfFte: 5500\nnumberOfEmployees: 5232\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -43499,7 +43499,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "class: '3'\ndescription: '150 - 300'\nnumberOfFte: 5500\nnumberOfEmployees: 5232\n",
+"doc:raw": "countryCode: \"BE\"\ngraydonEnterpriseId: 1057155523\nregistrationId: \"0422319093\"\nvatNumber: \"BE0422319093\"\ngraydonCompanyId: \"0422319093\"\nisBranchOffice: false\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -44756,22 +44756,22 @@
 {
 "@id": "#193/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#193",
-"sourcemaps:value": "[(1,0)-(7,0)]"
+"sourcemaps:value": "[(1,0)-(10,0)]"
 },
 {
 "@id": "#196/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#196",
-"sourcemaps:value": "[(1,0)-(10,0)]"
+"sourcemaps:value": "[(1,0)-(3,0)]"
 },
 {
 "@id": "#199/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#199",
-"sourcemaps:value": "[(1,0)-(3,0)]"
+"sourcemaps:value": "[(1,0)-(5,0)]"
 },
 {
 "@id": "#202/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#202",
-"sourcemaps:value": "[(1,0)-(5,0)]"
+"sourcemaps:value": "[(1,0)-(7,0)]"
 },
 {
 "@id": "#205/source-map/lexical/element_0",

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.16.1",
+  "version": "0.17.0",
   "license": "Apache-2.0",
   "exports": {
     "./browser.js": {

package/src/modeling/Semantics.ts

@@ -227,6 +227,44 @@ export enum SemanticScope {
   Association = 'Association',
 }
 
+/**
+ * Defines categories for organizing semantics in the UI.
+ */
+export enum SemanticCategory {
+  /**
+   * User management, authentication, and access control
+   */
+  Identity = 'Identity & Authentication',
+  /**
+   * Timestamps, versioning, and record lifecycle
+   */
+  Lifecycle = 'Timestamps & Versioning',
+  /**
+   * Text content, media, and rich content types
+   */
+  Content = 'Content & Media',
+  /**
+   * Business-specific data like pricing, inventory, status
+   */
+  Business = 'Business Data',
+  /**
+   * Contact information and communication
+   */
+  Contact = 'Contact Information',
+  /**
+   * Organization, categorization, and tagging
+   */
+  Organization = 'Classification & Organization',
+  /**
+   * Location and geographical data
+   */
+  Location = 'Location & Geography',
+  /**
+   * Calculated and derived values
+   */
+  Computed = 'Computed Values',
+}
+
 /**
  * A base interface for all Data Semantics, containing common properties.
  * A semantic is an annotation applied to a Data Entity, Property, or Association
@@ -250,6 +288,10 @@ interface BaseDataSemantic {
    * Specifies whether the semantic applies to an Entity, Property, or Association.
    */
   scope: SemanticScope
+  /**
+   * The category this semantic belongs to for UI organization.
+   */
+  category: SemanticCategory
 }
 
 /**
@@ -307,213 +349,296 @@ export type DataSemantic = EntitySemantic | PropertySemantic | AssociationSemant
  */
 export const DataSemantics: Record<SemanticType, DataSemantic> = {
   //
-  // Entity-Level Definitions
+  // Identity & Authentication
   //
 
   [SemanticType.User]: {
     id: SemanticType.User,
     displayName: 'User Entity',
     scope: SemanticScope.Entity,
-    description: 'Designates an entity that represents system users, crucial for authentication and authorization.',
+    description: 'System users and accounts',
+    category: SemanticCategory.Identity,
   },
-
-  //
-  // Property-Level Definitions
-  //
-
   [SemanticType.Password]: {
     id: SemanticType.Password,
     displayName: 'User Password',
     scope: SemanticScope.Property,
-    description:
-      'Annotates the field as the user password. The runtime should treat this field with special care, ensuring it is encrypted and not exposed in API responses.',
+    description: 'Secure password field',
+    category: SemanticCategory.Identity,
+    applicableDataTypes: ['string'],
+  },
+  [SemanticType.UserRole]: {
+    id: SemanticType.UserRole,
+    displayName: 'User Role Field',
+    scope: SemanticScope.Property,
+    description: 'User permissions and access level',
+    category: SemanticCategory.Identity,
     applicableDataTypes: ['string'],
   },
+  [SemanticType.ResourceOwnerIdentifier]: {
+    id: SemanticType.ResourceOwnerIdentifier,
+    displayName: 'Resource Owner Identifier',
+    scope: SemanticScope.Association,
+    description: 'Links record to owner user',
+    category: SemanticCategory.Identity,
+  },
+
+  //
+  // Timestamps & Versioning
+  //
+
   [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.",
+    description: 'When record was created',
+    category: SemanticCategory.Lifecycle,
     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.",
+    description: 'When record was last modified',
+    category: SemanticCategory.Lifecycle,
     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.",
+    description: 'When record was marked deleted',
+    category: SemanticCategory.Lifecycle,
     applicableDataTypes: ['datetime'],
   },
-  [SemanticType.PublicUniqueName]: {
-    id: SemanticType.PublicUniqueName,
-    displayName: 'Public Unique Name (Slug)',
+  [SemanticType.DeletedFlag]: {
+    id: SemanticType.DeletedFlag,
+    displayName: 'Soft Delete Flag',
     scope: SemanticScope.Property,
-    description: 'A user-friendly, unique public identifier for a resource, often used in URLs.',
-    applicableDataTypes: ['string'],
+    description: 'Mark record as deleted',
+    category: SemanticCategory.Lifecycle,
+    applicableDataTypes: ['boolean'],
+  },
+  [SemanticType.Version]: {
+    id: SemanticType.Version,
+    displayName: 'Version Number',
+    scope: SemanticScope.Property,
+    description: 'Auto-incrementing version counter',
+    category: SemanticCategory.Lifecycle,
+    applicableDataTypes: ['number'],
   },
+
+  //
+  // Content & Media
+  //
+
   [SemanticType.Title]: {
     id: SemanticType.Title,
     displayName: 'Record Title',
     scope: SemanticScope.Property,
-    description: 'A title for the record. Used as a source for the PublicUniqueName semantic.',
+    description: 'Main title or heading',
+    category: SemanticCategory.Content,
     applicableDataTypes: ['string'],
   },
-  [SemanticType.UserRole]: {
-    id: SemanticType.UserRole,
-    displayName: 'User Role Field',
+  [SemanticType.Description]: {
+    id: SemanticType.Description,
+    displayName: 'Description',
     scope: SemanticScope.Property,
-    description: "A text or enum field that defines the user's role for role-based authorization.",
+    description: 'Detailed description text',
+    category: SemanticCategory.Content,
     applicableDataTypes: ['string'],
   },
-  [SemanticType.Status]: {
-    id: SemanticType.Status,
-    displayName: 'Record Status',
+  [SemanticType.Summary]: {
+    id: SemanticType.Summary,
+    displayName: 'Summary',
     scope: SemanticScope.Property,
-    description: 'A text or enum field to represent the state of a record.',
+    description: 'Brief summary text',
+    category: SemanticCategory.Content,
     applicableDataTypes: ['string'],
   },
-  [SemanticType.Version]: {
-    id: SemanticType.Version,
-    displayName: 'Version Number',
+  [SemanticType.Markdown]: {
+    id: SemanticType.Markdown,
+    displayName: 'Markdown Content',
     scope: SemanticScope.Property,
-    description: 'An integer field that automatically increments on every update.',
-    applicableDataTypes: ['number'],
+    description: 'Formatted text content',
+    category: SemanticCategory.Content,
+    applicableDataTypes: ['string'],
+  },
+  [SemanticType.HTML]: {
+    id: SemanticType.HTML,
+    displayName: 'HTML Content',
+    scope: SemanticScope.Property,
+    description: 'Rich HTML content',
+    category: SemanticCategory.Content,
+    applicableDataTypes: ['string'],
   },
   [SemanticType.ImageURL]: {
     id: SemanticType.ImageURL,
     displayName: 'Image URL',
     scope: SemanticScope.Property,
-    description: 'Annotates a field that holds a reference to an image data via an URL.',
+    description: 'Link to image file',
+    category: SemanticCategory.Content,
     applicableDataTypes: ['string'],
   },
   [SemanticType.FileURL]: {
     id: SemanticType.FileURL,
     displayName: 'File URL',
     scope: SemanticScope.Property,
-    description: 'Annotates a field that holds a reference to a file object via an URL (non-image binary data).',
+    description: 'Link to file attachment',
+    category: SemanticCategory.Content,
     applicableDataTypes: ['string'],
   },
-  [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.Markdown]: {
-    id: SemanticType.Markdown,
-    displayName: 'Markdown Content',
+
+  //
+  // Business Data
+  //
+
+  [SemanticType.Status]: {
+    id: SemanticType.Status,
+    displayName: 'Record Status',
     scope: SemanticScope.Property,
-    description: 'A text field that contains markdown content.',
+    description: 'Current state of record',
+    category: SemanticCategory.Business,
     applicableDataTypes: ['string'],
   },
-  [SemanticType.HTML]: {
-    id: SemanticType.HTML,
-    displayName: 'HTML Content',
+  [SemanticType.Price]: {
+    id: SemanticType.Price,
+    displayName: 'Price',
     scope: SemanticScope.Property,
-    description: 'Annotates a field that contains HTML content.',
-    applicableDataTypes: ['string'],
+    description: 'Monetary value with currency',
+    category: SemanticCategory.Business,
+    applicableDataTypes: ['number', 'string'],
   },
-  [SemanticType.GeospatialCoordinates]: {
-    id: SemanticType.GeospatialCoordinates,
-    displayName: 'Geospatial Coordinates',
+  [SemanticType.SKU]: {
+    id: SemanticType.SKU,
+    displayName: 'SKU',
     scope: SemanticScope.Property,
-    description: 'Annotates a field that holds geospatial coordinate data (latitude/longitude).',
+    description: 'Product identification code',
+    category: SemanticCategory.Business,
     applicableDataTypes: ['string'],
   },
+
+  //
+  // Contact Information
+  //
+
   [SemanticType.Email]: {
     id: SemanticType.Email,
     displayName: 'Email',
     scope: SemanticScope.Property,
-    description: 'Annotates a field as an email address with validation and verification options.',
+    description: 'Email address',
+    category: SemanticCategory.Contact,
     applicableDataTypes: ['string'],
   },
   [SemanticType.Phone]: {
     id: SemanticType.Phone,
     displayName: 'Phone',
     scope: SemanticScope.Property,
-    description: 'Annotates a field as a phone number with validation and formatting options.',
+    description: 'Phone number',
+    category: SemanticCategory.Contact,
     applicableDataTypes: ['string'],
   },
-  [SemanticType.Price]: {
-    id: SemanticType.Price,
-    displayName: 'Price',
-    scope: SemanticScope.Property,
-    description: 'Annotates a field as a monetary value with currency support and precision control.',
-    applicableDataTypes: ['number', 'string'],
-  },
   [SemanticType.URL]: {
     id: SemanticType.URL,
     displayName: 'URL',
     scope: SemanticScope.Property,
-    description: 'Annotates a field as a URL with validation and allowed protocols.',
+    description: 'Web address or link',
+    category: SemanticCategory.Contact,
     applicableDataTypes: ['string'],
   },
-  [SemanticType.SKU]: {
-    id: SemanticType.SKU,
-    displayName: 'SKU',
+
+  //
+  // Classification & Organization
+  //
+
+  [SemanticType.PublicUniqueName]: {
+    id: SemanticType.PublicUniqueName,
+    displayName: 'Public Unique Name (Slug)',
     scope: SemanticScope.Property,
-    description:
-      'Annotates a field as a Stock Keeping Unit (SKU). Enforces uniqueness at the database level, critical for product catalogs. Provides automatic validation and formatting for product identification codes.',
+    description: 'URL-friendly unique identifier',
+    category: SemanticCategory.Organization,
     applicableDataTypes: ['string'],
   },
-  [SemanticType.Description]: {
-    id: SemanticType.Description,
-    displayName: 'Description',
-    scope: SemanticScope.Property,
-    description: 'Annotates a field as a long-form description.',
-    applicableDataTypes: ['string'],
+  [SemanticType.Tags]: {
+    id: SemanticType.Tags,
+    displayName: 'Tags',
+    scope: SemanticScope.Association,
+    description: 'Enable tagging functionality',
+    category: SemanticCategory.Organization,
   },
-  [SemanticType.Summary]: {
-    id: SemanticType.Summary,
-    displayName: 'Summary',
+  [SemanticType.Categories]: {
+    id: SemanticType.Categories,
+    displayName: 'Categories',
+    scope: SemanticScope.Association,
+    description: 'Enable categorization functionality',
+    category: SemanticCategory.Organization,
+  },
+
+  //
+  // Location & Geography
+  //
+
+  [SemanticType.GeospatialCoordinates]: {
+    id: SemanticType.GeospatialCoordinates,
+    displayName: 'Geospatial Coordinates',
     scope: SemanticScope.Property,
-    description: 'Annotates a field as a short summary.',
+    description: 'Location coordinates',
+    category: SemanticCategory.Location,
     applicableDataTypes: ['string'],
   },
+
+  //
+  // Computed Values
+  //
+
   [SemanticType.Calculated]: {
     id: SemanticType.Calculated,
     displayName: 'Calculated',
     scope: SemanticScope.Property,
-    description: 'Annotates a field as a calculated value based on a formula.',
+    description: 'Auto-calculated field value',
+    category: SemanticCategory.Computed,
     applicableDataTypes: ['string'],
   },
   [SemanticType.Derived]: {
     id: SemanticType.Derived,
     displayName: 'Derived',
     scope: SemanticScope.Property,
-    description: 'Annotates a field as derived from other fields.',
+    description: 'Value derived from other fields',
+    category: SemanticCategory.Computed,
     applicableDataTypes: ['string'],
   },
+}
 
-  //
-  // Association-Level Definitions
-  //
+/**
+ * Helper function to get all semantics grouped by category.
+ * Useful for organizing semantics in UI dropdowns and forms.
+ */
+export const getSemanticsByCategory = (): Record<SemanticCategory, DataSemantic[]> => {
+  const result: Record<SemanticCategory, DataSemantic[]> = {
+    [SemanticCategory.Identity]: [],
+    [SemanticCategory.Lifecycle]: [],
+    [SemanticCategory.Content]: [],
+    [SemanticCategory.Business]: [],
+    [SemanticCategory.Contact]: [],
+    [SemanticCategory.Organization]: [],
+    [SemanticCategory.Location]: [],
+    [SemanticCategory.Computed]: [],
+  }
 
-  [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.Tags]: {
-    id: SemanticType.Tags,
-    displayName: 'Tags',
-    scope: SemanticScope.Association,
-    description: 'Annotates an association as supporting tag functionality.',
-  },
-  [SemanticType.Categories]: {
-    id: SemanticType.Categories,
-    displayName: 'Categories',
-    scope: SemanticScope.Association,
-    description: 'Annotates an association as supporting category functionality.',
-  },
+  Object.values(DataSemantics).forEach((semantic) => {
+    result[semantic.category].push(semantic)
+  })
+
+  return result
+}
+
+/**
+ * Helper function to get semantics for a specific category.
+ * @param category The category to filter by
+ * @returns Array of semantics in the specified category
+ */
+export const getSemanticsByCategoryType = (category: SemanticCategory): DataSemantic[] => {
+  return Object.values(DataSemantics).filter((semantic) => semantic.category === category)
 }
 
 /**