Entities & fields

May 6, 2026 · View on GitHub

Entities are defined under the entities section. Each entity describes:

a generated Java model class (JPA @Entity for SQL, Spring Data @Document for MongoDB)
its storage name (SQL table name or MongoDB collection name)
its fields, constraints, and relationships
optional metadata used for documentation (Javadoc, OpenAPI descriptions, etc.)

Entity schema

entities:
  - name: ProductModel
    storageName: product_table
    description: "Represents a product"
    softDelete: true
    audit:
      enabled: true
      type: Instant
    fields: []

Property	Type	Required	Description
`name`	string	✅	Java class name of the entity/model
`storageName`	string	conditional	SQL: table name. MongoDB: collection name. Optional only for models used exclusively as inner JSON types.
`description`	string	optional	Used to generate Javadoc and enrich API docs (where applicable)
`audit`	object	optional	Audit configuration for `createdAt` / `updatedAt` fields
`bulk`	object	optional	Entity-level bulk operation configuration (`bulk create` and `bulk delete`)
`sort`	object	optional	Per-entity sorting configuration for list endpoints/queries
`security`	object	optional	Entity-level role mapping for CRUD and relation endpoints
`softDelete`	boolean	optional	Enables soft delete for this entity (default: `false`)
`fields`	list	✅	List of fields for the entity

If description is provided, the generator can produce Javadoc for entities/fields.

Soft delete configuration

Soft delete allows “deleting” records without physically removing them from the database.

softDelete: true

Property	Type	Required	Description
`softDelete`	boolean	optional	Enables soft delete behavior (default: `false`)

Generator behavior (when `softDelete: true`)

SQL databases: The entity is generated with Hibernate soft-delete annotations (@SQLDelete and @SQLRestriction) so that DELETE statements become UPDATE statements (logical delete).

MongoDB: A deleted boolean field is added to the document, and service/repository methods apply a filter to exclude soft-deleted documents from queries.

Audit configuration

The audit block controls automatic creation of audit fields on the entity (typically createdAt and updatedAt).

audit:
  enabled: true
  type: INSTANT

Property	Type	Required	Description
`enabled`	boolean	optional	Enables audit fields (`createdAt`, `updatedAt`) for this entity (default: `false`)
`type`	enum	optional	Underlying temporal type used for audit fields

SQL databases: Audit fields map to created_at / updated_at columns using Spring Data JPA auditing (@CreatedDate, @LastModifiedDate).

MongoDB: Audit fields are stored as document fields using Spring Data MongoDB auditing (@CreatedDate, @LastModifiedDate).

Possible type values:

Instant
LocalDate
LocalDateTime

Sort configuration

Sorting can be configured per entity and is used by generated REST list endpoints, GraphQL page queries, and OpenAPI docs.

sort:
  allowedFields: [name, price, createdAt]
  defaultDirection: ASC

Property	Type	Required	Description
`allowedFields`	list	required	Fields allowed in `sortBy`
`defaultDirection`	enum	optional	Default direction (`ASC` or `DESC`, default: `ASC`)

Validation rules:

when sort is configured, allowedFields must not be empty
each allowedFields value must reference an entity field (or createdAt/updatedAt when audit is enabled)
unsupported sortable targets are rejected: simple collections, JSON fields, relation collections

Runtime behavior:

when sortBy is not provided, no sorting is applied
when sortBy is provided, it must be one of allowedFields
when sortBy is provided and sortDirection is omitted, defaultDirection is used

Bulk operations configuration

Bulk operations are opt-in per entity and currently support:

POST /{entity-path}/bulk for bulk create
DELETE /{entity-path}/bulk for bulk delete
GraphQL createBulk<Entity> mutation for bulk create
GraphQL deleteBulk<Entity> mutation for bulk delete

Preferred shape:

bulk:
  create:
    enabled: true
  delete:
    enabled: true

If bulk is absent, both bulk create and bulk delete generation are disabled for that entity.

Entity security configuration

Per-entity security lets you override role requirements for generated endpoints.

entities:
  - name: ProductModel
    storageName: product_table
    security:
      getAll: [ADMIN, USER]
      getById: [ADMIN, USER]
      create: [ADMIN]
      update: [ADMIN]
      delete: [ADMIN]
      addRelation: [ADMIN]
      removeRelation: [ADMIN]
    fields: []

Property	Type	Description
`getAll`	list	Allowed roles for list endpoint (`GET /...`).
`getById`	list	Allowed roles for get-by-id endpoint.
`create`	list	Allowed roles for create endpoint.
`update`	list	Allowed roles for update endpoint.
`delete`	list	Allowed roles for delete endpoint.
`addRelation`	list	Allowed roles for add-relation endpoints.
`removeRelation`	list	Allowed roles for remove-relation endpoints.

Behavior notes:

Security annotations are generated only when global configuration.security.enabled: true.
The same operation mapping is applied to generated REST endpoints and GraphQL resolver methods (when GraphQL is enabled).
If operation roles are omitted, generated endpoint falls back to authenticated access (isAuthenticated()).
If the whole entity security block is omitted, all endpoints for that entity fall back to authenticated access.

