ADR-032: YAML Schema Versioning for iDempiere AD Elements

Status

Proposed

Context

The CLI generates YAML definitions for iDempiere Application Dictionary elements (tables, columns, windows, tabs). The AD metadata schema changes between iDempiere versions, so our YAML schema must be version-aware.

Decision

Create a versioned YAML schema that:

  1. Includes targetVersion field to specify minimum iDempiere version
  2. Documents which fields are available in which versions
  3. Validates YAML against the appropriate schema based on target version

YAML Schema v1.0

Base Schema (All Versions)

version: "1.0"
kind: TableDefinition | WindowDefinition | ProcessDefinition
targetVersion: "10" | "11" | "12" | "13"  # Minimum iDempiere version

metadata:
  name: string          # Technical name (XX_MyTable)
  displayName: string   # Display name (max 60 chars)
  description: string   # One-line description (max 255 chars)
  help: string          # Detailed help (max 2000 chars)
  entityType: "U" | "D" | "C"  # U=User, D=Dictionary, C=Customization

AD_Table Fields by Version

Field v10 v11 v12 v13 Type Description
tableName Y Y Y Y string(40) Technical table name
name Y Y Y Y string(60) Display name
description Y Y Y Y string(255) Description
help Y Y Y Y string(2000) Help text
accessLevel Y Y Y Y enum 1=Org, 2=Client, 3=Client+Org, 4=System, 6=Sys+Client, 7=All
entityType Y Y Y Y string(40) Entity type
isView Y Y Y Y boolean Is database view
isHighVolume Y Y Y Y boolean High volume table
isChangeLog Y Y Y Y boolean Enable change audit
isDeleteable Y Y Y Y boolean Allow record deletion
isSecurityEnabled Y Y Y Y boolean Row-level security
replicationType Y Y Y Y enum L=Local, M=Merge, R=Reference
isCentrallyMaintained Y Y Y Y boolean Centrally maintained
ad_table_uu - Y Y Y uuid Table UUID (v11+)
isPartition - - Y Y boolean Table partitioning (v12+)
isShowInDrillOptions - - Y Y boolean Show in drill (v12+)

AD_Column Fields by Version

Field v10 v11 v12 v13 Type Description
columnName Y Y Y Y string(63) Technical column name
name Y Y Y Y string(60) Display name
description Y Y Y Y string(255) Description
help Y Y Y Y string(2000) Help text
ad_reference_id Y Y Y Y int Column type reference
ad_reference_value_id Y Y Y Y int List/Table reference
fieldLength Y Y Y Y int Max length
isMandatory Y Y Y Y boolean Required field
isKey Y Y Y Y boolean Primary key
isParent Y Y Y Y boolean Parent link
isIdentifier Y Y Y Y boolean Show in lookups
isSelectionColumn Y Y Y Y boolean Search column
isTranslated Y Y Y Y boolean Translatable
isUpdateable Y Y Y Y boolean Can be updated
isEncrypted Y Y Y Y boolean Encrypted storage
defaultValue Y Y Y Y string(2000) Default value
callout Y Y Y Y string(255) Callout class
readOnlyLogic Y Y Y Y string(2000) Read-only logic
mandatoryLogic Y Y Y Y string(2000) Mandatory logic
ad_column_uu - Y Y Y uuid Column UUID (v11+)
isPartitionKey - - Y Y boolean Partition key (v12+)
partitioningMethod - - Y Y string(2) RANGE, LIST (v12+)

AD_Reference Types (Column Types)

ID Name YAML Type Description
10 String String Text field
11 Integer Integer Whole numbers
12 Amount Amount Money values
13 ID ID Primary key
14 Text Text Multi-line text
15 Date Date Date only
16 Date+Time DateTime Date and time
17 List List Dropdown
18 Table Table FK with validation
19 Table Direct TableDirect Direct FK
20 Yes-No YesNo Boolean
22 Number Number Decimal
29 Quantity Quantity Qty values
30 Search Search Search dialog
36 Text Long TextLong Very long text
40 URL URL Web URL

v11+ UUID Types:

ID Name YAML Type Description
200242 UUID UUID UUID column
200243 Table (UU) TableUU FK to UUID
200244 TableDir (UU) TableDirectUU Direct FK to UUID
200245 Search (UU) SearchUU Search by UUID
200246 Record UUID RecordUUID Record_UU reference

AD_Window Fields by Version

Field v10 v11 v12 v13 Type Description
name Y Y Y Y string(60) Window name
description Y Y Y Y string(255) Description
help Y Y Y Y string(2000) Help text
windowType Y Y Y Y enum M=Maintain, T=Transaction, Q=Query
isSOTrx Y Y Y Y boolean Sales transaction
isDefault Y Y Y Y boolean Default window
entityType Y Y Y Y string(40) Entity type
isBetaFunctionality Y Y Y Y boolean Beta feature
titleLogic - Y Y Y string(255) Dynamic title (v11+)
predefinedContextVariables - - Y Y string(4000) Context vars (v12+)

