Entity Field Type

Description:
The entity field type is used to create complex fields containing nested fields. It allows you to group related data together and create structured, hierarchical data models. This field type is essential for creating complex forms, nested objects, and relationships within your application.

Elasticsearch Mapping: object with nested properties

YAML Definition 

- name: address
  type: entity
  display_name: "Address Information"
  guidance: "Enter the complete address details."
  required: true
  readonly: false
  hidden: false
  cardinality: "oneToOne"
  item_type: "address"
  fields: []
  pagesize: 10
  display_fields: []

Attributes

  • name (string): Required.
    The unique identifier for the field.

  • type (string): Required.
    Must be set to entity for entity fields.

  • display_name (string): Optional.
    The label displayed in the user interface. If not provided, a formatted version of name is used.

  • guidance (string): Optional.
    Help text or instructions for the field, assisting users in understanding what data to enter.

  • required (boolean): Optional.
    If true, the field must be filled before submission. Default: false.

  • readonly (boolean): Optional.
    If true, the field is read-only and cannot be edited by the user. Default: false.

  • hidden (boolean): Optional.
    If true, the field is hidden from the user interface. Default: false.

  • cardinality (string): Optional.
    Relationship cardinality. Options: oneToOne, oneToMany, manyToOne, manyToMany.

  • item_type (string): Optional.
    Type identifier for the entity.

  • fields (array): Optional.
    Nested field definitions within the entity.

  • pagesize (number): Optional.
    Number of items per page for pagination. Default: 10.

  • display_fields (array): Optional.
    Fields to display in summary view. Array of field names.

Examples

Simple Entity with Nested Fields:

- name: contact_info
  type: entity
  display_name: "Contact Information"
  guidance: "Enter your contact details"
  fields:
    - name: first_name
      type: string
      display_name: "First Name"
      required: true
    - name: last_name
      type: string
      display_name: "Last Name"
      required: true
    - name: email
      type: email_address
      display_name: "Email Address"
      required: true
    - name: phone
      type: string
      display_name: "Phone Number"
      required: false

One-to-Many Entity Relationship:

- name: items
  type: entity
  display_name: "Order Items"
  cardinality: "oneToMany"
  item_type: "order_item"
  fields:
    - name: product_name
      type: string
      display_name: "Product Name"
      required: true
    - name: quantity
      type: number
      display_name: "Quantity"
      required: true
      default_value: 1
    - name: unit_price
      type: number
      display_name: "Unit Price"
      precision: 2
      symbol: "$"
      required: true
  pagesize: 5
  display_fields: ["product_name", "quantity", "unit_price"]

Complex Entity with Multiple Field Types:

- name: vehicle_details
  type: entity
  display_name: "Vehicle Information"
  guidance: "Enter complete vehicle details"
  fields:
    - name: make
      type: string
      display_name: "Make"
      required: true
    - name: model
      type: string
      display_name: "Model"
      required: true
    - name: year
      type: number
      display_name: "Year"
      validation: "min:1900,max:2024"
      required: true
    - name: vin
      type: string
      display_name: "VIN"
      validation: "^[A-HJ-NPR-Z0-9]{17}$"
      required: true
    - name: is_insured
      type: boolean
      display_name: "Currently Insured"
      default_value: false
    - name: registration_date
      type: date
      display_name: "Registration Date"
      required: false

Usage Notes

  • Nested Fields:
    • Use the fields array to define the structure of nested data.
    • Each field in the array follows the same field definition format as top-level fields.
    • Nested fields can be of any supported field type.
  • Cardinality:
    • oneToOne: Single entity instance (default).
    • oneToMany: Multiple entity instances (e.g., list of items).
    • manyToOne: Many-to-one relationship.
    • manyToMany: Many-to-many relationship.
  • Item Type:
    • Use item_type to specify the type identifier for the entity.
    • Useful for categorizing and organizing entity data.
  • Pagination:
    • Use pagesize to control how many items are displayed per page.
    • Important for one-to-many relationships with many items.
  • Display Fields:
    • Use display_fields to specify which fields appear in summary views.
    • Useful for list displays and compact representations.
  • Validation:
    • Validation can be applied at both the entity level and individual field level.
    • Entity-level validation can check relationships between nested fields.
  • Use Cases:
    • Contact Information: Grouping name, address, phone, email.
    • Order Items: Product details, quantities, prices.
    • Vehicle Information: Make, model, year, VIN, insurance status.
    • Address Details: Street, city, state, zip code.
    • Document Metadata: Title, author, date, category.
  • Data Structure:
    • Entity fields create nested object structures in the data.
    • Useful for creating complex, hierarchical data models.
    • Supports both simple grouping and complex relationships.
  • User Experience:
    • Entity fields can be displayed as expandable sections or tabs.
    • Provide clear guidance on what information belongs in each entity.
    • Consider the complexity of nested fields for user input.
  • Performance Considerations:
    • Complex entities with many nested fields may impact form performance.
    • Consider pagination for large one-to-many relationships.
    • Optimize display fields for efficient data presentation.

By incorporating the entity field type into your schema, you can create complex, structured data models that group related information together, enhancing the organization and usability of your application.

Copyright © 2025 Caseblocks Limited.