Skip to content

Latest commit

 

History

History
179 lines (118 loc) · 4.55 KB

README.md

File metadata and controls

179 lines (118 loc) · 4.55 KB

Addon Manifest Schema

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

Button Discord   Button Website   Button Contribute

The usage information is currently not functional as the
endpoint for the hosted version hasn't been set up yet.


📷 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
    schematypens = 'HTTPS://FreeCAD.Org/Manifest'
    href = '<Schema Url>'
?>

This replaces the xmlns attribute on <package>


📍 Endpoints

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

https://FreeCAD.org/Manifest

💾 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/Addon-Manifest/releases/download/<Version>/Schema.xsd`

📄 Example

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
    schematypens = 'HTTPS://FreeCAD.Org/Manifest'
    href = 'https://FreeCAD.org/Manifest'
?>
<package format = '1' >
    <!-- . . . -->
</package>

📑 Repository

Folder Purpose
Source Tree of bite sized XSD source files.
Scripts Python script used to create a bundle.
.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
    schematypens = 'HTTPS://FreeCAD.Org/Manifest'
    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

📜 Preview

Bundler Showcase 1


🩹 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.