Element <param>

Purpose: Declared contract for one fragment input.

Why: Use it in an included fragment to declare and validate one required or defaulted input.

Example

<param name="channel"/>

Decision guide

Business value: Makes a reusable fragment's required inputs and defaults explicit to reviewers and tools.

• Use when

  • An included fragment requires a caller-provided value or exposes a documented default.

• Choose another approach when

  • Supplying the caller-side value or defining an unrelated setup property.

• Prerequisites

  • Place it in the included fragment and give it a stable name.

• Alternatives

  • Use property at the include site to supply the declared parameter. (See: <property>)

Complete examples

Call one typed descriptor fragment with scoped parameters

Use a param contract and include-local properties when several business products share one model shape but require different bounded values.

<setup>
    <param name="entity_name" description="Product emitted by this fragment."/>
    <param name="scheme" type="enum" values="SEPA SWIFT"/>
    <param name="count" type="int" default="2"/>
    <generate name="{entity_name}" count="{count}" target="LogExporter">
        <id name="id" generator="IncrementGenerator"/>
        <key name="scheme" constant="{scheme}"/>
    </generate>
</setup>

<setup>
    <include uri="fragments/payment.xml">
        <property name="entity_name" constant="sepa_payments"/>
        <property name="scheme" constant="SEPA"/>
        <property name="count" constant="3"/>
    </include>
    <include uri="fragments/payment.xml">
        <property name="entity_name" constant="swift_payments"/>
        <property name="scheme" constant="SWIFT"/>
    </include>
</setup>

Rules and invalid combinations

type='enum' requires a non-empty values list.

Attributes: type, values

Why: The fragment contract needs the allowed literal vocabulary to validate include properties.

<param name="channel" type="enum" values="WEB STORE"/>

<param name="channel" type="enum"/>

A param default cannot contain an expression.

Attributes: default

Why: Defaults are validated at parse time; dynamic values belong on the caller's property script mode.

<param name="count" type="int" default="10"/>

<param name="count" type="int" default="{base_count}"/>

A literal default must satisfy the declared param type.

Attributes: default, type, values

Why: The include contract must reject an invalid fallback before the fragment executes.

<param name="count" type="int" default="10"/>

<param name="count" type="int" default="ten"/>

I618 — Parser Include Param Missing

Fragment contract violation for

{contract_table}

{missing_summary}

Why: The included fragment declares required params that were not supplied by the caller.

Resolution: Supply the missing values or define defaults on the fragment declarations.

Full rule

I619 — Parser Include Param Invalid Value

Invalid value for param '{param_name}' in . Expected {expected_detail}; provided '{provided_value}'

Why: The include caller supplied a literal value that does not satisfy the fragment param contract.

Resolution: Update the value to match the declared param type or enum values.

Full rule

I620 — Parser Param In Top Level Descriptor

declarations have no effect in top-level descriptors

Why: Fragment param declarations are only consumed when a descriptor is used as an included XML fragment.

Resolution: Move the declarations into a fragment descriptor or remove them from the top-level descriptor.

Full rule

Allowed parents / Allowed children

Allowed parents: else, else-if, if, setup, while

Allowed children:

None

Related concepts and use cases

• Dynamic Includes and Fragment Parameters — Explains URI interpolation, scoped include properties, typed fragment params, runtime caller context, nesting, conditions, and cataloged failures for reusable XML composition.

Attributes

Show all 5 attributes

default

Optional literal default injected into the child include scope when omitted by the caller.

optional; string; Default: null.

description

Human-readable explanation surfaced by static schema consumers.

optional; string; Default: null.

name

Fragment param name delivered by .

required; string.

type

Param type used for parse-time validation of literal property values.

optional; string; Default: "string"; Values: string, int, enum, path.

values

Whitespace-separated enum values when type='enum'.

optional; string; Default: null.