Dnn Manifest XSD Schema would be nice

[valadas]

Description of problem

Currently the dnn manifest specs are:

• Only documented in a handful of outdated blog posts
• Described (also outdated) in this old documentation page https://www.dnnsoftware.com/docs/developers/extensions/dnn-manifest-schema.html
• The new documentation project is not yet online and a quick search for "manifest" returned nothing

Description of solution

I think understanding the manifest is the first step to understand what makes some piece of code become a Dnn extension. I am working on creating and XSD file (XML Schema Definition). If we include this file in this repository and have both the EVS and the Dnn installer validate manifests against it, it would force us to maintain the file (one source of truth), xsd also allows self-documentation to quickly explain what is what. Referencing this xsd from a manifest should provide intellisence (code completion) in Visual Studio and many other popular editors. This could also be used as the source of truth by other tools like module templates and generators.

Description of alternatives considered

Watch the bachelor with a few bottles of whisky.

Additional context

I am logging here the assumptions I am making right now from the various information I can find, please correct me where I am wrong. When I have something roughly usable, I will submit a pull request where we can do the final fine-tuning.

Assumptions / Questions about extension types

1. Connector: I did not find any documentation on this and no matching installer for it here https://github.com/dnnsoftware/Dnn.Platform/tree/development/DNN%20Platform/Library/Services/Installer/Installers from what I can see it is because there is nothing special about that package type and it just uses the Generic Component types.
2. DashboardControl, this was removed with Dnn 9, should we still keep it in the xsd because the installer would not crash if it is there? or have multiple versions of the xsd or just keep one version of the xsd but not put this pakage type in?
3. PersonaBar: I have not found much documentation about the manifest but we have plenty of examples available, I should be fine documenting that one.

Versioning

If there are plans on changing stuff regarding the installer or regarding the supported extension types, should we have a dnn-manifest-v9.xsd and then a dnn-manifest-v10.xsd and so on so we can have different rules? Or XSD 1.1 allows having in a single file different rules depending on a parent parameter (in our case it could be the minimum target version), but I think most Microsoft tools only support XSD 1.0

Any suggestions are welcome.

[EPTamminga]

Great suggestion. If you need a tester, ping me.

[bdukes]

Regarding versioning and DashboardControl, I think we'll need a history of XSD files (hopefully no more than one per major version)

[mitchelsellers]

I would echo @bdukes. Based on the new Semantic versioning decision, we should not be introducing new features that would require Manifest Schema changes between major releases, so at most we would have V10, V9, etc.

Going forward, there will be changes, exactly how much, or when, is a bit unclear.

[valadas]

Ok, I think I will make a DnnManifest8.xsd and a DnnManifest9.xsd, anyone still targets Dnn7 on new projects, I guess not ?

Now, hosting it? We need a url to reference in the modules manifests, we can host it here on github in the repository, in which case the url would be something like https://raw.githubcontent.com/dnnsoftware/Dnn.Platform/development/Build/Manifests/DnnManifest9.xsd it is a bit long but we have control over it quickly. Or https://dnnsoftware.com/DnnManifest9.xsd much shorter but needs manual steps and coordination to deploy. Or do you have other ideas, something easy to remember but under our control would be nice...

[ohine]

I don't think we need a dnn8 manifest schema created, mainly due to security issues. We should focus on dnn 9.2 and up.

[WillStrohl]

I, for one, would not recommend the alternative solution suggested. 🤢

[WillStrohl]

Also, while it would indeed be "nice" to have schema's for prior releases, it may indeed be good idea to only focus on 9.xx and newer to have at least one more reason to encourage upgrades. I wouldn't recommend backwards compatibility for things like this in most cases. Specifically, Oliver cited security as a concern, and I agree if not for any other reason.

[valadas]

The idea of having them for previous versions is that I would like to have EVS use that as a first step and warn about stuff that does not match the XSD, I guess there are probably still a lot of module vendors that have modules still Dnn 8 compatible being maintained... Maybe not going back too far but I would include Dnn8. Plus I think there would be only 2 small differences between 8 and 9 extensions support (persona bar and dashboard) so it would not be a huge undertaking to make the two.

[bdukes]

There would only be additions between 8 & 9, so the DNN 9 XSD wouldn't reject a valid DNN 8 XML file. The only concern would be a module that targets DNN 8 but uses a feature introduced later.

[EPTamminga]

If there is a small difference between a DNN8 and DNN9 manifest, it would be easy to create a DNN8 XSD as well. That would help to validate DNN8 targeted extensions.

[valadas]

Hmm, actually, the more I look at it and the more it will not really make a big difference, the package types are extensible ( you can have a package type for your own modules extensions ), so we cannot be too strict on what types of packages are considered valid. I guess that part will need to be just a regex for spacing and invalid characters only...

[valadas]

I have tried to accomplish this but because the manifest is extensible and because the extension type is a property instead of a node type, it does not look like we can rely on xsd unless we have multiple and then that would limit is usefulness to only packages with a singly type of of extension. So for the time being I think this should be abandoned and I am closing the issue.