Field schema

fields:
  - name: id
    type: Long
    description: "Primary key"
    id:
      strategy: IDENTITY

Property	Type	Required	Description
`name`	string	✅	Java field name
`type`	string	✅	Java type (e.g. `String`, `Long`, `UUID`, `LocalDate`, `Enum`, `JSON<Type>`, entity name for relations, or `List<BasicType>` / `Set<BasicType>`)
`description`	string	optional	Used for Javadoc and API documentation
`example`	string	optional	Example value emitted in generated OpenAPI schema (`components/schemas/...`)
`id`	object or boolean	optional	SQL: object with `strategy` and optional generator fields. MongoDB: use marker `id: true`.
`column`	object	optional	Column constraints (unique, nullable, insertable, updateable, length etc.)
`relation`	object	optional	Relationship definition (JPA-style)
`values`	list	required for `Enum`	Enum constant values (only when `type: Enum`)

Supported basic types are: String, Character, Integer, Long, Boolean, Double, Float, Short, Byte, UUID, BigDecimal, BigInteger, LocalDate, LocalDateTime, OffsetDateTime, Instant

Simple collections (ElementCollection)

Only supported for basic types:

List<BasicType>
Set<BasicType>

Example:

- name: phoneNumbers
  type: List<String>
- name: tags
  type: Set<Long>

SQL databases: The generator creates a separate collection table named ${storageName}_${snake_case(fieldName)} and links it to the owner entity via <entity>_id (JPA @ElementCollection).

MongoDB: The collection is stored as a native array field within the document — no extra collection/table is created.

JSON fields

Supported formats:

JSON<Type>
JSON<List<Type>>
JSON<Set<Type>>

Where Type can be:

a basic type (e.g. String, Long, UUID, BigDecimal, LocalDateTime, …)
a model name (another model defined in entities)

Example:

- name: metadata
  type: JSON<Metadata>
- name: tags
  type: JSON<Set<String>>
- name: events
  type: JSON<List<Event>>

Primary key: `id`

The id field definition differs between SQL and MongoDB:

SQL/JPA example

- name: id
  type: Long
  description: "The unique identifier for the entity"
  id:
    strategy: IDENTITY

MongoDB/NoSQL example

- name: id
  type: String
  id: true
  description: "Mongo document id"

Supported strategies:

TABLE
SEQUENCE
UUID
IDENTITY
AUTO

Property	Type	Required	Applies to	Description
`strategy`	enum	✅	SQL object form	ID generation strategy
`generatorName`	string	optional	`SEQUENCE`, `TABLE`	DB object name. For `SEQUENCE`: DB sequence name. For `TABLE`: generator table name.
`allocationSize`	number	optional	`SEQUENCE`, `TABLE`	Allocation size for sequence/table generators (defaults to `50`).
`initialValue`	number	optional	`SEQUENCE`, `TABLE`	Initial value for ID generation (defaults to `1`).
`pkColumnName`	string	optional	`TABLE`	Name of the “segment key” column in generator table (defaults to `gen_name`).
`valueColumnName`	string	optional	`TABLE`	Name of the “counter” column in generator table (defaults to `gen_value`).

Sequence-Based ID Example

- name: id
  type: Long
  id:
    strategy: SEQUENCE
    generatorName: product_id_seq  # optional, default: <table>_id_seq
    allocationSize: 10             # optional, default: 50
    initialValue: 1                # optional, default: 1

Table-Based ID Example

- name: id
  type: Long
  id:
    strategy: TABLE
    generatorName: product_id_gen  # optional, default: <table>_id_gen
    pkColumnName: my_gen_name      # optional, default: gen_name
    valueColumnName: my_gen_val    # optional, default: gen_value
    allocationSize: 5              # optional, default: 50
    initialValue: 1000             # optional, default: 1

For TABLE strategy, the pkColumnValue is automatically set to the entity's storageName (e.g. user_table), so you normally don't need to configure it manually.

Not all SQL databases support all ID strategies. SEQUENCE is best supported on PostgreSQL; IDENTITY works on MySQL, MariaDB, MSSQL, and PostgreSQL; TABLE works on all SQL databases.

Column constraints: `column.*`

SQL databases only. The column block maps to JPA @Column annotation properties and has no effect for MongoDB.

Use the column block to control column-level constraints:

- name: name
  type: String
  column:
    nullable: false
    updateable: true
    unique: true
    length: 255

Property	Type	Description
`nullable`	boolean	Whether the column can be null
`unique`	boolean	Whether the column must be unique
`length`	number	Column length (primarily for strings)
`insertable`	boolean	Whether the column can be inserted
`updateable`	boolean	Whether the column can be updated

For MongoDB, use validation.* to enforce constraints at the application level (e.g. required: true, notBlank: true).

Relationships: `relation.*`

