DTOs

Every @expose / @service entity gets its DTO (XxxDTO), search DTO (XxxSrchDTO) and key DTO without a dto: section. Declare a DTO when you want a different shape - fields across references, fields left out, a DTO for a list of members (@dtype(List<OrderLineDTO>)).

model/dto.yml

dto:
  OrderLineDTO:
    meta: dto @template(OrderLine)
    fields:
      itemName: string @ref(item.name)          # the item's name in the answer

  ArticleDTO:
    meta: dto @template(Article)
    fields:
      boardName: string @ref(board.name)
      createDate: --                            # left out of the template

  ArticleSrchDTO:
    meta: dto @searchable(entity=Article, pageSize=50)
    fields:
      title: string @search(like)
      boardType: List<BoardType> @search(in) @ref(board.boardType)
      createDateFrom: date @search(between)
      createDateTo: date @search(between)

  CustomDTO:
    meta: dto
    fields:
      field1: string
      field2: int

Meta annotations

Annotation	Means
@template(Entity)	the entity's fields; several: @template(A, B). string(n) becomes @Size(max=n)
@searchable(entity=E, pageSize=n)	a search DTO turned into a Specification; adds pageNumber, pageSize, sortCode
@sort(field+)	the default order of this search DTO (wins over the entity's)
@jsonview / @jsonview(auto)	field visibility per create / read / update with Jackson @JsonView

Field annotations

Annotation	Means
@ref(field.path)	a value across references
--	the template's field left out
@view(cru)	@jsonview visibility (c = create, r = read, u = update)
@readonly	this DTO's mapping does not write the field to the entity
!	required - a DTO of your own says it on its own fields (postId: long! @ref(post.postId))

Members of a root

A root that carries its members in requests and answers names the members' DTO with @dtype, and the DTO is declared:

PurchaseOrder:
  fields:
    lines: List<OrderLine> @OneToMany(mappedBy="order") @dtype(List<OrderLineDTO>) @minsize(1, 'the cart is empty')

dto:
  OrderLineDTO:
    meta: dto @template(OrderLine)

A DTO named in @dtype(...) that no dto: section declares warns unresolved type 'OrderLineDTO' at generation and breaks compileJava - compile even when generation succeeded.