Document Field Type

Description:
The document field type is used to capture file uploads and document attachments. It provides a user-friendly interface for uploading files with support for multiple file types, size limits, and validation. This field type is essential for applications that need to collect documents, images, or other file attachments from users.

Elasticsearch Mapping: object with document properties

YAML Definition 

- name: attachments
  type: document
  display: document
  display_name: "Attachments"
  default_value: null
  required: false
  readonly: false
  hidden: false
  guidance: "Upload relevant documents"
  allow_select_multiple: true
  allowed_extensions: ["pdf", "doc", "jpg", "png"]
  max_file_size: "10MB"
  validation: "file_type"
  validation_message: "Please upload valid file types"

Attributes

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

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

  • display (string): Required.
    Must be set to document for document display.

  • 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 files to upload.

  • required (boolean): Optional.
    If true, at least one file must be uploaded 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.

  • default_value (array): Optional.
    The default files displayed when the form is first loaded.

  • allow_select_multiple (boolean): Optional.
    Whether to allow multiple file selection. Default: false.

  • allowed_extensions (array): Optional.
    Array of allowed file extensions (e.g., [“pdf”, “doc”, “jpg”]).

  • max_file_size (string): Optional.
    Maximum file size limit (e.g., “10MB”, “5MB”).

  • validation (string): Optional.
    Validation rules for the document field.

  • validation_message (string): Optional.
    Custom validation error message to display when validation fails.

Examples

Basic Document Field:

- name: attachments
  type: document
  display: document
  display_name: "Attachments"
  required: false
  guidance: "Upload relevant documents"
  allow_select_multiple: true
  allowed_extensions: ["pdf", "doc", "docx", "jpg", "png"]
  max_file_size: "10MB"

Required Document Field:

- name: contract_document
  type: document
  display: document
  display_name: "Contract Document"
  required: true
  guidance: "Upload the signed contract document"
  allow_select_multiple: false
  allowed_extensions: ["pdf"]
  max_file_size: "5MB"
  validation: "file_type"
  validation_message: "Please upload a valid PDF contract document"

Image Upload Field:

- name: profile_photo
  type: document
  display: document
  display_name: "Profile Photo"
  required: false
  guidance: "Upload a profile photo (JPG or PNG format)"
  allow_select_multiple: false
  allowed_extensions: ["jpg", "jpeg", "png"]
  max_file_size: "2MB"

Multiple Document Field:

- name: supporting_documents
  type: document
  display: document
  display_name: "Supporting Documents"
  required: true
  guidance: "Upload all supporting documents for your application"
  allow_select_multiple: true
  allowed_extensions: ["pdf", "doc", "docx", "jpg", "png", "txt"]
  max_file_size: "20MB"

Usage Notes

  • File Upload Interface:
    • The document field provides a drag-and-drop or click-to-upload interface.
    • Supports both single and multiple file uploads.
    • Shows upload progress and validation feedback.
  • File Type Restrictions:
    • Use allowed_extensions to restrict file types.
    • Common extensions include:
      • Documents: ["pdf", "doc", "docx", "txt", "rtf"]
      • Images: ["jpg", "jpeg", "png", "gif", "bmp"]
      • Spreadsheets: ["xls", "xlsx", "csv"]
      • Presentations: ["ppt", "pptx"]
  • File Size Limits:
    • Use max_file_size to set upload size limits.
    • Common size formats: "1MB", "5MB", "10MB", "50MB".
    • Consider server and storage limitations when setting limits.
  • Multiple File Selection:
    • Set allow_select_multiple: true to allow multiple file uploads.
    • Useful for collecting multiple documents or attachments.
    • Files are stored as an array of file objects.
  • Validation:
    • Use validation: "file_type" to enable file type validation.
    • Validates file extensions against allowed_extensions.
    • Checks file size against max_file_size.
  • Required Fields:
    • Set required: true for essential document uploads.
    • Ensures that necessary documents are provided.
  • Readonly Fields:
    • Use readonly for displaying uploaded documents that shouldn’t be changed.
    • Common for approved or processed documents.
  • Use Cases:
    • Contract Management: Uploading signed contracts and agreements.
    • Application Forms: Supporting documents for applications.
    • Profile Management: Profile photos and personal documents.
    • Project Management: Project files, specifications, and deliverables.
    • Support Tickets: Screenshots and supporting documentation.
  • Data Structure:
    • Document data is stored as file objects with metadata.
    • Includes file name, size, type, and upload timestamp.
    • Files are typically stored in cloud storage or file system.
  • Security Considerations:
    • Validate file types to prevent malicious uploads.
    • Implement virus scanning for uploaded files.
    • Set appropriate file size limits to prevent abuse.
    • Consider file storage security and access controls.
  • Performance Considerations:
    • Large file uploads may impact form performance.
    • Consider implementing chunked uploads for large files.
    • Optimize file storage and retrieval for better performance.
  • Accessibility:
    • Ensure that file upload interfaces are keyboard accessible.
    • Provide clear labels and instructions for file uploads.
    • Support screen readers for upload status and validation messages.

By incorporating the document field type into your schema, you enable users to upload and manage file attachments, enhancing the data collection capabilities of your application.

Copyright © 2025 Caseblocks Limited.