create/docs/src/development/package-xml-schema.md

Package.xml Schema Extensions

Kindred Create extends FreeCAD's standard package.xml addon manifest with a <kindred> element. This element provides metadata for the manifest-driven addon loader: version compatibility, load ordering, dependency declarations, and editing context registration.

The <kindred> element is ignored by FreeCAD's AddonManager and stock module loader. Addons with this element remain compatible with upstream FreeCAD.

Field reference

Field	Parsed by loader	Required	Default	Description
min_create_version	Yes	No	(none)	Minimum Kindred Create version. Addon is skipped if the running version is lower.
max_create_version	Yes	No	(none)	Maximum Kindred Create version. Addon is skipped if the running version is higher.
load_priority	Yes	No	100	Integer. Lower values load first. Used as a secondary sort after dependency resolution.
dependencies	Yes	No	(none)	List of addon names (by <name> in their package.xml) that must load before this one.
sdk_version	No	No	(none)	Required kindred-addon-sdk version. Reserved for future use when the SDK is available.
pure_python	No	No	true	If false, the addon requires compiled C++ components. Informational.
contexts	No	No	(none)	Editing contexts this addon registers or injects into. Informational.

Fields marked "Parsed by loader" are read by addon_loader.py and affect load behavior. Other fields are informational metadata for tooling and documentation.

Schema

<kindred>
  <min_create_version>0.1.0</min_create_version>
  <max_create_version>1.0.0</max_create_version>
  <sdk_version>0.1.0</sdk_version>
  <load_priority>100</load_priority>
  <pure_python>true</pure_python>
  <dependencies>
    <dependency>sdk</dependency>
    <dependency>other-addon</dependency>
  </dependencies>
  <contexts>
    <context id="partdesign.body" action="inject"/>
    <context id="sketcher.edit" action="register"/>
    <context id="*" action="overlay"/>
  </contexts>
</kindred>

All child elements are optional. An empty <kindred/> element is valid and signals that the addon is Kindred-aware with all defaults.

Version fields

min_create_version and max_create_version are compared against the running Kindred Create version using semantic versioning (major.minor.patch). If the running version falls outside the declared range, the addon is skipped with a warning in the report view.

Load priority

When multiple addons have no dependency relationship, load_priority determines their relative order. Lower values load first. Suggested ranges:

Range	Use
0-9	SDK and core infrastructure
10-49	Foundation addons that others may depend on
50-99	Standard addons
100+	Optional or late-loading addons

Dependencies

Each <dependency> names another addon by its <name> element in package.xml. The loader resolves load order using topological sort. If a dependency is not found among discovered addons, the dependent addon is skipped.

Contexts

The <contexts> element documents which editing contexts the addon interacts with. The action attribute describes the type of interaction:

Action	Meaning
inject	Addon injects commands into this context's toolbars
register	Addon registers this as a new context
overlay	Addon registers an overlay that may apply across contexts

A wildcard id="*" indicates the addon's overlay applies universally (matched by a condition function rather than a specific context ID).

Example: complete package.xml

<?xml version="1.0" encoding="UTF-8"?>
<package format="1" xmlns="https://wiki.freecad.org/Package_Metadata">
  <name>MyAddon</name>
  <description>Example Kindred Create addon</description>
  <version>0.2.0</version>
  <maintainer email="dev@example.com">Developer</maintainer>
  <license>LGPL-2.1-or-later</license>
  <url type="repository">https://git.example.com/myaddon</url>

  <content>
    <workbench>
      <classname>MyAddonWorkbench</classname>
      <subdirectory>./</subdirectory>
    </workbench>
  </content>

  <kindred>
    <min_create_version>0.1.0</min_create_version>
    <load_priority>80</load_priority>
    <pure_python>true</pure_python>
    <contexts>
      <context id="partdesign.body" action="inject"/>
    </contexts>
  </kindred>
</package>

Backward compatibility

• The <kindred> element sits outside <content> and is not part of FreeCAD's package.xml specification. FreeCAD's App.Metadata C++ parser and the AddonManager's Python MetadataReader both ignore unknown elements.
• An addon installed in stock FreeCAD will work normally; the <kindred> extensions are simply unused.
• The Kindred Create loader works with or without the <kindred> element. Addons that omit it load with no version constraints and default priority (100).