Introduction

Schemas in Caseblocks define the structure of your data models. They are defined using YAML and consist of various field types organized into fieldsets. This documentation will guide you through creating and managing these schemas, detailing each field type and the options available to customize them to fit your application’s needs.

Field Types

Caseblocks supports various field types, each designed to handle specific kinds of data. Below are some of the available field types and their implementation details.

String

Description: Represents any alphanumeric value.

YAML Definition:

- name: field_name
  type: string
  display_name: "Display Name"          # Optional
  guidance: "Guidance text"            # Optional
  format: "Format string"              # Optional
  readonly: true                       # Optional
  hidden: true                         # Optional
  required: true                       # Optional
  internal: false                      # Required
  display: "Display option"             # Optional
  symbol: "Symbol"                      # Optional
  cardinality: "Cardinality"            # Optional
  default_value: "Default Value"        # Optional
  validation: "Regex or rule"           # Optional
  validation_message: "Error message"   # Optional
  # Additional attributes as needed

Example:

- name: title
  type: string
  display_name: "Title"
  required: true

Number

Description: Handles integer or float values.

YAML Definition:

- name: field_name
  type: number
  display_name: "Display Name"          # Optional
  guidance: "Guidance text"            # Optional
  format: "Format string"              # Optional
  readonly: true                       # Optional
  hidden: true                         # Optional
  required: true                       # Optional
  internal: false                      # Required
  display: "Display option"             # Optional
  symbol: "Symbol"                      # Optional
  cardinality: "Cardinality"            # Optional
  default_value: 0                      # Optional
  validation: "Validation rule"         # Optional
  validation_message: "Error message"   # Optional
  precision: 2                          # Optional
  # Additional attributes as needed

Example:

- name: customer_ref
  type: number
  sequence: true
  display_name: "Customer Reference"

Field Attributes

Each field in a schema can have various attributes that define its behavior and presentation. Below is a list of available attributes:

  • name (string): The unique identifier for the field. (Required)
  • type (FieldType): The type of the field (e.g., string, number). (Required)
  • display_name (string): The name displayed in the UI.
  • guidance (string): Help text or instructions for the field.
  • format (string): Specifies the format of the field (e.g., date formats).
  • readonly (boolean): If true, the field is read-only.
  • hidden (boolean): If true, the field is hidden from the UI.
  • required (boolean): If true, the field must be filled.
  • internal (boolean): Indicates if the field is for internal use. (Required)
  • display (string): Display options or settings.
  • symbol (string): Symbol associated with the field (e.g., currency symbol).
  • cardinality (string): Defines the relationship cardinality (e.g., oneToMany).
  • item_type (string): Specifies the type of items in a collection field.
  • pagesize (number): Number of items per page in UI components.
  • validation (string): Validation rules (e.g., regex).
  • validation_message (string): Message displayed on validation failure.
  • default_value (any): The default value of the field.
  • sequence (boolean): Indicates if the field is part of a sequence.
  • options (any[]): List of options for selection fields.
  • display_fields (string[]): Fields to display in related entities.
  • relation (string): Name of the relation.
  • uif (string): UI framework specific settings.
  • cascading_parent_field (string): Field that acts as a parent in cascading relations.
  • dependent_fields (string[]): Fields that depend on this field.
  • fields (Field[]): Nested fields for complex types.
  • parentField (Field): Parent field in nested structures.
  • fieldset (Fieldset): The fieldset this field belongs to.
  • time_format (string): Format of the time component.
  • input_format (string): Format for input data.
  • input_timezone (string): Timezone for input data.
  • export_format (string): Format for exported data.
  • export_timezone (string): Timezone for exported data.
  • display_toggle_field (string): Field that toggles the display of this field.
  • precision (number): Number of decimal places for number fields.

Fieldsets

Fields in a schema are organized into fieldsets, which are logical groupings that help manage and display related fields together. Each fieldset has a unique name and contains a list of fields.

YAML Structure:

fieldsets:
  - name: fieldset_name
    fields:
      - name: field1
        type: field_type
        # Additional attributes
      - name: field2
        type: field_type
        # Additional attributes

