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

<?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.