Skip to content

Commit 5855b83

Browse files
vivoeivaclaudefacontidavide
authored
Feature: advanced xml validation (#1146)
* Add 'generic' parameter to writeTreeXSD() When generic=true, oneNodeGroup uses xs:any processContents="lax" instead of a closed xs:choice, allowing unknown custom node elements to pass validation. Top-level xs:element declarations are also emitted so that lax processing can still resolve and validate the known built-in node types by name. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Add generate_xsd tool Generates the generic XSD schema from the default factory (built-in nodes only) and prints it to stdout, suitable for use as a generic static validator that stays in sync with the built-in node inventory. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Fix non-deterministic port attribute order in writeTreeXSD() PortsList is an unordered_map so iterating it directly produced XSD attributes in hash-table order, which varies across runs and platforms. Sort ports into a std::map before emitting xs:attribute elements. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Add writeTreeSchematron() for cross-reference validation of BT XML files XSD alone cannot express constraints like "every custom node element used in a BehaviorTree body must have a matching TreeNodesModel entry" Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Add generate_schematron tool Generates an ISO Schematron schema (btcpp4.sch) complementing the generic XSD Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Add generated XSD and Schematron schemas * Add validate_xml.py - XSD and Schematron validation tool Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Only built-ins should go into generic xsd file * Add tests for writeTreeXSD() and writeTreeSchematron() Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Fix implicit conversion * Also handle inout_port in XSD * Fix reconfiguration after editing src/btcpp4_schematron.sch * Fix writeTreeXSD() signature not to break ABI * Change placeholder replacement logic for Schematron * Add more test cases for InsideXmlComment() * Add xsd and schematron checks to CI (intentionally broken) * Fix clang-format issues * Regenerate schemas to pass CI * Add guard for --no-xsd --no-sch together to validate_xml.py * Remove rule checking explicit notation against TreeNodeModel * Regenerate Schematron file * Add Schematron Rule B: explicit-notation node structure constraints Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Regenerate Schematron file * Drop insideXmlComment(): keep the placeholder out of the template comment insideXmlComment() was added to the public xml_parsing.h only so that writeTreeSchematron() could skip the ##BUILTIN_PIPE## placeholder where the template comment mentions it. Rewording the comment so it no longer contains the placeholder makes a plain replace-all enough, removes the helper from the public API, and also fixes the generated bt4.sch, whose comment still described an unexpanded placeholder. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Regenerate tools/generated/bt4.xsd for _onlyIf, _onStart, BTCPP_version Master gained the _onlyIf/_onStart preconditions (#1261) and the BTCPP_version root attribute (#1264); the checked-in XSD was stale and the new 'generated schemas are up to date' CI step would fail. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ME1hnSFSzibU5phxboGsjk * Regenerate bt4.xsd and bt4.sch for the Finally node (#1229) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ME1hnSFSzibU5phxboGsjk --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com> Co-authored-by: Davide Faconti <davide.faconti@gmail.com>
1 parent 4f672ea commit 5855b83

13 files changed

Lines changed: 1078 additions & 11 deletions

File tree

‎.github/workflows/cmake_ubuntu.yml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,17 @@ jobs:
5050
- name: run test (Linux)
5151
run: ctest --test-dir build/${{env.BUILD_TYPE}}
5252

53+
- name: Check generated schemas are up to date
54+
run: |
55+
./build/${{env.BUILD_TYPE}}/tools/bt4_generate_xsd > /tmp/bt4.xsd
56+
./build/${{env.BUILD_TYPE}}/tools/bt4_generate_schematron > /tmp/bt4.sch
57+
fail=0
58+
diff tools/generated/bt4.xsd /tmp/bt4.xsd || \
59+
{ echo "XSD is stale - regenerate: ./build/Release/tools/bt4_generate_xsd > tools/generated/bt4.xsd"; fail=1; }
60+
diff tools/generated/bt4.sch /tmp/bt4.sch || \
61+
{ echo "Schematron is stale - regenerate: ./build/Release/tools/bt4_generate_schematron > tools/generated/bt4.sch"; fail=1; }
62+
exit $fail
63+
5364
# USE_VENDORED_JSON=OFF, with the oldest supported nlohmann_json (3.10.5 on 22.04)
5465
system-json:
5566
runs-on: ubuntu-22.04

‎CMakeLists.txt‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -219,6 +219,18 @@ if (WIN32)
219219
list(APPEND BT_SOURCE src/shared_library_WIN.cpp )
220220
endif()
221221

222+
# Embed src/btcpp4_schematron.sch as a C++ string constant.
223+
set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS
224+
"${CMAKE_CURRENT_SOURCE_DIR}/src/btcpp4_schematron.sch"
225+
)
226+
227+
file(READ "${CMAKE_CURRENT_SOURCE_DIR}/src/btcpp4_schematron.sch" BTCPP_SCHEMATRON_TEMPLATE)
228+
configure_file(
229+
"${CMAKE_CURRENT_SOURCE_DIR}/src/schematron_template.h.in"
230+
"${CMAKE_CURRENT_BINARY_DIR}/generated/schematron_template.gen.h"
231+
@ONLY
232+
)
233+
222234
if (BTCPP_SHARED_LIBS)
223235
set(CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS ON)
224236
add_library(${BTCPP_LIBRARY} SHARED ${BT_SOURCE})
@@ -261,6 +273,7 @@ target_include_directories(${BTCPP_LIBRARY}
261273
$<INSTALL_INTERFACE:include>
262274
PRIVATE
263275
${BTCPP_EXTRA_INCLUDE_DIRS}
276+
${CMAKE_CURRENT_BINARY_DIR}/generated
264277
)
265278

