Forms Schema Specification

Reference: JSON Schema Specification

{
    "$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')."
                },
                "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." }
                        }
                    }
                }
            }
        }
    }
}