Skip to main content

Entity Definition

Overview​

ElastiCORE DSL is a YAML-based domain model definition language that generates Java code by defining entities, DTOs, enumerations, repositories, and transaction ports. These definition files can be freely named with a .yml extension under the ./resources/blueprint/{domainName} directory. It is recommended to create separate files by model type and write the relevant definitions in each. e.g., entity.yml, dto.yml For detailed environment configuration, see env.yml Configuration.

Basic Structure​

entity:
  EntityName:
    meta: entity [annotations]
    fields:
      fieldName: fieldType [annotations] -- comment

Meta Annotations​

  • entity: Basic entity declaration
  • @abstract: Abstract entity (for inheritance only)
  • @extend(ParentEntity): Entity inheritance
  • @expose(n): REST API exposure and page size configuration (generates Controller, Service, SearchDTO)
  • @service(n): Generates service layer only with page size configuration (no Controller; generates Service, SearchDTO)
  • @audited: JPA Envers audit target
  • @dto: Marks the entity for DTO generation
  • @pageable: Pagination support
  • @embeddable: JPA Embeddable entity
  • @table(tableName): Specify table name
  • @java(fullClassName): Specify the generated Java class name
  • @Index(name="idx_name", columnList="col1,col2"): Index definition

Field Annotations​

  • @id: Primary key
  • @sequence: Auto-increment sequence
  • @genid: Custom ID generator (see env.yml configuration)
  • @GeneratedValue: JPA auto-generated value
  • @length(n): Maximum string length
  • @default(value): Default value
  • @search(like|eq|between|in): Search condition configuration
  • @updatable(false): Non-updatable field
  • @ref(path): Reference to another field
  • @dtype(type): Explicit DTO type specification
  • @cascade(ALL|PERSIST|MERGE|REMOVE): Relationship cascade configuration
  • @relation(mappedBy="fieldName"): Relationship mapping
  • @notaudited: Exclude field from auditing
  • @Column(name="col_name", length=n): JPA column mapping
  • @env:annotationName: Reference to environment configuration annotation
tip

For detailed information on field annotations, see Annotation Guide.

JPA Relationship Annotations​

  • @OneToMany(mappedBy="fieldName"): One-to-many relationship
  • @ManyToOne: Many-to-one relationship
  • @ManyToMany: Many-to-many relationship
  • @OneToOne: One-to-one relationship

Spring Data JPA Annotations​

  • @jpa:org.springframework.data.annotation.CreatedDate: Auto-set creation timestamp
  • @jpa:org.springframework.data.annotation.CreatedBy: Auto-set creator
  • @jpa:org.springframework.data.annotation.LastModifiedDate: Auto-set modification timestamp
  • @jpa:org.springframework.data.annotation.LastModifiedBy: Auto-set modifier

Field Types​

For detailed field type information, see Field Types Reference.

  • string(n), string(n)!: String (! = NOT NULL)
  • text: Long text (TEXT type)
  • int, Integer: Integer
  • long, Long: Long integer
  • double, Double: Floating-point number
  • boolean, Boolean: Boolean
  • bigdecimal(precision.scale): Fixed-point number (e.g., bigdecimal(15.2) → @Column(precision = 15, scale = 2))
  • date: Date (LocalDate)
  • datetime: Date and time (LocalDateTime)
  • int[], string[]: Array types
  • List<Type>: List type
  • EnumName: Enumeration reference
  • EntityName: Entity reference

Entity Examples​

entity:
  BaseEntity:
    meta: entity @abstract
    fields:
      createDate: datetime @search(between) @updatable(false) @jpa:org.springframework.data.annotation.CreatedDate
      createdBy: string(20) @updatable(false) @jpa:org.springframework.data.annotation.CreatedBy

  AuditEntity:
    meta: entity @abstract @extend(BaseEntity)
    fields:
      lastModifiedBy: string(20) @jpa:org.springframework.data.annotation.LastModifiedBy
      lastModifiedDate: datetime @jpa:org.springframework.data.annotation.LastModifiedDate
      createIP: string(20) -- System input IP
      lastModifiedIP: string(20) -- System modification IP

  Board:
    meta: entity @expose(50) @extend(AuditEntity) @Index(name="idx_board_type", columnList="board_type")
    fields:
      bid: long @id @sequence -- Board ID
      name: string(100)! @search(like) -- Board name
      boardType: BoardType -- Board type
      articles: List<Article> @dtype(List<ArticleDTO>) @OneToMany(mappedBy="board")

  Article:
    meta: entity @expose(50) @extend(AuditEntity)
    fields:
      aid: string @id @genid -- Article ID
      title: string(200)! @search(like) -- Title
      content: text -- Content body
      price: bigdecimal(10.2) @search(between) -- Price (precision 10, scale 2)
      board: Board @ManyToOne -- Parent board
      coordinates: int[] @env:integerarray -- Coordinate array

Advanced Features​

Composite Key Definition​

entity:
  CompositeKeyEntity:
    meta: entity
    fields:
      key1: string @id
      key2: string @id
      data: string

Embedded Entity​

entity:
  Address:
    meta: entity @embeddable
    fields:
      postNo: string(5) @Column(name="post_no", length=5)
      baseAddr: string(200) @Column(name="base_addr", length=200)
      detailAddr: string(300) @Column(name="detail_addr", length=300)

  User:
    meta: entity
    fields:
      userId: long @id @sequence
      name: string(100)!
      address: Address -- Embedded address

Inheritance​

entity:
  Vehicle:
    meta: entity @abstract
    fields:
      id: string @id
      brand: string(50)
      model: string(100)

  Car:
    meta: entity @extend(Vehicle)
    fields:
      doors: int -- Number of doors
      fuelType: FuelType

  Motorcycle:
    meta: entity @extend(Vehicle)
    fields:
      engineSize: int -- Engine displacement

Many-to-Many Relationships​

entity:
  User:
    meta: entity
    fields:
      userId: long @id @sequence
      username: string(50)!
      roles: List<Role> @ManyToMany

  Role:
    meta: entity
    fields:
      roleId: long @id @sequence
      roleName: string(50)!
      users: List<User> @ManyToMany(mappedBy="roles")

Naming Conventions​

Entities​

  • Class name: PascalCase (Board, Article, BoardType)
  • Field name: camelCase (boardId, createDate, lastModifiedBy)
  • Table name: snake_case (board, article, board_type)

ID Fields​

  • Pattern: entity name (lowercase) + "Id" (boardId, articleId, userId)

Best Practices​

  1. Inheritance hierarchy design: BaseEntity → AuditEntity → Concrete entity
  2. Search capability: Add @search annotations to frequently searched fields
  3. Index optimization: Configure @Index for query performance
  4. Relationship mapping: Use @dtype to specify DTO types and prevent circular references
  5. Audit tracking: Apply @audited to critical entities
  6. Field validation: Mark NOT NULL fields with !
  7. Environment configuration: Define common annotations in env.yml

Important Notes​

  • Circular references: Prevent with @dtype in bidirectional relationships
  • Performance considerations: Use pagination for large datasets (@pageable, @expose)
  • Data consistency: Be careful with @cascade settings for foreign key relationships
  • Search optimization: Consider index design for complex search conditions