AD_Tab Fields by Version

Field v10 v11 v12 v13 Type Description
name Y Y Y Y string(60) Tab name
description Y Y Y Y string(255) Description
help Y Y Y Y string(2000) Help text
seqNo Y Y Y Y int Tab order
tabLevel Y Y Y Y int 0=Header, 1=Line, 2+
isReadOnly Y Y Y Y boolean Read-only tab
isSingleRow Y Y Y Y boolean Single record view
isInfoTab Y Y Y Y boolean Info tab
isTranslationTab Y Y Y Y boolean Translation tab
whereClause Y Y Y Y string(2000) Filter SQL
orderByClause Y Y Y Y string(2000) Sort SQL
displayLogic Y Y Y Y string(2000) Display logic
readOnlyLogic Y Y Y Y string(2000) Read-only logic
isInsertRecord Y Y Y Y boolean Allow insert
isAdvancedTab Y Y Y Y boolean Advanced tab
hasTree Y Y Y Y boolean Tree view
maxQueryRecords - Y Y Y int Max query rows (v11+)
isLookupOnlySelection - Y Y Y boolean Lookup only (v11+)
isAllowAdvancedLookup - Y Y Y boolean Advanced lookup (v11+)
ad_TabType - - Y Y string(40) Tab type (v12+)
isHighVolume - - - Y boolean High volume (v13+)

Example YAML

Full Table Definition (v12+)

version: "1.0"
kind: TableDefinition
targetVersion: "12"

metadata:
  name: XX_CustomerComplaint
  displayName: Customer Complaint
  description: Tracks customer complaints and resolution status
  help: |
    This table stores customer complaint records including the issue details,
    priority level, assigned handler, and resolution information.
  entityType: U

spec:
  table:
    accessLevel: "3"  # Client+Organization
    isHighVolume: false
    isChangeLog: true
    isDeleteable: true
    isSecurityEnabled: false

  templates:
    - audit       # AD_Client_ID, AD_Org_ID, Created, Updated, IsActive
    - uuid        # XX_CustomerComplaint_UU

  columns:
    - name: DocumentNo
      type: String
      length: 30
      mandatory: true
      identifier: true
      description: Unique complaint reference number

    - name: C_BPartner_ID
      type: Search
      reference: C_BPartner
      mandatory: true
      description: Customer who filed the complaint

    - name: DateReceived
      type: Date
      mandatory: true
      default: "@#Date@"
      description: Date complaint was received

    - name: Priority
      type: List
      reference: XX_ComplaintPriority  # Custom reference list
      mandatory: true
      default: "M"
      description: Complaint priority level

    - name: Status
      type: List
      reference: XX_ComplaintStatus
      mandatory: true
      default: "O"  # Open
      description: Current complaint status

    - name: Description
      type: Text
      mandatory: true
      description: Detailed complaint description

    - name: Resolution
      type: Text
      mandatory: false
      description: Resolution details

    - name: DateResolved
      type: Date
      mandatory: false
      description: Date complaint was resolved

    - name: AD_User_ID
      type: TableDirect
      mandatory: false
      description: User assigned to handle complaint

  window:
    name: Customer Complaints
    description: Manage customer complaints
    windowType: M  # Maintain
    isSOTrx: true

    tabs:
      - name: Complaint
        seqNo: 10
        tabLevel: 0
        isSingleRow: true
        orderByClause: DateReceived DESC

Minimal Table Definition (v10 compatible)

version: "1.0"
kind: TableDefinition
targetVersion: "10"

metadata:
  name: XX_SimpleLog
  displayName: Simple Log
  description: Simple logging table
  entityType: U

spec:
  table:
    accessLevel: "3"

  templates:
    - audit

  columns:
    - name: LogMessage
      type: String
      length: 255
      mandatory: true

Validation Rules

  1. Version Check: Reject fields not available in targetVersion
  2. Required Fields: Validate all mandatory fields present
  3. Reference Validation: Verify referenced tables/lists exist
  4. Naming Convention: Enforce XX_ prefix for custom tables
  5. Column Types: Map YAML types to AD_Reference_ID

Implementation

The CLI will:

  1. Parse YAML and extract targetVersion
  2. Load appropriate schema for that version
  3. Validate YAML against schema
  4. Generate warnings for deprecated fields
  5. Output validated YAML or error report

Sources

Path: /docs/developers/architecture/idempiere-hub/032-yaml-schema-versioning