Add XSDs for Format and Types.ps1xml files #7832
Conversation
SteveL-MSFT
left a comment
SteveL-MSFT
left a comment
There was a problem hiding this comment.
Great contribution! Didn't review the schema itself in detail, but overall it looks fine. We can address as bugs if issues are reported.
src/Schemas/Format.xsd
Outdated
There was a problem hiding this comment.
.NET Framework is specifically not .NET Core. Since this applies to both, I would suggest just changing all occurrences of .NET Framework to simply .NET
|
@SteveL-MSFT as mentioned, all documentation is 1:1 unmodified from the Format XML schema reference: https://docs.microsoft.com/en-us/powershell/developer/format/format-schema-xml-reference I can easily update these schemas with new documentation by running the script again, but I don't think it makes sense to apply fixes to the documentation only to the schema? Most people will probably read the docs online. We should decide which one is the source of truth |
|
@felixfbecker I submitted MicrosoftDocs/PowerShell-Docs#2943 to fix the online documentation. I'm ok leaving the second comment until we add more to the schema. You can wait for that to be merged and rerun your script. |
|
I like the idea of a single source of truth. Maybe we should include your script in this PR so anyone can update the schemas from the docs. |
|
In an ideal world the docs would rather be generated from the schema (there are probably tools out there that do this). Parsing markdown with regexes is really hacky so I'm not sure if we want to rely on that. The current docs are not very well-structured in general so generating them differently would likely do them good. @SteveL-MSFT your change actually didn't affect my script because it only updated the table of contents, I sent a follow-up PR: MicrosoftDocs/PowerShell-Docs#2944 |
|
My script also detected many cases in the docs where the schema you gave me @lzybkr directly contradicted the reference docs, e.g. an explicit |
|
Generating the markdown does sound easier. It doesn't need to be in this PR, but I do like that idea. And I don't see ever truly having a single source of truth without generating PowerShell's parser from the xsd - but having done that once before, we'd want the generated code to be much better than what I saw a few years ago. |
|
@lzybkr @SteveL-MSFT updated schemas with latest docs, should be good to merge now. |
src/Schemas/Types.xsd
Outdated
There was a problem hiding this comment.
Please add a trailing newline at the end
|
@felixfbecker please rebase off master to pick up fixes causing the CI failures |
These can be used for autocompletion and validation in editors
|
@SteveL-MSFT all green ✅ |
|
@felixfbecker Sorry for the delay. I will review this today. |
|
@felixfbecker Thanks for your contribution! |
These can be used for autocompletion and validation in editors
4 participants
PR Summary
As proposed in #7749.
These can be used for autocompletion and validation in editors like VS Code. It makes writing Format and Types files so much more pleasant to write.
The schemas were taken from #7749 but extended with documentation parsed from the reference docs markdown with a script.
Question: Should this be hosted on http://schemas.microsoft.com/ like the MAML schemas? How do the MAML schemas get published there?
cc @lzybkr @SteveL-MSFT
PR Checklist
.h,.cpp,.cs,.ps1and.psm1files have the correct copyright headerWIP:to the beginning of the title and remove the prefix when the PR is ready.[feature]if the change is significant or affects feature tests