Validation Rules

The CMS validates component bundles during upload to ensure quality, security, and compatibility. This guide covers all validation rules and how to fix common errors.

When you upload a component bundle, the CMS performs these validation steps:

1. Zip file validation: Check file integrity and size
2. File presence validation: Verify required files exist
3. JSON validation: Parse and validate JSON files
4. Schema validation: Check JSON conforms to expected schemas
5. Marker cross-reference: Verify HTML markers reference dialog fields
6. HTML sanitization: Remove dangerous HTML patterns
7. File size validation: Check individual file sizes

If any validation fails, the entire upload is rejected (all-or-nothing).

Error: Uploaded file is not a valid zip or exceeds 10 MB

Causes:

• File is corrupted
• File is not a zip archive
• Zip file exceeds 10 MB

Solutions:

• Verify the file is a valid zip archive
• Reduce the number of components in the zip
• Compress images or remove unnecessary files
• Split into multiple smaller uploads

Error: Zip entry contains path traversal sequence

Causes:

• Zip contains entries with ../ in the path
• Malicious or improperly created zip file

Solutions:

• Recreate the zip without parent directory references
• Ensure all paths are relative to the zip root
• Use standard zip tools (avoid manual path manipulation)

Error: Component subfolder is missing required files

Causes:

• Missing details.json
• Missing dialog.json
• Missing component.html
• Missing component.css

Solutions:

• Add all required files to the component folder
• Check file names are exactly correct (case-sensitive)
• Verify files are in the correct location

Example structure:

Error: details.json is malformed or missing required fields

Causes:

• Invalid JSON syntax
• Missing required fields (name, description, purpose, optionsDescription)
• Empty required fields

Solutions:

• Validate JSON syntax using a JSON validator
• Ensure all required fields are present
• Ensure all required fields have non-empty string values

Valid example:

Error: dialog.json is not valid JSON

Causes:

• Syntax errors (missing commas, brackets, quotes)
• Trailing commas
• Invalid escape sequences

Solutions:

• Use a JSON validator to find syntax errors
• Check for missing or extra commas
• Verify all strings are properly quoted
• Remove trailing commas

Common mistakes:

Error: dialog.json does not conform to Dialog Schema

Causes:

• Missing schemaVersion
• Missing fields or fieldGroups
• Invalid field type
• Missing required field properties (type, name, label)
• Invalid field name (contains invalid characters)
• select field missing options
• Invalid conditional (showIf) reference

Solutions:

• Add schemaVersion: "1.0"
• Ensure fields or fieldGroups is present
• Use valid field types: text, textarea, richtext, number, boolean, select, asset, icon, image, page-link
• Add all required properties to each field
• Use valid field names (alphanumeric and underscores only, start with letter)
• Add options array to select fields
• Verify showIf references an existing field

Valid field:

Error: component.html references a field not in dialog.json

Causes:

• Marker {{fieldName}} references undefined field
• Typo in marker name
• Field was removed from dialog but marker remains in HTML

Solutions:

• Add the missing field to dialog.json
• Fix the typo in the marker name
• Remove the marker from component.html

Example:

dialog.json:

component.html:

Fix: Add description field to dialog or remove the marker.

The CMS automatically sanitizes HTML to remove dangerous patterns. These patterns are removed during upload:

Removed: <script> tags and their content

Removed: javascript: protocol in URLs

Removed: Inline event handlers (on* attributes)

Error: Individual component file exceeds 512 KB

Causes:

• details.json exceeds 512 KB
• dialog.json exceeds 512 KB
• component.html exceeds 512 KB
• component.css exceeds 512 KB
• component.js exceeds 512 KB
• editor.js exceeds 512 KB
• variables.json exceeds 512 KB

Solutions:

• Reduce file size by removing unnecessary content
• Simplify complex HTML or CSS
• Split large components into smaller components
• Optimize and minify CSS

File size limits:

• Individual file: 512 KB maximum
• Total zip: 10 MB maximum

Error: variables.json is malformed or missing required fields

Causes:

• Invalid JSON syntax
• Missing required fields (name, category, description, defaultValue)
• Invalid category value
• Variable name doesn't start with --

Solutions:

• Validate JSON syntax
• Ensure all required fields are present
• Use valid category: color, spacing, typography, layout, border, shadow, other
• Ensure variable names start with --

Valid example:

Error: File MIME type does not match expected type

Causes:

• File extension doesn't match content
• File is corrupted

Solutions:

• Ensure files have correct extensions
• Verify file content matches extension
• Recreate files if corrupted

Expected MIME types:

• .json: application/json
• .html: text/html
• .css: text/css
• .js: text/javascript or application/javascript

Cause: Field names cannot contain hyphens

Solution: Use underscores or camelCase:

or

Cause: select field is missing options array

Solution: Add options:

Cause: Conditional field references a field that doesn't exist

Solution: Ensure the referenced field exists:

Cause: image field is missing proper default value

Solution: Add default value object:

1. Validate JSON: Use a JSON validator for all JSON files
2. Check file names: Verify exact file names (case-sensitive)
3. Test locally: Open HTML and CSS in a browser
4. Check markers: Ensure all markers reference dialog fields
5. Review file sizes: Check individual file sizes

1. Upload to test site: Use a test site for initial uploads
2. Test all fields: Try all field combinations
3. Test conditionals: Verify conditional fields show/hide correctly
4. Test validation: Try invalid inputs to verify validation works
5. Test responsive: Check on mobile, tablet, and desktop

1. Read error messages: Error messages indicate the specific issue
2. Check line numbers: JSON errors often include line numbers
3. Validate incrementally: Fix one error at a time
4. Use tools: Use JSON validators and HTML validators
5. Compare with examples: Compare your files with working examples

When validation fails, the API returns HTTP 400 with detailed errors:

Response structure:

• error: Human-readable error message
• code: Machine-readable error code
• components: Array of per-component results
  • name: Component folder name
  • valid: Whether the component passed validation
  • errors: Array of validation errors for this component

• Component Structure — Required files and structure
• Dialog Schema — Dialog schema requirements
• Templating Syntax — Valid marker syntax
• Component Example — Working example