Skip to content

Service Interface XML reference

Baseline: Tala 31.0.1. The service interface declares operations referenced by domain plan items and binds them to parameters and transport targets.

Operations and required structure

The root <service_interface> contains action, query, and validator declarations. An action has this structure:

<service_interface>
  <action name="BookRoom">
    <parameters>
      <parameter predicate="room_date" format="value"/>
      <parameter predicate="selected_room" optional="true"/>
    </parameters>
    <failure_reasons>
      <failure_reason name="unavailable"/>
    </failure_reasons>
    <target>
      <http endpoint="https://service.example/book-room"/>
    </target>
  </action>
  <query name="FindRooms">
    <parameters>
      <parameter predicate="room_date"/>
    </parameters>
    <target>
      <http endpoint="https://service.example/find-rooms"/>
    </target>
  </query>
</service_interface>

The example endpoint is illustrative only; deployed endpoint values belong in service configuration.

Operation Required children Target forms accepted by Tala 31.0.1
action parameters, failure_reasons, target <frontend/> or <http endpoint="..."/>
query parameters, target <http endpoint="..."/>
validator parameters, target <http endpoint="..."/>

Operation names must be unique within their type. A target is required. Query and validator frontend targets are rejected by Tala's XML compiler tests.

For an action, keep the <parameters>, <failure_reasons>, and <target> children even when a section is empty. An empty failure list is written as <failure_reasons/>. Queries and validators do not have a failure_reasons child in the XML format.

Parameters and results

Each <parameter> requires an ontology predicate. Its optional format is value or grammar_entry; optional is an XML Boolean. For HTTP targets the service receives both the semantic value and the language grammar entry. The format selector chooses the frontend representation for frontend-targeted actions.

Actions may declare failure_reason names. The action result and failure information are consumed by TDM's service-action execution and reporting logic.

Parameter attribute Values Meaning
predicate Required ontology predicate Selects the argument to bind and pass to the target.
optional XML Boolean Marks the argument optional.
format value or grammar_entry Selects the frontend argument form. HTTP targets receive both representations.

frontend delegates actions to the application-facing side. http invokes the declared HTTP endpoint; query and validator operations use this target in Tala 31.0.1.

Compatibility boundaries

The XSD declares an entity_recognizer element, but Tala 31.0.1's ServiceInterfaceCompiler builds only actions, queries, and validators. Do not assume an entity-recognizer declaration is part of the runtime ServiceInterface model.

The DDD JSON schema uses a shared target shape that permits a frontend target for all operation types. The XML compiler rejects frontend targets for queries and validators after JSON is converted to XML. Use HTTP targets for those operations and compile/load the bundle to validate it.

Executable references: tala/ddd/schemas/service_interface.xsd, tala/ddd/schemas/json/service_interface.schema.json, tala/ddd/ddd_xml_compiler.py, and tala/ddd/test/test_ddd_xml_compiler.py.

Operation and child references