Entity Structure

Basic Settings

Primitive Data Types

Complex Data Types

Field Configuration

Relationship Types

Relationship Properties

Annotation System Overview

Every entity in BijouCore can be enhanced with annotations, which function as a sophisticated tagging system. Annotations are displayed as colored tags in the UI and can be filtered, searched, and managed according to user permissions.

• Annotations are automatically included in all OData responses via the $Annotations field
• Each annotation has a Type that defines its appearance (color, icon) and category
• Annotations can optionally include a Subject field for additional context
• Permissions for annotations follow the entity's read/write permissions

Annotation Types

Annotation types are managed through the Studio and define how annotations appear and behave.

Using Annotations in the UI

• Entity Details Pages: Annotations appear as tags in the header card with inline subject text
• Data Tables: A dedicated "Tags" column shows all annotations for each record
• Creating Annotations: Click the tag+ button and select from available types
• Editing Annotations: Click on any tag to edit its subject text
• Deleting Annotations: Click the X icon on a tag (with confirmation)

API Access

Annotations can be accessed and managed through the OData API:

// Get entity - annotations are always included
GET /$odata/Customer('123e4567-e89b-12d3-a456-426614174000')

// Response includes $Annotations field:
{
  "Id": "123e4567-e89b-12d3-a456-426614174000",
  "Name": "Customer Name",
  "$Annotations": [...]
}

// Create annotation
POST /$odata/Customer/{id}/annotations
{
  "TypeId": "annotation-type-id",
  "Subject": "Important customer note"
}

// Update annotation
PUT /$odata/Customer/{id}/annotations/{annotationId}
{
  "Subject": "Updated note"
}

// Delete annotation
DELETE /$odata/Customer/{id}/annotations/{annotationId}

Entity Naming

• Use PascalCase for entity names (e.g., CustomerOrder)
• Choose singular nouns rather than plurals (e.g., Product not Products)
• Be specific and avoid generic names (e.g., InvoiceItem rather than Item)
• Avoid abbreviations or acronyms unless widely understood

Field Naming

• Use PascalCase for field names (e.g., FirstName)
• For relationship fields, include the target entity name (e.g., CustomerAddress)
• For boolean fields, use prefixes like "Is", "Has", or "Can" (e.g., IsActive, HasAttachments)
• Date fields typically end with "Date", "Time", or "At" (e.g., CreatedAt, StartDate)

Entity Structure

• Include a descriptive string field that can be used as the ItemTitle
• Enable OptimisticLockEnabled for entities that may be concurrently edited
• Enable FullTextSearchEnabled only when search across multiple string fields is needed
• Keep fields focused on a single responsibility; avoid overloading fields with multiple purposes
• Design relationships carefully, considering query patterns and data access needs