Example:

fieldsets:
  - name: details
    fields: 
      - name: title
        type: string
  - name: internal_references
    fields: 
      - name: customer_ref
        type: number
        sequence: true

Example Schemas

Below are some pre-configured example schemas to illustrate how schemas are defined in YAML.

Customer Schema 

name: "Customer"
fieldsets:
  - name: details
    fields: 
      - name: title
        type: string
  - name: internal_references
    fields: 
      - name: customer_ref
        type: number
        sequence: true

Claim Schema 

name: "Claim"
fieldsets:
  - name: summary
    fields: 
      - name: title
        type: string
        required: true
  - name: internal_references
    fields:
      - name: claim_ref
        type: number
        sequence: true

Sales Order Schema 

name: "Sales Order"
fieldsets:
  - name: order_header
    fields: 
      - name: title
        type: string
      - name: order_source
        type: string
      - name: order_date
        type: date
  - name: order_line_items
    fields:
      - name: items
        type: entity
        cardinality: oneToMany
        item_type: item
        fields: 
          - name: make
            type: string
          - name: model
            type: string
          - name: count
            type: number   
            default_value: 1
      - name: subtotal
        type: number
        default_value: 0
  - name: order_summary
    fields: 
      - name: total
        type: number
        default_value: 0
  - name: internal_references
    fields: 
      - name: customer_ref
        type: number

Creating a New Schema

To create a new schema in Caseblocks, follow these steps:

  1. Define the Schema Name: Provide a unique name for your schema.
  2. Organize Fieldsets: Determine logical groupings for your fields and define each fieldset with a unique name.
  3. Define Fields: Within each fieldset, list out the fields with their respective types and attributes.
  4. Specify Attributes: For each field, set the necessary attributes to control behavior and presentation.
  5. Validate YAML: Ensure your YAML syntax is correct to prevent errors during schema deployment.

Step-by-Step Example

Let’s create a Product schema with relevant fieldsets and fields.

name: "Product"
fieldsets:
  - name: product_details
    fields:
      - name: name
        type: string
        display_name: "Product Name"
        required: true
      - name: description
        type: string
        display_name: "Description"
        guidance: "Provide a detailed description of the product."
  - name: pricing
    fields:
      - name: price
        type: number
        display_name: "Price"
        required: true
        precision: 2
      - name: currency
        type: string
        display_name: "Currency"
        default_value: "USD"
  - name: relationships
    fields:
      - name: category
        type: relation
        related_to: "Category"
        related_on: "category_id"
        display_name: "Category"
  - name: timestamps
    fields:
      - name: created_at
        type: date
        display_name: "Created At"
        readonly: true
      - name: updated_at
        type: date
        display_name: "Updated At"
        readonly: true

Best Practices

  • Consistent Naming: Use clear and consistent naming conventions for schemas, fieldsets, and fields to enhance readability and maintainability.
  • Modular Fieldsets: Group related fields into fieldsets to organize the schema logically.
  • Default Values: Where applicable, set default values to ensure data consistency.
  • Validation Rules: Implement validation rules to maintain data integrity and provide meaningful error messages.
  • Documentation: Document each field and its purpose using the guidance attribute to assist other developers and users.
  • Version Control: Manage schema changes using version control systems to track modifications over time.

Conclusion

Managing schemas in Caseblocks involves defining structured YAML configurations that specify the data models used within your application. By understanding the available field types, attributes, and best practices, you can create robust and maintainable schemas that effectively support your application’s data requirements.

For further assistance or advanced configurations, please refer to the Caseblocks API Reference or contact the Caseblocks support team.

Additional Notes

  • Extensibility: The documentation can be extended to cover more advanced topics, such as nested entities, custom validations, and integrating with other Caseblocks features.
  • Examples and Code Snippets: Including more examples and code snippets can help developers understand complex configurations.
  • Visual Aids: Diagrams or screenshots of the UI can provide visual context for how schemas and fieldsets appear within Caseblocks.

If you have specific code for the display of each field or additional requirements, feel free to provide them, and the documentation can be further tailored to include those details.

Copyright © 2025 Caseblocks Limited.