The xs:annotation element can be used in XML schemas for supplying structured meta information (xs:documentation for people, xs:appinfo for machines). Is there something similar that would allow adding such information to instance documents, or are we restricted to stuffing things into unstructured XML comments?

BACKGROUND/RATIONALE

The use case is adding structured information to instance documents that represent test cases for a FHIR validator. Human readers need to be informed about the intent of a given test/document, and the test framework needs to know which specific error or warning it is supposed to look for among the many errors/warnings that may result from validating this document (since many errors result in oodles of follow-on errors, which often get output long before the actual error that caused the validator to panic).

Eventually there will be thousands of test cases, each with several test steps/documents, so that coding the relevant information into file/directory names is simply not feasible. On the other hand I want to keep the test document and its meta information together, instead of spreading the information over multiple files.

Adding a companion file to each document would double the number of files and it would allow the two files in a pair to diverge. The same goes for using the filenames as keys for retrieving meta information from some meta file/database. Having a meta file per directory would have some advantages for humans, but this could just as easily be obtained by gathering the meta info from the files on the fly (or as a build step).

If a test document contains the necessary meta data then things are easier to manage overall. For example, I could move a file to a subdirectory should_fail_but_passes until some problem is resolved, without changing the file and/or having to edit a meta file/database.

CodePudding user response：

You could use processing-instructions. A processing instruction has two components, a target and optional content:

https://en.wikipedia.org/wiki/Processing_Instruction

An XML processing instruction is enclosed within <? and ?>, and contains a target and optionally some content, which is the node value, that cannot contain the sequence ?>.

<?PITarget PIContent?>

The advantage of PIs are that it is outside of the content markup and XSD validation, and most default rendering ignores it.

It provides a convenient way to use the PI target as a "key" for lookup and categorization and then the content can have whatever you decide.

So, if you had a processing instruction in your XML:

<?expectedError MissingRequiredElementException?>

you could access it with by the target name "expectedError":

//processing-instruction("expectedError")