266279
target_compile_definitions(${BTCPP_LIBRARY} PUBLIC BTCPP_LIBRARY_VERSION="${PROJECT_VERSION}")

‎include/behaviortree_cpp/xml_parsing.h‎

Lines changed: 40 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -59,14 +59,51 @@ void VerifyXML(const std::string& xml_text,
5959
bool include_builtin = false);
6060

6161
/**
62-
* @brief writeTreeXSD generates an XSD for the nodes defined in the factory
62+
* @brief writeTreeXSD generates an XSD for the nodes defined in the factory.
6363
*
64-
* @param factory the factory with the registered types
64+
* @param factory the factory with the registered types
6565
*
66-
* @return string containing the XML.
66+
* @return string containing the XSD XML (strict, closed-vocabulary schema).
6767
*/
6868
[[nodiscard]] std::string writeTreeXSD(const BehaviorTreeFactory& factory);
6969

70+
/**
71+
* @brief writeTreeXSD generates an XSD for the nodes defined in the factory.
72+
*
73+
* @param factory the factory with the registered types
74+
* @param generic if true, oneNodeGroup uses xs:any processContents="lax"
75+
* instead of a closed xs:choice, allowing unknown custom
76+
* node elements to pass validation. Top-level xs:element
77+
* declarations are also emitted so that lax processing can
78+
* still resolve and validate the known built-in node types.
79+
*
80+
* @return string containing the XSD XML.
81+
*/
82+
[[nodiscard]] std::string writeTreeXSD(const BehaviorTreeFactory& factory, bool generic);
83+
84+
/**
85+
* @brief writeTreeSchematron generates an ISO Schematron schema for BehaviorTree.CPP XML files.
86+
*
87+
* XSD alone cannot express cross-reference constraints. This Schematron
88+
* complements writeTreeXSD() with three rule patterns:
89+
* - treeNodesModel: every custom (non-built-in) node element appearing in a
90+
* BehaviorTree body must have a matching TreeNodesModel entry (required by
91+
* Groot2 for port display and editing).
92+
* - subtreeResolution: every <SubTree ID="X"/> must resolve to a
93+
* <BehaviorTree ID="X"> in the same file (relaxed when <include> is present).
94+
* - rootStructure: main_tree_to_execute must name an existing BehaviorTree.
95+
*
96+
* The built-in node list is derived from factory.builtinNodes() so that the
97+
* schema stays in sync as new built-ins are added.
98+
*
99+
* @param factory factory from which the built-in node names are taken;
100+
* a default-constructed BehaviorTreeFactory suffices for most uses.
101+
*
102+
* @return string containing the Schematron XML (queryBinding="xslt",
103+
* compatible with xsltproc and lxml.isoschematron).
104+
*/
105+
[[nodiscard]] std::string writeTreeSchematron(const BehaviorTreeFactory& factory);
106+
70107
/**
71108
* @brief WriteTreeToXML create a string that contains the XML that corresponds to a given tree.
72109
* When using this function with a logger, you should probably set both add_metadata and

‎src/btcpp4_schematron.sch‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<sch:schema xmlns:sch="http://purl.oclc.org/dsdl/schematron" queryBinding="xslt">
3+
<sch:title>BehaviorTree.CPP XML validation rules</sch:title>
4+
5+
<!--
6+
Rule A checks that every compact-notation custom node appearing in a BehaviorTree
7+
body has a corresponding entry in TreeNodesModel. Groot2 and other graphical
8+
editors require this because compact notation alone gives no port information.
9+
Explicit notation (<Action ID="X"/>) is already sufficient for Groot2 and does
10+
not require a TreeNodesModel entry (see behaviortree.dev/docs/learn-the-basics/xml_format).
11+
Built-in node types are excluded - they are always known to the library.
12+
13+
The pipe-delimited list of built-in node names used by Rule A, e.g.
14+
|AlwaysFailure|AlwaysSuccess|Fallback|Sequence|...|, is filled in by
15+
writeTreeSchematron() from the built-in nodes of the factory.
16+
17+
The XPath 1.0 idiom contains('|A|B|C|', concat('|', local-name(), '|'))
18+
tests set membership without requiring XPath 2.0 sequence literals, keeping
19+
this schema compatible with xsltproc and lxml.isoschematron.
20+
-->
21+
<sch:pattern id="treeNodesModel">
22+
<sch:title>TreeNodesModel completeness</sch:title>
23+
24+
<!-- Rule A: compact-notation custom nodes (element name IS the registration ID) -->
25+
<sch:rule context="/root/BehaviorTree//*[
26+
not(contains('##BUILTIN_PIPE##', concat('|', local-name(), '|'))) and
27+
local-name() != 'Action' and local-name() != 'Condition' and
28+
local-name() != 'Control' and local-name() != 'Decorator' and
29+
local-name() != 'SubTree'
30+
]">
31+
<sch:assert test="/root/TreeNodesModel/*[@ID = local-name(current())]">
32+
Custom node '<sch:value-of select="local-name()"/>' used in tree
33+
'<sch:value-of select="ancestor::BehaviorTree/@ID"/>'
34+
has no &lt;TreeNodesModel&gt; entry.
35+
</sch:assert>
36+
</sch:rule>
37+
</sch:pattern>
38+
39+
<!--
40+
Rule B checks structural constraints for explicit-notation nodes.
41+
The BT.CPP XML format mandates:
42+
- Action and Condition nodes are leaves (no children).
43+
- Decorator nodes have exactly one child.
44+
- Control nodes have at least one child.
45+
These constraints apply to the generic wrapper elements used in explicit notation
46+
(<Action ID="..."/>, <Condition ID="..."/>, <Decorator ID="..."/>, <Control ID="..."/>).
47+
Built-in nodes written in compact notation are already constrained by the XSD.
48+
-->
49+
<sch:pattern id="explicitNodeStructure">
50+
<sch:title>Explicit-notation node structure</sch:title>
51+
52+
<!-- Action and Condition are leaves -->
53+
<sch:rule context="/root/BehaviorTree//*[
54+
@ID and (local-name() = 'Action' or local-name() = 'Condition')
55+
]">
56+
<sch:assert test="count(*) = 0">
57+
<sch:value-of select="local-name()"/> ID='<sch:value-of select="@ID"/>'
58+
must have no children (has <sch:value-of select="count(*)"/>).
59+
</sch:assert>
60+
</sch:rule>
61+
62+
<!-- Decorator has exactly one child -->
63+
<sch:rule context="/root/BehaviorTree//*[local-name() = 'Decorator' and @ID]">
64+
<sch:assert test="count(*) = 1">
65+
Decorator ID='<sch:value-of select="@ID"/>'
66+
must have exactly one child (has <sch:value-of select="count(*)"/>).
67+
</sch:assert>
68+
</sch:rule>
69+
70+
<!-- Control has at least one child -->
71+
<sch:rule context="/root/BehaviorTree//*[local-name() = 'Control' and @ID]">
72+
<sch:assert test="count(*) >= 1">
73+
Control ID='<sch:value-of select="@ID"/>' must have at least one child.
74+
</sch:assert>
75+
</sch:rule>
76+
</sch:pattern>
77+
78+
<!--
79+
Rule C checks that every <SubTree ID="X"/> references a <BehaviorTree ID="X">
80+
defined in the same file. The check is relaxed when an <include> element is
81+
present because the referenced tree may reside in an external file.
82+
-->
83+
<sch:pattern id="subtreeResolution">
84+
<sch:title>SubTree ID cross-references</sch:title>
85+
<sch:rule context="/root/BehaviorTree//SubTree[@ID]">
86+
<sch:assert
87+
test="/root/BehaviorTree[@ID = current()/@ID] or /root/include">
88+
SubTree ID='<sch:value-of select="@ID"/>' is not defined in this file.
89+
(If the definition lives in an included file, add an &lt;include&gt;.)
90+
</sch:assert>
91+
</sch:rule>
92+
</sch:pattern>
93+
94+
<sch:pattern id="rootStructure">
95+
<sch:title>Root element consistency</sch:title>
96+
<sch:rule context="/root[@main_tree_to_execute]">
97+
<sch:assert
98+
test="BehaviorTree[@ID = current()/@main_tree_to_execute]">
99+
main_tree_to_execute='<sch:value-of select="@main_tree_to_execute"/>'
100+
does not match any BehaviorTree ID in this file.
101+
</sch:assert>
102+
</sch:rule>
103+
</sch:pattern>
104+
105+
</sch:schema>

‎src/schematron_template.h.in‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
// Auto-generated from src/btcpp4_schematron.sch — do not edit directly.
2+
// To update: edit src/btcpp4_schematron.sch and re-run CMake.
3+
namespace BT { namespace detail {
4+
static const char* const schematron_template =
5+
R"BTCPP4SCH(@BTCPP_SCHEMATRON_TEMPLATE@)BTCPP4SCH";
6+
} // namespace detail
7+
} // namespace BT

‎src/xml_parsing.cpp‎

Lines changed: 86 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,8 @@
5959
#endif
6060
#endif
6161

62+
#include "schematron_template.gen.h"
63+
6264
#include "behaviortree_cpp/blackboard.h"
6365
#include "behaviortree_cpp/tree_node.h"
6466
#include "behaviortree_cpp/utils/demangle_util.h"
@@ -1560,17 +1562,24 @@ std::string writeTreeNodesModelXML(const BehaviorTreeFactory& factory,
15601562
}
15611563

15621564
std::string writeTreeXSD(const BehaviorTreeFactory& factory)
1565+
{
1566+
return writeTreeXSD(factory, false);
1567+
}
1568+
1569+
std::string writeTreeXSD(const BehaviorTreeFactory& factory, bool generic)
15631570
{
15641571
// There are 2 forms of representation for a node:
15651572
// compact: <Sequence .../> and explicit: <Control ID="Sequence" ... />
15661573
// Only the compact form is supported because the explicit form doesn't
15671574
// make sense with XSD since we would need to allow any attribute.
15681575
// Prepare the data
15691576

1577+
const auto& builtin_set = factory.builtinNodes();
15701578
std::map<std::string, const TreeNodeManifest*> ordered_models;
15711579
for(const auto& [registration_id, model] : factory.manifests())
15721580
{
1573-
ordered_models.insert({ registration_id, &model });
1581+
if(!generic || builtin_set.count(registration_id) != 0)
1582+
ordered_models.insert({ registration_id, &model });
15741583
}
15751584

15761585
XMLDocument doc;
@@ -1651,6 +1660,15 @@ std::string writeTreeXSD(const BehaviorTreeFactory& factory)
16511660
</xs:extension>
16521661
</xs:simpleContent>
16531662
</xs:complexType>
1663+
<xs:complexType name="inoutPortType">
1664+
<xs:simpleContent>
1665+
<xs:extension base="xs:string">
1666+
<xs:attribute name="name" type="xs:string" use="required"/>
1667+
<xs:attribute name="type" type="xs:string" use="optional"/>
1668+
<xs:attribute name="default" type="xs:string" use="optional"/>
1669+
</xs:extension>
1670+
</xs:simpleContent>
1671+
</xs:complexType>
16541672
<xs:attributeGroup name="preconditionAttributeGroup">
16551673
<xs:attribute name="_failureIf" type="xs:string" use="optional"/>
16561674
<xs:attribute name="_onlyIf" type="xs:string" use="optional"/>
@@ -1686,6 +1704,7 @@ std::string writeTreeXSD(const BehaviorTreeFactory& factory)
16861704
<xs:choice minOccurs="0" maxOccurs="unbounded">
16871705
<xs:element name="input_port" type="inputPortType"/>
16881706
<xs:element name="output_port" type="outputPortType"/>
1707+
<xs:element name="inout_port" type="inoutPortType"/>
16891708
</xs:choice>
16901709
<xs:element name="description" type="descriptionType" minOccurs="0" maxOccurs="1"/>
16911710
</xs:sequence>
@@ -1724,15 +1743,27 @@ std::string writeTreeXSD(const BehaviorTreeFactory& factory)
17241743
XMLElement* one_node_group = doc.NewElement("xs:group");
17251744
{
17261745
one_node_group->SetAttribute("name", "oneNodeGroup");
1727-
std::ostringstream xsd;
1728-
xsd << "<xs:choice>";
1729-
for(const auto& [registration_id, model] : ordered_models)
1746+
if(generic)
17301747
{
1731-
xsd << "<xs:element name=\"" << registration_id << "\" type=\"" << registration_id
1732-
<< "Type\"/>";
1748+
// Generic: accept any element; lax processing validates known built-ins
1749+
// via the top-level xs:element declarations emitted at the end of this function.
1750+
parse_and_insert(one_node_group, "<xs:choice>"
1751+
"<xs:any namespace=\"##any\" "
1752+
"processContents=\"lax\"/>"
1753+
"</xs:choice>");
1754+
}
1755+
else
1756+
{
1757+
std::ostringstream xsd;
1758+
xsd << "<xs:choice>";
1759+
for(const auto& [registration_id, model] : ordered_models)
1760+
{
1761+
xsd << "<xs:element name=\"" << registration_id << "\" type=\"" << registration_id
1762+
<< "Type\"/>";
1763+
}
1764+
xsd << "</xs:choice>";
1765+
parse_and_insert(one_node_group, xsd.str().c_str());
17331766
}
1734-
xsd << "</xs:choice>";
1735-
parse_and_insert(one_node_group, xsd.str().c_str());
17361767
schema_element->InsertEndChild(one_node_group);
17371768
}
17381769

@@ -1799,8 +1830,12 @@ std::string writeTreeXSD(const BehaviorTreeFactory& factory)
17991830
XMLElement* common_attr_group = doc.NewElement("xs:attributeGroup");
18001831
common_attr_group->SetAttribute("ref", "commonAttributeGroup");
18011832
type->InsertEndChild(common_attr_group);
1833+
std::map<std::string, const BT::PortInfo*> ordered_ports;
18021834
for(const auto& [port_name, port_info] : model->ports)
1835+
ordered_ports.insert({ port_name, &port_info });
1836+
for(const auto& [port_name, port_info_ptr] : ordered_ports)
18031837
{
1838+
const auto& port_info = *port_info_ptr;
18041839
XMLElement* attr = doc.NewElement("xs:attribute");
18051840
attr->SetAttribute("name", port_name.c_str());
18061841
const auto xsd_attribute_type = xsdAttributeType(port_info);
@@ -1828,11 +1863,54 @@ std::string writeTreeXSD(const BehaviorTreeFactory& factory)
18281863
schema_element->InsertEndChild(type);
18291864
}
18301865

1866+
// Generic mode: emit top-level xs:element declarations so that
1867+
// processContents="lax" in oneNodeGroup can resolve and validate
1868+
// known built-in node elements by name.
1869+
if(generic)
1870+
{
1871+
for(const auto& [registration_id, model] : ordered_models)
1872+
{
1873+
XMLElement* elem = doc.NewElement("xs:element");
1874+
elem->SetAttribute("name", registration_id.c_str());
1875+
elem->SetAttribute("type", (registration_id + "Type").c_str());
1876+
schema_element->InsertEndChild(elem);
1877+
}
1878+
}
1879+
18311880
XMLPrinter printer;
18321881
doc.Print(&printer);
18331882
return std::string(printer.CStr(), size_t(printer.CStrSize() - 1));
18341883
}
18351884

1885+
std::string writeTreeSchematron(const BehaviorTreeFactory& factory)
1886+
{
1887+
// Build the pipe-delimited builtin node list, e.g. "|AlwaysFailure|Fallback|...|",
1888+
// then substitute the ##BUILTIN_PIPE## placeholder in the embedded template.
1889+
// The template itself lives in src/btcpp4_schematron.sch (human-readable);
1890+
// schematron_template.gen.h is generated from it by CMake.
1891+
std::ostringstream builtin_pipe_ss;
1892+
builtin_pipe_ss << "|";
1893+
for(const auto& name : factory.builtinNodes())
1894+
builtin_pipe_ss << name << "|";
1895+
1896+
std::string result = BT::detail::schematron_template;
1897+
const std::string placeholder = "##BUILTIN_PIPE##";
1898+
const std::string builtin_pipe = builtin_pipe_ss.str();
1899+
int replacements = 0;
1900+
1901+
for(std::size_t pos = result.find(placeholder); pos != std::string::npos;
1902+
pos = result.find(placeholder, pos))
1903+
{
1904+
result.replace(pos, placeholder.size(), builtin_pipe);
1905+
pos += builtin_pipe.size();
1906+
++replacements;
1907+
}
1908+
if(replacements == 0)
1909+
throw RuntimeError("writeTreeSchematron: placeholder '", placeholder,
1910+
"' not found in schematron template");
1911+
return result;
1912+
}
1913+
18361914
std::string WriteTreeToXML(const Tree& tree, bool add_metadata, bool add_builtin_models)
18371915
{
18381916
XMLDocument doc;

0 commit comments

Comments
 (0)