Klamm Forms Template Schema (Version 1.0)

Forms JSON Schema

Version 1.0

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id": "https://klamm.social.gov.bc.ca/forms-schema.json",
    "title": "Forms Build Template",
    "description": "Schema for importing form definitions into the Kiln form builder.",
    "type": "object",
    "required": [
        "form_id",
        "title",
        "data"
    ],
    "properties": {
        "form_id": {
            "type": "string",
            "description": "A unique identifier for the form, used to find or create a Form record."
        },
        "title": {
            "type": "string",
            "description": "The title of the form."
        },
        "ministry_id": {
            "type": [
                "integer",
                "null"
            ],
            "description": "Optional: The ID of the ministry associated with the form."
        },
        "deployed_to": {
            "type": [
                "string",
                "null"
            ],
            "description": "Optional: The deployment target for this form version."
        },
        "dataSources": {
            "type": "array",
            "description": "Optional: List of data sources attached to this form version.",
            "items": {
                "type": "object",
                "required": [
                    "name"
                ],
                "properties": {
                    "name": {
                        "type": "string",
                        "description": "The name of the data source to attach."
                    }
                }
            }
        },
        "data": {
            "type": "object",
            "description": "The main content structure of the form.",
            "required": [
                "items"
            ],
            "properties": {
                "items": {
                    "type": "array",
                    "description": "A list of top-level form elements (containers, groups, or fields).",
                    "items": {
                        "oneOf": [
                            {
                                "$ref": "#/definitions/containerElement"
                            },
                            {
                                "$ref": "#/definitions/groupElement"
                            },
                            {
                                "$ref": "#/definitions/fieldElement"
                            }
                        ]
                    }
                }
            }
        }
    },
    "definitions": {
        "baseElementProperties": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "description": "A unique instance ID for the element. Can be 'element' + number or a custom ID."
                },
                "conditions": {
                    "type": "array",
                    "description": "Optional: Conditions that affect the element's visibility or other properties.",
                    "items": {
                        "type": "object",
                        "required": [
                            "type",
                            "value"
                        ],
                        "properties": {
                            "type": {
                                "type": "string",
                                "description": "Type of condition (e.g., 'visibility')."
                            },
                            "value": {
                                "type": [
                                    "string",
                                    "boolean",
                                    "number",
                                    "null"
                                ],
                                "description": "The value associated with the condition."
                            }
                        }
                    }
                },
                "webStyles": {
                    "type": "object",
                    "description": "Optional: Key-value pairs for web-specific CSS styles.",
                    "patternProperties": {
                        "^[a-zA-Z-]+$": {
                            "type": "string"
                        }
                    },
                    "additionalProperties": false
                },
                "pdfStyles": {
                    "type": "object",
                    "description": "Optional: Key-value pairs for PDF-specific CSS styles.",
                    "patternProperties": {
                        "^[a-zA-Z-]+$": {
                            "type": "string"
                        }
                    },
                    "additionalProperties": false
                }
            }
        },
        "containerElement": {
            "type": "object",
            "description": "A container element for grouping other form elements.",
            "allOf": [
                {
                    "$ref": "#/definitions/baseElementProperties"
                }
            ],
            "required": [
                "type",
                "id",
                "containerItems"
            ],
            "properties": {
                "type": {
                    "type": "string",
                    "enum": [
                        "container"
                    ]
                },
                "containerItems": {
                    "type": "array",
                    "description": "A list of nested form elements (groups or fields) within this container.",
                    "items": {
                        "oneOf": [
                            {
                                "$ref": "#/definitions/groupElement"
                            },
                            {
                                "$ref": "#/definitions/fieldElement"
                            }
                        ]
                    }
                }
            }
        },
        "groupElement": {
            "type": "object",
            "description": "A field group element, potentially repeatable.",
            "allOf": [
                {
                    "$ref": "#/definitions/baseElementProperties"
                }
            ],
            "required": [
                "type",
                "id",
                "codeContext",
                "groupItems"
            ],
            "properties": {
                "type": {
                    "type": "string",
                    "enum": [
                        "group"
                    ]
                },
                "codeContext": {
                    "type": "object",
                    "required": [
                        "name"
                    ],
                    "properties": {
                        "name": {
                            "type": "string",
                            "description": "The programmatic name of the field group (e.g., 'generic_group')."
                        }
                    }
                },
                "label": {
                    "type": [
                        "string",
                        "null"
                    ],
                    "description": "Optional: Custom label for the group. If null, default is used."
                },
                "repeater": {
                    "type": "boolean",
                    "description": "Optional: True if this group can be repeated (default: false)."
                },
                "databindings": {
                    "type": "object",
                    "description": "Optional: Data binding information for the group.",
                    "properties": {
                        "source": {
                            "type": [
                                "string",
                                "null"
                            ]
                        },
                        "path": {
                            "type": [
                                "string",
                                "null"
                            ]
                        }
                    }
                },
                "repeaterItemLabel": {
                    "type": [
                        "string",
                        "null"
                    ],
                    "description": "Optional: Custom label for individual items in a repeater group."
                },
                "groupItems": {
                    "type": "array",
                    "description": "A list of items within the group. Expected to contain a single object with 'fields' array.",
                    "minItems": 1,
                    "maxItems": 1,
                    "items": {
                        "type": "object",
                        "required": [
                            "fields"
                        ],
                        "properties": {
                            "fields": {
                                "type": "array",
                                "description": "A list of fields within this group.",
                                "items": {
                                    "$ref": "#/definitions/fieldElement"
                                }
                            }
                        }
                    }
                }
            }
        },
        "fieldElement": {
            "type": "object",
            "description": "A single form field element.",
            "allOf": [
                {
                    "$ref": "#/definitions/baseElementProperties"
                }
            ],
            "required": [
                "type",
                "id",
                "codeContext"
            ],
            "properties": {
                "type": {
                    "type": "string",
                    "description": "The type of the field (e.g., 'text-input', 'number-input', 'select').",
                    "enum": [
                        "text-input",
                        "number-input",
                        "select",
                        "checkbox",
                        "date",
                        "text-info"
                    ]
                },
                "codeContext": {
                    "type": "object",
                    "required": [
                        "name"
                    ],
                    "properties": {
                        "name": {
                            "type": "string",
                            "description": "The programmatic name of the field (e.g., 'generic_text_input')."
                        }
                    }
                },
                "label": {
                    "type": [
                        "string",
                        "null"
                    ],
                    "description": "Optional: Custom label for the field. If null, default is used."
                },
                "databindings": {
                    "type": "object",
                    "description": "Optional: Data binding information for the field.",
                    "properties": {
                        "source": {
                            "type": [
                                "string",
                                "null"
                            ]
                        },
                        "path": {
                            "type": [
                                "string",
                                "null"
                            ]
                        }
                    }
                },
                "mask": {
                    "type": [
                        "string",
                        "null"
                    ],
                    "description": "Optional: Input mask for the field."
                },
                "helperText": {
                    "type": [
                        "string",
                        "null"
                    ],
                    "description": "Optional: Helper text or tooltip for the field."
                },
                "value": {
                    "type": [
                        "string",
                        "number",
                        "boolean",
                        "null"
                    ],
                    "description": "Optional: Default or initial value for the field."
                },
                "validation": {
                    "type": "array",
                    "description": "Optional: Validation rules for the field.",
                    "items": {
                        "type": "object",
                        "required": [
                            "type",
                            "value",
                            "errorMessage"
                        ],
                        "properties": {
                            "type": {
                                "type": "string",
                                "description": "Type of validation (e.g., 'required', 'min', 'max')."
                            },
                            "value": {
                                "type": [
                                    "string",
                                    "number",
                                    "boolean",
                                    "null"
                                ],
                                "description": "The value for the validation rule."
                            },
                            "errorMessage": {
                                "type": "string",
                                "description": "Error message for this validation rule."
                            }
                        }
                    }
                },
                "listItems": {
                    "type": "array",
                    "description": "Optional: For select/dropdown fields, the list of options.",
                    "items": {
                        "type": "object",
                        "required": [
                            "name",
                            "text",
                            "value"
                        ],
                        "properties": {
                            "name": {
                                "type": "string",
                                "description": "Unique programmatic name for the option."
                            },
                            "text": {
                                "type": "string",
                                "description": "Display text for the option."
                            },
                            "value": {
                                "type": "string",
                                "description": "The actual value of the option."
                            }
                        }
                    }
                }
            }
        }
    }
}

Reference: JSON Schema Specification