Addon Manifest Schema

This repository contains the source files for the XML
Schema ( XSD ) used for the FreeCAD Addon Manifest.

     

📷 Showcase

The schema not only provides validation, autocomplete
and examples but also tooltips, here is one of them.

💬 Usage

To use this schema, you simply have to
reference it in your package.xml file.

<?xml-model
    href = '<Schema Url>'
?>

📍 Endpoints

Currently FreeCAD only supports one endpoint
that hosts the latest version of the schema at:

https://Addons.FreeCAD.Org/Manifest.xsd

💾 Older Versions

In case you need to use an older version of the schema,
you can reference one of the GitHub Releases like so:

https://github.com/FreeCAD/FreeCAD-Addon-Manifest-Schema/releases/download/<Version>/Schema.xsd

https://github.com/FreeCAD/FreeCAD-Addon-Manifest-Schema/releases/download/v1.0/Schema.xsd

📄 Integration

The following code demonstrates how you can
reference this schema in your addon manifest:

<?xml
    version = '1.0'
    encoding = 'UTF-8'
    standalone = 'no'
?>
<?xml-model
    href = 'https://Addons.FreeCAD.Org/Manifest.xsd'
?>
<package 
    xmlns = 'HTTPS://Addons.FreeCAD.Org/Manifest'
>
    <!-- . . . -->
</package>

📖 Examples

The following manifests demonstrate
different configurations you may use.

File	Contents
Everything.xml	Manifest with all available elements & attributes.

📑 Repository

Folder	Purpose
Source	Tree of bite sized XSD source files.
Scripts	Python script used to create a bundle.
Assets	Examples & images used in the docs.
.github	Configuration & information of the repo.
.build	Output folder for the bundled schema.

🔧 Development

The source files of the schema can be used
directly by referencing Source/mod.xsd.

<?xml-model
    href = '/Path-To-Cloned-Repository/Source/mod.xsd'
?>

📦 Bundling

To bundle the /Source/ files into a combined schema,
you just have to run the following Python command:

python Scripts/Bundle.py

This will create a bundled file at .build/Schema.xsd

<?xml-model
    href = '/Path-To-Cloned-Repository/.build/Schema.xsd'
?>

📜 Preview

📋 Versioning

This schema uses semantic versioning with
2 numbers where the first is the manifest
format & the second is this schema's build.

<Manifest Format>.<Schema Build>

The Releases page lists all published versions.

🚧 Workarounds

Due to the missing XSD 1.1 Support in the RedHat
VSCode extension, multiple workarounds are being
used to approximate the actual schema structure.

• In XSD 1.1, the <all> tag allows for unbound elements, the two possible
  workarounds are using a sequence and forcing the order of elements or
  using <choice> and allowing multiple of every tags.

  The <package> tag uses the latter to facilitate <maintainer> & <url>

• The <url> tag should require a branch attribute if the
  type attribute was set to repository, however currently
  the branch attribute will always be present & optional.