Relationships are defined via the relation block. The type must be one of:

OneToOne
OneToMany
ManyToOne
ManyToMany

The same relation types work for both SQL and MongoDB, but the underlying implementation differs:

SQL: relations use JPA annotations with foreign keys / join tables
MongoDB: relations are represented as embedded documents or document references

SQL examples

# One-to-one (SQL)
- name: product
  type: ProductModel
  relation:
    type: OneToOne
    joinColumn: product_id
    fetch: EAGER
    cascade: MERGE

# One-to-many (SQL)
- name: users
  type: UserEntity
  relation:
    type: OneToMany
    joinColumn: product_id
    fetch: LAZY
    cascade: MERGE

# Many-to-many (SQL)
- name: users
  type: UserEntity
  relation:
    type: ManyToMany
    uniqueItems: true
    fetch: LAZY
    cascade: MERGE
    joinTable:
      name: order_user_table
      joinColumn: order_id
      inverseJoinColumn: user_id

MongoDB examples

For MongoDB, omit joinColumn, joinTable, fetch, and cascade — they are not applicable:

# One-to-one (MongoDB)
- name: product
  type: ProductModel
  relation:
    type: OneToOne

# One-to-many (MongoDB)
- name: users
  type: UserEntity
  relation:
    type: OneToMany
    uniqueItems: true

# Many-to-many (MongoDB)
- name: users
  type: UserEntity
  relation:
    type: ManyToMany
    uniqueItems: true

`uniqueItems`

uniqueItems can be used only with OneToMany and ManyToMany:

uniqueItems: true → generator uses Set/HashSet
omitted or false → generator uses List/ArrayList
for OneToOne and ManyToOne, validator reports an error

Relation properties

Property	Type	Applies to	Description
`type`	string	all	Relationship type (`OneToOne`, `OneToMany`, `ManyToOne`, `ManyToMany`)
`fetch`	string	SQL only	Fetch type (`EAGER`, `LAZY`)
`cascade`	string	SQL only	Cascade type (e.g. `MERGE`, `ALL`, `PERSIST`, etc.)
`uniqueItems`	boolean	all	Collection uniqueness for `OneToMany` / `ManyToMany` (`true` => `Set`, otherwise `List`)
`joinColumn`	string	SQL only	Join column name (for `OneToOne`, `OneToMany`, `ManyToOne`)
`joinTable`	object	SQL only	Join table config (used in `ManyToMany`)

Enums: `type: Enum` + `values`

To define an enum field:

- name: status
  type: Enum
  description: "The status of the product"
  values:
    - ACTIVE
    - INACTIVE

values is required when type is Enum.

JSON fields: `JSON<Type>`

- name: details
  type: JSON<Details>

Where Details is another entity-like schema definition (often used as an embedded structure):

- name: Details
  description: "Represents a user details"
  fields:
    - name: firstName
      type: String
    - name: lastName
      type: String

SQL databases: JSON types are stored in a single database column. Exact support depends on the database (PostgreSQL has native jsonb, MySQL/MariaDB have JSON columns, MSSQL uses nvarchar(max)).
MongoDB: JSON types map naturally to nested embedded documents — no special column type needed.

Validation

Validation rules are defined per-field using the validation block.

Validation schema

  - name: email
    type: String
    column:
      nullable: false
      unique: true
    validation:
      required: true
      notBlank: true
      email: true
      minLength: 5
      maxLength: 255
  - name: description
    type: String
    validation:
      required: true
      pattern: "^[A-Za-z]+$"
  - name: tags
    type: Set<String>
    validation:
      minItems: 1
      maxItems: 10

Property	Type	Applies to	Description
`required`	boolean	all	Field must be present (non-null)
`notBlank`	boolean	String	String must contain non-whitespace characters
`notEmpty`	boolean	String, collections	Must not be empty (`""` / `[]`)
`minLength`	integer	String	Minimum string length
`maxLength`	integer	String	Maximum string length
`min`	decimal	numbers	Minimum numeric value
`max`	decimal	numbers	Maximum numeric value
`minItems`	integer	collections	Minimum number of elements (`List<>`, `Set<>`)
`maxItems`	integer	collections	Maximum number of elements (`List<>`, `Set<>`)
`email`	boolean	String	Must be a valid e-mail address
`pattern`	string	String	Must match a valid Java regex pattern (e.g. `^[A-Za-z]+$`)

min / max map well to numeric validations (e.g. BigDecimal, Integer, Long, Double).
minItems / maxItems apply to List<BasicType> and Set<BasicType>.
pattern uses Java regex syntax (java.util.regex.Pattern).

Validation rules

required is about nullability. notBlank / notEmpty are about content (and non-null for the respective type).
If a validation field is used on an unsupported type, it will be ignored.
If pattern is provided, it must be a valid Java regex (Pattern.compile(pattern) must succeed). If not, the generator will fail fast with a clear error message.

Ignoring an entity

To skip generation for a specific entity:

- name: SomeEntity
  ignore: true
  fields: []