Dear Geert,
many thanks for your email that underlines very interesting issues.
Below is the reply from Fabio Vitali (thanks!) on behalf of LegalDocML-TC.
The purpose of LegalDocML-TC is to design, promote, disseminate the Akoma Ntoso standard respecting the OASIS regulation and support its correct use. LegalDocML-TC is not intended to provide consultancy, so our action is limited to the scope of LegalDocML-TC.
Best regards,
LegalDocML-TC
===========
[the original was HTML formatted and the examples came out really bad, so
here we go again, plain text]
Dear list members,
I am searching for some advice for using indirection in identification
metadata
I generally like the approach as taken for FRBRauthor The semantics of the author role has an indirection allowing me to be very
precise
<FRBRauthor href="" as="#author"/>
and
<TLCRole eId="author"
href= "" href="https://my.ontology.com/vocabulary/author#author">"https://my.ontology.com/vocabulary/author#author" showAs="Author"/>
This is very good, except for the URI you have chosen as the value of the href attribute.
There is an expectation that the href attribute of the TLC elements in the meta/references block contain URI according to the Akoma Ntoso Naming Convention, section 4.11. Although not mandated by the naming convention for political reasons, I strongly suggest to use the syntax proposed, starting if "/akn/ontology/[class]"Â , e.g.: /akn/ontology/person/it.fabio.vitali
I would love the same indirection (allowing me to be very precise) on other
metadata too
1. Languages
I have my own language scheme since I need to express documents in Old Dutch
for instance
I have some languages that sit outside the scope of ISO 639-2 alpha-3
I saw that the EU proposes a technique for doing so as expressed in AKN4EU
modelling guidelines
<FRBRlanguage language="od"/>
<TLCReference name="language"
href="" href="https://my.ontology.com/vocabulary/language#old_dutch">"https://my.ontology.com/vocabulary/language#old_dutch" showAs="od"/>
mandating the @showAs to have the same value as the @language attribute in
the FRBRlanguage and mandating the @name to be 'language'
That would work for me. Though I wonder if that is a common practice
and I also wonder how that would work with @fromLanguage in a
FRBRtranslation
Looking for guidance here, either confirmation that AKN4EU is using a best
practice, or proposing some alternatives
(I must admit I am not too thrilled about the explicit mandate of using ISO
639-2 alpha-3)
The language codes used in the Akoma Ntoso Naming Convention are always three letter long. The documentation says that "For an Akoma Ntoso XML representation, this value MUST correspond to the content of the first element <FRBRlanguage> in the metadata section." Thus viceversa we expect that the value for the <FRBRLanguage> element to be three letters long, too.
I understand that using ISO 639-2 Alpha-3 might create a problem for ancient languages, so I think we should find the best compromise given our options.
ISO 639-2 alpha-3 lists three codes containing the word "dutch":
Dutch, Middle (ca. 1050â1350)Â - code dum
Dutch; FlemishÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ - code nld
Dutch; FlemishÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ - code dut
I understand that both nld and dut refer to the same language, which is modern Dutch (just like ger and deu both refer to modern German).
I also understand that you are not satisfy with Middle Dutch (dum) but are looking for something more precise.
"ISO 639-3 extends the ISO 639-2 alpha-3 codes with an aim to cover all known natural languages. The extended language coverage was based primarily on the language codes used in the Ethnologue (volumes 10â14) published by SIL International, which is now the registration authority for ISO 639-3. It provides an enumeration of languages as complete as possible, including living and extinct, ancient and constructed, major and minor, written and unwritten. However, it does not include reconstructed languages such as Proto-Indo-European." (from https://en.wikipedia.org/wiki/ISO_639-3)
Since 639-3 is an extension of 639-2, there is no chance of code clashes, so as a local choice, I see it possible to specify a 639-3 three letter code instead. I think it is appropriate that, in a future release of the Akoma Ntoso Naming Convention, we explicitly list this as an escape route for those language that fall out of the scope of 639-2. Since 639-3 contains 7893 different codes as of 2021, while 639-2 has less than 500, I find it unlikely that we explicitly switch to 639-3 even though all existing codes would still work.
Anyway, for such odd cases using 639-3 could be a useful workaround. In the current list of 639-3 I see six codes mentioning the word dutch:
[brc] Berbice Creole Dutch
[dse] Dutch Sign Language
[dum] Middle Dutch (ca. 1050-1350)
[nld] Dutch
[odt] Old Dutch
[skw] Skepi Creole Dutch
From my point of view, using "odt" would be acceptable. Not "od", though.
In addition, the choice to add a TLReference whose eId is not explicitly mentioned anywhere in the document is not forbidden. The approach you show will hardly be mandated, but if there is a community of practices that adopts it I am fine with it. Of course the same issue about the form of the href attribute applies here, too.
2. Format
Same (sort of) applies to FRBRformat
I see everybody seems to use
<FRBRformat value="xml"/>
which makes kind of sense.
However, I want to be more precise (I do have multiple XML variant
manifestations)
Again, some indirection would help
<FRBRformat value="xml"/>
and
<TLCReference name="format"
href="" href="https://my.ontology.com/vocabulary/user-format/xml">"https://my.ontology.com/vocabulary/user-format/xml" showAs="xml"/>
Is that a common way to do so? Are there better alternatives?
I don't understand the need to identify a specific type of XML (there are basic two versions of XML, 1.0 and 1.1, and their differences are hardly relevant anywhere. On the other hand, you may want to provide information about the specific XML vocabulary adopted, which is a different thing altogether.
The Akoma Ntoso Naming Convention specifies that the data format is a "unique three or four letter extension signifying the data format in which the Manifestation is drafted (required). For instance, such extension can be âpdfâ for PDF, âdocâ or âdocxâ for MS Word, âhtmâ or âhtmlâ for HTML âxmlâ for an XML Manifestation, or âaknâ for the package of all documents including XML versions of the main document(s) according to the Akoma Ntoso vocabulary. For an Akoma Ntoso XML representation, this value MUST correspond to the content of element <FRBRformat> in the <FRBRManifestation> section of the metadata."
Correspondingly the FRBRformat element must specify a three or four letter string that can be used in the URI. The whole purpose of this is to allow the server to specify automatically the Content-Type of the response when delivering a document, thus itmust be easily mapped to a MIME content type such as text/xml.
If you need to specify additional information about the vocabulary (e.g., that it is Akoma Ntoso 3.0, for instance), the Naming Convention specifies another bits of the manifestation URI, after the manifestation date: "Any additional markup-related annotation (e.g., the existence of multiple versions or of annotations.) (optional)". True, there is no corresponding element in the FRBRManifestation block, BUT <FRBRFormat> allows the attribute "refersTo" which was designed exactly for this purpose.
Thus what I would write would be something like the following:
<FRBRformat value="xml" refersTo="#AKN3.0"/>
<TLCConcept name="dataFormat" eId="AKN3.0" href="" showAs="XML Akoma Ntoso 3.0"/>
I hope this satisfies you.
3. Dates
<FRBRdate date="1967-05-08" name="onto:birthday"/>
I want to indicate to the user what the semantics are for onto:birthday
I could do so by adding an XML namespace binding "onto" to the ontology
namespace
So implicitly I am clear enough about how the onto:birthday should be
understood
(assuming the user that wants to know, expands the value of @name into a
full qualified name and check the expanded uri to the ontology,
I would have https://my.ontology.com/vocabulary/date/birthday dereferenced
for information
xmlns: href="">"https://my.ontology.com/vocabulary/date/"
<FRBRdate date="1967-05-08" name="onto:birthday"/>
In case I want to be more precise and not assume the xml namespace binding
would be used for uri expansion.
<TLCReference name="date"
href="" href="https://my.ontology.com/vocabulary/date/birthday">"https://my.ontology.com/vocabulary/date/birthday"
showAs="onto:birthday"/>
Would that then be an acceptable way of expressing that semantics better?
The refersTo attribute which I used before was invented exactly for this purpose. I just noticed that it has not been added to FRBRDate, which is disgraceful, and I promise it will be added in the next release.
In the meantime you can either add refersTo yourself or use name. To add it yourself, look inside akomaNtoso30.xsd for the following block:
ÂÂ <xsd:element name="FRBRdate">
ÂÂÂÂÂ <xsd:complexType>
ÂÂÂÂÂÂÂÂ <xsd:complexContent>
ÂÂÂÂÂÂÂÂÂÂÂ <xsd:extension base="metaopt">
ÂÂÂÂÂÂÂÂÂÂÂÂÂÂ <xsd:attributeGroup ref="date"/>
ÂÂÂÂÂÂÂÂÂÂÂÂÂÂ <xsd:attributeGroup ref="name"/>
ÂÂÂÂÂÂÂÂÂÂÂ </xsd:extension>
ÂÂÂÂ ÂÂÂÂ</xsd:complexContent>
ÂÂÂÂÂ </xsd:complexType>
ÂÂ </xsd:element>
and add just a line as follows:
ÂÂ <xsd:element name="FRBRdate">
ÂÂÂÂÂ <xsd:complexType>
ÂÂÂÂÂÂÂÂ <xsd:complexContent>
ÂÂÂÂÂÂÂÂÂÂÂ <xsd:extension base="metaopt">
ÂÂÂÂÂÂÂÂÂÂÂÂÂÂ <xsd:attributeGroup ref="date"/>
ÂÂÂÂÂÂÂÂÂÂÂÂÂÂ <xsd:attributeGroup ref="name"/>
ÂÂÂÂÂÂÂÂÂÂÂÂÂÂ <xsd:attributeGroup ref="refers"/>
ÂÂÂÂÂÂÂÂÂÂÂ </xsd:extension>
ÂÂÂÂÂÂÂÂ </xsd:complexContent>
ÂÂÂÂÂ </xsd:complexType>
ÂÂ </xsd:element>
Then you can use 'refersTo' (or if you dare not, 'name') as follows:
<FRBRdate date="1967-05-08" refersTo="#birthday"/>
<TLCConcept eId="birthday" href="" showAs="birthday"/>
[the original was HTML formatted and the examples came out really bad, so
here we go again, plain text]
Dear list members,
I am searching for some advice for using indirection in identification
metadata
I generally like the approach as taken for FRBRauthor
The semantics of the author role has an indirection allowing me to be very
precise
<FRBRauthor href="" as="#author"/>
and
<TLCRole eId="author"
href="" href="https://my.ontology.com/vocabulary/author#author">"https://my.ontology.com/vocabulary/author#author" showAs="Author"/>
I would love the same indirection (allowing me to be very precise) on other
metadata too
1. Languages
I have my own language scheme since I need to express documents in Old Dutch
for instance
I have some languages that sit outside the scope of ISO 639-2 alpha-3
I saw that the EU proposes a technique for doing so as expressed in AKN4EU
modelling guidelines
<FRBRlanguage language="od"/>
<TLCReference name="language"
href="" href="https://my.ontology.com/vocabulary/language#old_dutch">"https://my.ontology.com/vocabulary/language#old_dutch" showAs="od"/>
mandating the @showAs to have the same value as the @language attribute in
the FRBRlanguage and mandating the @name to be 'language'
That would work for me. Though I wonder if that is a common practice
and I also wonder how that would work with @fromLanguage in a
FRBRtranslation
Looking for guidance here, either confirmation that AKN4EU is using a best
practice, or proposing some alternatives
(I must admit I am not too thrilled about the explicit mandate of using ISO
639-2 alpha-3)
2. Format
Same (sort of) applies to FRBRformat
I see everybody seems to use
<FRBRformat value="xml"/>
which makes kind of sense.
However, I want to be more precise (I do have multiple XML variant
manifestations)
Again, some indirection would help
<FRBRformat value="xml"/>
and
<TLCReference name="format"
href="" href="https://my.ontology.com/vocabulary/user-format/xml">"https://my.ontology.com/vocabulary/user-format/xml" showAs="xml"/>
Is that a common way to do so? Are there better alternatives?
3. Dates
<FRBRdate date="1967-05-08" name="onto:birthday"/>
I want to indicate to the user what the semantics are for onto:birthday
I could do so by adding an XML namespace binding "onto" to the ontology
namespace
So implicitly I am clear enough about how the onto:birthday should be
understood
(assuming the user that wants to know, expands the value of @name into a
full qualified name and check the expanded uri to the ontology,
I would have https://my.ontology.com/vocabulary/date/birthday dereferenced
for information
xmlns: href="">"https://my.ontology.com/vocabulary/date/"
<FRBRdate date="1967-05-08" name="onto:birthday"/>
In case I want to be more precise and not assume the xml namespace binding
would be used for uri expansion.
<TLCReference name="date"
href="" href="https://my.ontology.com/vocabulary/date/birthday">"https://my.ontology.com/vocabulary/date/birthday"
showAs="onto:birthday"/>
Would that then be an acceptable way of expressing that semantics better?
Very happy to hear your views,
Thanks in advance
Geert Bormans, C-Moria