Introduction
iXML is an XML-based server-side language used by ZeyOS for services, workflows, data orchestration, and integration logic. It is the primary orchestration layer for ZeyOS applications, responsible for handling HTTP request/response cycles, database interactions, file processing, external API communication, and business rule enforcement. If you are new to ZeyOS customization, iXML is the first language to learn.
Unlike general-purpose programming languages, iXML is purpose-built for the ZeyOS runtime environment. Every iXML document is valid XML, which means it inherits XML's strict syntactic rules — proper nesting, mandatory closing tags, attribute quoting, and entity escaping. This design decision allows ZeyOS to parse iXML documents with standard XML parsers and provides IDE support through DTD and XSD schemas. The tradeoff is that certain characters common in programming (such as < and >) must be entity-escaped when they appear inside attribute values.
iXML follows a substitution-based evaluation model rather than the expression-based evaluation found in most mainstream languages. Variables are referenced through dollar-sign substitution ($variableName), and values flow through statements via a mechanism called result propagation. Understanding these two concepts — substitution and propagation — is essential before working with any iXML command.
What iXML is used for
In a typical ZeyOS application, iXML code lives in three directories within the application structure. Each directory serves a different purpose, but all use the same iXML language:
services/— API route handlers (remotecall endpoints), scheduled jobs (timing services), and entity lifecycle hooks (before/after modification triggers). Services are the entry points for all application logic.resources/— Reusable domain logic, shared templates, helper functions, and configuration modules. Resources are included by services and other resources using the<include>command.weblets/— Embedded UI components that render within the ZeyOS interface. Weblets generate HTML output with embedded data from the ZeyOS platform.
In practical terms, iXML typically handles:
- Receiving and parsing incoming HTTP requests (JSON, form data, XML payloads)
- Validating input against business rules
- Orchestrating database reads and writes, often within transactions
- Calling external REST and SOAP APIs
- Generating structured responses (JSON, HTML, PDF, CSV)
- Managing error conditions and returning consistent error envelopes
See also
- Syntax Essentials — variables, strings, control flow, and the commands you use in every service
- Reusability and OOP — functions, macros, classes, and includes for structuring larger codebases
Core definitions
These definitions form the conceptual baseline used throughout the iXML reference and this guide. Every term below has a precise meaning that the language runtime enforces.
Terminology
The iXML language specification distinguishes between the structural components of an iXML document and their semantic roles:
| Term | Meaning |
|---|---|
| Element | Simple XML element — a single tag with attributes and optional content |
| Structure | Compound XML structure containing one or more child elements with their own semantics |
| Operation | The semantic definition of an element — what an element does when it executes |
| Construct | The semantic definition of a structure — what a compound structure does, including the behavior of its children |
| Statement | An executable instance of an operation or construct — the concrete occurrence in your code |
| Code | A series of statements that execute in sequence |
The distinction between operation and construct determines whether an iXML tag stands alone or contains child elements with their own semantics. For example, <set> is an operation — it assigns a value and has no semantic children. In contrast, <if> is a construct — it can contain <elseif>, <elseis>, and <else> children, each with their own execution rules.
Occurrences
Child elements within a construct are governed by occurrence rules that specify how many times a child element may appear:
| Occurrence | Meaning |
|---|---|
single | The element may appear at most once. If it appears more than once, the behavior is undefined. |
multiple | The element may appear any number of times, including not at all. |
Input types
Every attribute in the iXML reference declares an input type that governs how the attribute value is interpreted at runtime. When you write an attribute value in your iXML code, the runtime does not treat all values as plain strings — instead, it processes each value according to the declared input type of that attribute.
| Type | Meaning |
|---|---|
var | String referencing a variable (name) or an array item with a specific key (name[key], name.key). Unnecessary whitespace characters are automatically stripped. |
bool | Applicable if set and not empty. Any non-empty string in the attribute value is treated as true; an empty string or the absence of the attribute is treated as false. |
int | Arithmetic expression cast to an integer number. The full expression is evaluated first, then the result is truncated to an integer. |
float | Arithmetic expression cast to a floating point number. The full expression is evaluated, preserving the fractional part. |
date | Arithmetic expression cast to an integer number and interpreted as a Unix timestamp. The resulting integer represents seconds since January 1, 1970 (UTC). |
string | Arbitrary byte sequence or series of Unicode (UTF-8) characters. Variable substitution is performed on the value before it is passed to the command. |
regexp | String interpreted as a Perl-compatible regular expression pattern enclosed in delimiters (e.g. /[a-z]+/i). |
type | Meta type identifier (case-insensitive). Used for attributes that accept type names like string, int, array, etc. |
ixml | Arbitrary iXML code. The content is parsed and executed as a series of statements. |
Result types
Every operation or construct that produces a value declares a result type:
| Type | Meaning |
|---|---|
null | NULL — the absence of a meaningful value |
bool | Boolean — either TRUE or FALSE |
int | Integer number — a whole number without a fractional part |
float | Floating point number — a number with a fractional part |
string | String — an arbitrary byte sequence or series of Unicode characters |
array | Array — a collection of items in an ordered map that associates keys to values |
function | Function — a closed subroutine with its own local context |
macro | Macro — an open subroutine that executes in the caller's context |
class | Class — an array prototype used for object-oriented programming |
Predicates
Predicates are behavioral flags that modify how a command's result is handled by the runtime:
| Predicate | Meaning |
|---|---|
no-result-propagation | The result is not propagated to the parent statement. |
When a command carries the no-result-propagation predicate, its result cannot be used inline via result propagation. For example, <function> and <class> definitions carry this predicate — they produce a value (the function or class itself), but that value is never propagated to a parent <output> or <set>. The value is only stored in the variable specified by the var attribute.
iXML document envelope
A complete iXML document should use the standard XML envelope with the iXML namespace and schema declarations. The envelope provides schema validation support and enables IDE features such as autocomplete and error highlighting:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE ixml SYSTEM "https://developers.zeyos.com/schema/ixml.dtd">
<ixml
xmlns="https://developers.zeyos.com/schema/ixml"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://developers.zeyos.com/schema/ixml https://developers.zeyos.com/schema/ixml.xsd">
<!-- iXML statements -->
</ixml>
Each part of the envelope serves a specific purpose:
| Part | Purpose |
|---|---|
<?xml ... ?> | Standard XML declaration specifying the XML version (1.0) and character encoding (UTF-8). This must be the very first line of the file with no preceding whitespace. |
<!DOCTYPE ...> | Optional DTD reference for validation. When present, the DTD enables basic structural validation of the document against the iXML element definitions. |
xmlns | The iXML namespace URI. This declares that all unqualified elements in the document belong to the iXML namespace. |
xmlns:xsi | The XML Schema instance namespace. This standard namespace provides the schemaLocation attribute for linking to XSD schema files. |
xsi:schemaLocation | Maps the iXML namespace to the XSD schema URL. IDEs and XML editors use this mapping to provide real-time validation, autocomplete suggestions, and error highlighting. |
When testing snippets with zeysdk run --ixml or the Development Console, the outer envelope can be omitted for convenience. Application files (services, resources, and weblets) should use the full envelope for schema validation and IDE support.