> If I've learned one thing as a systems engineer, it's that documenting the *rationale* for requirements provides key context above and beyond even "perfectly" formulated language in a specification.
This is a hobby horse of mine, for general purpose code: I think the school of thought (which I associate with Rob Pike) that the code itself is the best (or only viable) documentation is impossible and reckless.
The idea only works at the top level (where you name by intent) and the low level (where you name by data structure, functionality, algorithm); for shallow code that is OK, but as soon as you get long and generified call or type chains the "what and why" of names is lost in "how". The code things in between the top and bottom can often be named by intent or operation and you have to choose; and if you name by intent they become confusing to be used in other situations, and if you name by operation you lose track of the purpose or business requirement. (IDEs help a lot, of course.)
For Schemas, there is a kinda-equivalent issue that if you make a schema with reusable standard components, a user needs to know the context to readily know what is going on: but we have no standard way to tell which ancestor's name or value is relevant for the user. For example, take the (too shallow to be very convincing)
<dataset>
<BillingAddress>
<set>
<po-box >22224<po-box>
<suburb code="2009">Pyrmont</suburb>
<city >Sydney</city>
<country code="AU">Kangaland</country>
</set>
</BillingAddress>
<OfficeAddress>
<set>
<street >2/73 Union St</street>
<suburb code="2009">Pyrmont</suburb>
<city >Sydney</city>
<country code="AU">Australia</country>
</set>
</OfficeAddress>
</dataset>
A validator might say the horrid error message "Unexpected value for country: Kangaland" or if using assertions the better "A country's name should be on the approved list (at file countries.xml): /dataset/BillingOffice/set/country has unexpected value 'Kangaland'." But the "dataset" and "set" are just noise: the info that the user needs for comprehension is just /*/BillingOffice//country
(As a related case, take Java NullPointerException. It was only Java 14 that took the step of providing in the exception message information about what code triggered the exception: but it doesn't tell what the field name was when it was first created or assigned null way up the call chain, which you need to know. (Of course, annotations can reduce the effect of the problem, by static tests.))
So, in summary, there is a general unsolved problem for markup and programming languages, of how to know which names up the ancestor or call chain are generic/operational/functional and which relate to intent/"semantics"/business-requirements. And without that, it is not possible to reliably avoid generating noisy, confusing or inadequate error messages.
In Schematron, I guess you could do something like
<sch:diagnostic name="showSecondLevelContext">
<sch:value-of select="concat('/*/', (ancestor::*)[2]/name(), '//', ./name()"/>
has unexpected value <sch:value-of select="."/>
</sch:diagnostic>
but a voice nags me that this should be information in the markup somehow: for example an internal prolog declaration
<!ATTLIST BillingOffice isGoodSemanticContext CDATA "yes" #FIXED>
or
<?semanticElements BillingOffice PostalAddress ?>
I guess it may comes down to whether you think a schema is data to drive an algorithm, or instead is data to participate in protocols allowing an effective conversation between multiple humans and systems.
Cheers
Rick
