5 Identifying elements of document (Normative)

5.1 Introduction to fragment specifications

Many references need to point to items smaller than whole documents. In sections 4.7, 4.9 and 4.10 the syntax is provided to create IRI references to subdocument units, such as fragments, components and portions.

The description of these syntaxes include the specification for the name or for the identifier of the component or portion being referred to. In this section we discuss how the name and the identifier of these parts should be created and managed, in case the Manifestation being referred to uses the Akoma Ntoso XML vocabulary.

The Akoma Ntoso XML vocabulary uses three different attributes for the attribution of ids to elements. All of them are optional for basic conformance, and required for higher level conformance. For one of these attributes, GUID , no syntax is prescribed. The two others, eId and wId , have a prescribed syntax in conformance level 2. Therefore, while the use of eIds and wIds is not required for conformance level 1, in conformance level 2 they MUST use the syntax described here IF used.

Non XML-based manifestations that use identifiers SHOULD adopt values for ids that are consistent with that specified in this section.

5.2 Fundamental principles identifiers in Akoma Ntoso

The Akoma Ntoso Naming Convention identifies, in a unique way, all Akoma Ntoso concepts and resources on the Internet and, in general, all collections thereof. These principles and characteristics should be respected in the use of identifiers for such documents:

• Universality : this specification applies to all document types that Akoma Ntoso deals with now or will deal with in the future. It works for amendable parts as well as non-amendable parts, for frequently modified parts as well as never modified parts. It works for original versions, single versions, multiple versions, and chains of versions.

• Proportionality of impact : the approach taken for a rare occurrence does not affect the solutions taken for the more frequent occurrences. It is better for the solution of a rare occurrence to be very convoluted than for the solution to a frequent occurrence to be even only mildly convoluted.

• Uniqueness : the identifier of a part is unique within the document.

• Persistency : the identifier of a part is persistent across versions, i.e., across all expressions of the same work. The persistency refers to the identity of the part, and not of the name or the number (i.e., if a part is moved and renamed the identifier accompanies the part, and does not stay with the number), so that it is possible to track the movement of the part across versions.

• Navigability : the identifier of a part is usable in an IRI reference as the fragment part (after the # character) or as the portion part (after the ~ character), even in hypertext links to a separate document, and the link remains traversable to the right place regardless of what happened to the destination document.

• Self-sufficiency : the identifier of a part is the only information needed to perform the basic operations (in particular, navigation and tracking). Explanatory metadata are always optional so that it is not necessary to deal with tracking in a separate metadata section.

• Contiguity : the identifier of a part is near the part it refers to, e.g., as an attribute to the relevant element [4] .

• Meaningfulness : the identifier of a part expresses, as much as possible, basic facts about its nature, position, or relation to superior and/or neighboring elements that are meaningful to the local tradition.

• Transferability : the identifier of a part is transferable when the part is transferred from a document to another, or from a document type to another. For instance, identifiers of bills are transferable to the identifiers of the corresponding act once the document has been promulgated, and similarly, the identifier of a structure within an amendment proposal, possibly even in an oral discussion reported in a Hansard, is transferable to the identifier of the structure in a new version of the bill. [5]

5.3 Id attributes in the Akoma Ntoso XML vocabulary

There are three different attributes in Akoma Ntoso XML to identify content:

• eId attribute (“E xpression-level” identifier) This is the first and most important identifier. An eId attribute provides uniqueness of an element within a specific Expression. The value of eId is specified as connected to the structural role of the corresponding element. So, it needs to be updated regularly whenever the structural role of the element changes in a new Expression (i.e., if the element is renumbered or changed in nature, e.g., from article to clause).

• wId attribute (“ Work-level ” identifier) This attribute is only needed if the eId is not also a Work-level identifier. It is meant for mapping the identity and position of the same elements in different Expressions and variants of the same Work – wId identifier will be explicitly included when the eId changes from one Expression to another. The value of the wId attribute never changes; it must be the same values for the same elements in all the Expressions of a document. In order to allow this, a master Expression needs to be identified, i.e., the Expression whose eId attribute becomes the references for the wId attribute of all other Expressions.

• GUID attribute ( Globally Unique Identifiers ) This attribute is an application-specific identifier that a local implementation may need to add to elements according to local rules and syntaxes. GUID is not a required attribute. Its use and specification is totally dependent on the representation and storage requirements of the author of the Manifestation. Despite the name, GUID do not even have to be globally unique across documents of the same collection. They are meant as a way to place ids from legacy formats and collections and that are still in use. The usage of GUID attribute has no required syntax and does not impact on compliance with this specification.

5.4 Syntax for eId and wId attributes

Most elements in the Akoma Ntoso XML vocabulary allow two optional attributes, called eId and wId . They are optional for compliance level 1, and are required for compliance levels 2 and above.

The syntax for these attributes is identical and is built in the exact same way, but are based on different elements:

• for the eId attribute, the reference element is the one in the current Expression

• for the wId attribute, the reference element is the one in the master Expression, as specified in section 5.4.

The generic syntax for these attributes is the following:

[prefix “__”] element_ref [“_”number] prefix is a (possibly empty) string providing uniqueness to the remaining part of the identifier, and it is based on the context in which the element appears;

• element_ref is a (required) identifier of the type of the element;
• number is a (possibly empty) representation of the numbering of the element within its context.

5.4.1 Prefix

Frequently elements appear in different parts of the same document with the same number and they need to be identified by the context in which they appear: for instance, a Chapter 2 may exist within both Book I and Book II , and a line 5 most probably exists in every page of some document.

The context is the part of the identifier that provides the required uniqueness. Thus, the context of the two instances of Chapter 2 is Book I or Book II respectively, while the context for each line 5 (i.e., each < eol> element) will be the page number of the page in which it appears (i.e., the immediately preceding < eop> element).

The prefix is a (possibly empty) string providing uniqueness to the remaining part of the identifier, and it is based on the context in which the element appears. In fact, by construction the prefix is the full identifier of the context element .

For example:

• book_I__chp_2 , The prefix part of Chapter 2 within Book I is “ book_I ”, which is the identifier of the element “Book I” that provides the context for the rest of the identifier.

• eop_2__eol_4 The prefix part of the line 5 of page 3 is “ eop_2 ”, which is the identifier of the element between page 2 and page 3 that provides the context for the rest of the identifier .

Composite documents make it more complex to reach uniqueness of identifiers over the whole XML document, since they might be the result of composing individual documents where the same identifiers may exist independently. For instance, an element called section 2 may exist independently in the main component and in an annex of the same document.

The identifier of an element MUST therefore include the full identifier of the context element that guarantees its uniqueness, and it CAN be the identifier of the individual document in a composite document, the identifier of a wrapping element that restarts the numbering, or the identifier of a preceding element that restarts the numbering.

Structures within the < quotedStructure> and < embeddedStructure> elements add the relevant mod identifier before their “natural” identifiers. In a way, < quotedStructure> and < embeddedStructure> act as the context for the contained structures. So for instance if clause 3 of article 15 has an amendment that adds article 4/a to a different act, the identifier of the <quotedStructure> element that contains the new article will be “ art_15__cl_3__mod_1__qstr_1 ”, and the identifier of article 4/a inside it will be “ art_15__cl_3__mod_1__qstr_1__art_4a ”. Of course, automatic systems that create current versions of texts should and will remove the prefix belonging to the modification law and will only keep the identifier “ art_4a ” in the final result.

The following are usual cases of contexts:

• All document classes ( <act>, <bill> , <doc>, etc.) are always contexts. This means that, except particular cases, all numbers restart whenever a new document class is started (e.g., in a composite document each document component has its own local numbering).

• Elements <quotedStructure> and <embeddedStructure> are always contexts, even if they do not force a restart of the numbering, but just a different numbering context within themselves.

• Plain inline elements are never contexts. Exception: element <mod> is always a context.

5.4.2 element_ref

In general, the element_ref part is the full name of the element. There are three exceptions:

1. Some elements share the same element_ref . This happens when the two elements has the common user semantic but are found in different structural contexts. These elements are:

XML elements	element_ref
<list> and <blockList>	list
<intro> and <listIntroduction>	intro
<wrapUp> and <listWrapUp>	wrapup
<body> , <mainBody> , <amendmentBody> , <debateBody> , < judgmentBody>	body

The reason for these elements to have the same element_ref is to reduce the complexity whenever the structures are functionally identical.

2. For some elements, an abbreviation is used. This abbreviation is a well-known shorthand of the full element name that is already used in legal citations. The following is the full list of abbreviations allowed:

XML element	element_ref
<alinea>	al
<amendmentBody>	body
<article>	art
<attachment>	att
<blockList>	list
<chapter>	chp
<citation>	cit
<citations>	cits
<clause>	cl
<component>	cmp
<components>	cmpnts
<componentRef>	cref
<debateBody>	body
<debateSection>	dbsect
<division>	dvs
<documentRef>	dref
<eventRef>	eref
<judgmentBody>	body
<intro>	intro
<list>	list
<listIntroduction>	intro
<listWrapUp>	wrap
<mainBody>	body
<paragraph>	para
<quotedStructure>	qstr
<quotedText>	qtext
<recital>	rec
<recitals>	recs
<section>	sec
<subchapter>	subchp
<subclause>	subcl
<subdivision>	subdvs
<subparagraph>	subpara
<subsection>	subsec
<temporalGroup>	tmpg
<wrapUp>	wrapup

3. For some elements, a string representing some information about the content of the element is used. These elements are:

XML element	element_ref
<TLCConcept>	a label of the concept;
<TLCEvent>	a label of the event;
<TLCLocation>	a label of the location;
<TLCObject>	a label of the object;
<TLCOrganization>	a label of the organization;
<TLCPerson>	a label of the person;
<TLCProcess>	a label of the process;
<TLCReference>	a label of the reference;
<TLCRole>	a label of the role;
<TLCTerm>	a label of the term;
<componentData>	a name for the component;
<keyword>	a label of the keyword;
<component>	depending on the document inside, the identifier can be “annex” or “attachment” or the name of the component , with an explicit number.

5.4.3 Num ber

The number part of an identifier is a (possibly empty) representation of the numbering of the element within its context.

There are three subcases:

1. Globally and locally unique elements:

If the element is necessarily unique within its context, no numbering is used, and therefore there is no number part. For instance, since there is exactly one body in acts and bills, its identifier can be simply “ body ” (or, of course, “ doc_1__body ” in case of a composite document). Analogously, since there is at most one content element inside articles or sections, the identifier of the <content> element of article 12 will be simply “ art_12__content ”.

2. Explicitly numbered elements

An explicitly numbered element has its number determined in the Expression itself in the form of a <num> sub-element. The number part of the identifiers of such elements corresponds to the stripping of all final punctuation, meaningless separations as well as redundant characters in the content of the <num> element. The representation is case-sensitive. For instance, if article 12 contains <num>Art. 11.2 bis</num > then the number part of the identifier will be “ 11-2bis ”. It is the job of the author of the Manifestation to determine whether the numbering expressed in the <num> element is global (i.e., it starts at 1 at the beginning of the document) or local (i.e., it restarts at 1 inside or after every instance of an intermediate element). This is usually made clear within every legal tradition and usually can be established by briefly examining a few or even just one document in its original form. Meaningful separations and punctuation are never stripped. For instance, article -1 (in some jurisdictions it represents a late insertion before article 1) will be “ art_-1 ”.

3. Implicitly numbered elements.

An implicitly numbered element has no <num> sub-element, and its numbering is established by counting the occurrences of similar elements within the same context, always using Arabic numbers. It is the job of the author of the Manifestation to determine whether the best way to count these elements is globally (i.e., starting at 1 at the beginning of the document class) or locally (i.e., restarting at 1 inside or after every instance of an intermediate element). This naming convention provides no rules on this choice, but there are a few common sense approaches. For instance, it is very natural that <eop> elements are globally counted, and <eol> are locally counted by their preceding <eop> element, and as such, the third <eop> element (the one separating the third page from the fourth) has identifier “ eop_3 ” (note no prefix), while the fifteenth end of line after such eop (the one separating the fifteenth line from the sixteenth) will have as identifier “ eop_3__eol_15 ”. On the other hand, <p> elements within a given structure are probably counted locally (as in “third <p> of section 12”). This is not necessarily the immediately containing element (which in this case would be the <content> element), but any containing or preceding element that in the opinion of the author of the Manifestation provides context for the counting. Thus the third <p> of section 12 could reasonably have “ sec_12__p_3 ” as its identifier.

5.5 Usage Rules for “eId” and “wId”

Documents are complex structures. Sometime, it is important to record the fact that the (conceptually) same structure may have different content (e.g., for different languages, different versions or different audiences).

Permanent identifiers are the basic tool to be able to identify the concept of sameness across situations that require different content to be known as really being the same. Unfortunately, relying only on a permanent identifier prevents some common and very useful operations to be performed on documents that present multiple instances of the same structure. For this reason the concepts of Expression identifiers ( eId ) and Work identifiers ( wId ) have been introduced.

5.5.1 Elements That Require an eId Attribute

The use of attribute eId is optional for conformance level 1, and required for conformance level 2. If attribute eId is used at all, then it MUST be used according to the syntax defined in section 5.4. If attribute eId is used in a document, then it is required for all elements that use or include attribute group idreq , and optional in all elements using or including attribute group idfac .

5.5.2 The Master Expression

1. Whether an XML document does or does not have Work-level identifiers is NOT a decision of the author of the Manifestation, but a characteristic of the nature of the document. In fact, if an XML document does NOT have Work-level identifiers, then it is assumed that:

(a) it is the Master Expression (the one whose Expression-level identifiers will be used as a map for the Work-level identifiers of all the other expressions) and

(b) its Work-level identifiers are the same as Expression-level identifiers.

If this is NOT the Master Expression, then the Work-level identifiers NEED to be present as soon as they become different from the corresponding Expression-level Identifiers.

Master Expressions are necessarily the FIRST (or the ONLY) time-related versions of a document that either is intrinsically MONOLINGUAL or is expressed in the MASTER LANGUAGE, which is country- and jurisdiction- dependent and may even not exist (as in EU).

A Manifestation author must know whether the document being marked up should be considered as the Master Expression for a Work or not.

The Expression-level identifiers use a semantic naming convention based on the structure of their Expression. The Work-level identifiers use a semantic naming convention based on the structure of their Master Expression, if one exists, or of a conceptual Ur-Expression, if none exists.

5.5.3 wId Attribute Use Cases

The decision to use two separate identifiers is to avoid the risk of collapsing two potentially very different meanings of “identification” into just one identifier: the identifier of the right place ( the one that I mean now when I use this identifier) and the identifier of the same place ( the one that had such an identifier in a different version or in a different variant of this document ).

In fact there are really two identifiers at work: one has the purpose of matching the evolving nature of the fragment with respect to the internal structure of the document and the other must guarantee the persistency of the identity of the fragment across versions and variants. They are usually the same, and diverge only when one of the four following situations occur:

1. In multilingual works, the concurrence of multiple similarly named structures in multiple expressions, say article 2 in the French version of a document and section 2 in the English version of the same document, both referring to the same conceptual structure. A first subcase of this situation is when a master language can be identified, which provides a clear Master Expression, and a second subcase is when no master language is provided (e.g., in European legislation), so that no Master Expression exists.

2. In a multi-version file, the co-occurrence of two similarly named structures from two versions, say article 2 in the past version and article 2 in the current version, both contained in the same (multi-version) Manifestation.

3. In a modification act, the concurrence of two similarly named structures of the amending and of the amended document, say I am amending art.2 of the amended act, and of course an art.2 that exists already somewhere else in the amending act.

4. In a chain of versions, the requirement to renumber a few structures that completely desynchronizes the old identification mechanisms from the new one, e.g., article 2 is from now on known as article 15. Such renumbering is frequent in bills, and rare in acts. But external references to bills are mainly static (i.e., they refer to a specific version of a bill), while external references to acts are often dynamic (i.e., they refer to any of a number of versions depending on the nature of the quest).

• First use case – renumbering in bills: an approved amendment A inserts a new article between art.1 and art.2 of version 1 of bill B. Because of this decision, art.2 is known in version 2 of B as art.3, art.3 is known as art.4, etc.

• Second use case – renumbering in acts: while act Y is in version 1, on date D1 act X makes a (dynamic) reference to art.2 of act Y. Subsequently, on date D2, act Y gets renumbered, and in version 2 art.2 becomes art.15 and a new art.2 is introduced in its stead. Subsequently, on date 3, act W makes a (dynamic) reference to art.15 of act Y (which is the new name for art.2) and on date D4 act Z makes a reference to art.2 of act Y (which is a new article that did not exist previously).

Given the above-mentioned principles, the natural solution is to have two identifiers to deal with. One is persistent and associated to the Work, while the other is evolving in time and associated to the Expression. Whenever the persistent identifier and the evolving identifier do not differ, only one of them is specified in the document, but when they differ, then the evolving identifier follows the structure of the Expression, while the permanent identifier is anchored to the structure of one specific Expression, called Master Expression , which is considered as the fundamental Expression for the permanent identification of fragments.

When a situation occurs that requires the two identifiers to differ from each other, such as one of the above-mentioned situations 1, 2, 3 or 4, then the eId attribute is set to reflect the new role and number of the element in the structure, while the wId attribute is added and set to reflect the identity that such fragment had, has or would have in the Master Expression. Thus, after any change in the document, the Work-level identifier ( wId ) is added and never changes, and the Expression identifier ( eId ) keeps on being updated according to the condition of the Expression it belongs to.

Tracking is always based on the wId , navigation is always based on the identifier that was the eId at the moment, and transfer is always based on the eId . If the evolving identifier changes in time more than once, the Akoma Ntoso vocabulary provides the <mapping> metadata to hold a complete map in time of the relationships between the persistent identifier wId and each of the evolving identifiers eId .

For instance, we can describe the four situations as follows.

5.5.3.1 Multi-Lingual Document

5.5.3.1.1 Subcase a

Two expressions exist in two different languages. One is in the master, or default language, and the other is an additional variant in a different language. As such, the version in the default language is the master Expression, and the other version uses the master Expression’s identifiers as wIds .

Representing the fact that article 2 in the secondary variant contains the same text as section 2 in the master Expression is performed as follows:

Master Expression (e.g., in English)

<section eId=”sec_2”>

<num>2</num>

<content>

<p>Some text in English</p>

</content>

</section>

Variant (e.g., in French)

<art wId=”sec_2” eId=”art_2”>

<num>2</num>

<content>

<p>Du texte en Français</p>

</content>

</art>

5.5.3.1.2 Subcase b

Two expressions exist in two different languages, but neither can be determined as the default or master language. This happens, for instance, in European legislation. As such, the master Expression does not exist in a concrete Expression, but must be determined abstractly (it could be called an UR-Expression ), and both versions uses the UR-Expression’s identifiers as wIds .

How do we represent that article 2 in the French version contains the same text as section 2 in the English version, and neither is the master Expression?:

Variant (e.g., in English)

<section wId=”elm_2” eId=”sec_2”>

<num>2</num>

<content>

<p>Some text in English</p>

</content>

</section>

Variant (e.g., in French)

<art wId=”elm_2” eId=”art_2”>

<num>2</num>

<content>

<p>Du texte en Français</p>

</content>

</art>

5.5.3.2 Multi-Version Document

In a multi-version file, two similarly named structures exist coming from two different versions, say article 2 in the past version and article 2 in the current version, both must be placed in the same (multi-version) Manifestation.

The “default” structure (e.g., the current version) uses a plain eId identifier; the “secondary” structure (e.g., the past version) uses a modified eId identifier and is associated to the default structure via the wId identifier.

<art eId=“art_2“>

<num>2</num>

<content>

<p>New version of art.2</p>

</content>

</art>

<art wId=“art_2“ eId=“art_2v1“>

<num>2</num>

<content>

<p>Old version of art.2</p>

</content>

</art>

In this situation it is assumed that the expected default behavior when traversing documents is to go to the newer version of the document, and if the navigation mechanism knows something more specific about the needs of the user, it would lead to the older version of the fragment instead.

5.5.3.3 Amending Act

The structured content uses wId as a suggestion of the identifier that the structure will have in the new version of the amended document:

<mod eId=”mod_1”>

Art. 5 is changed as follows:

<quotedStructure eId=”mod_1__qstr_1”>

<art eId=”mod_1__qsrt_1__art_5” wId=”art_5”>

...

</art>

</quotedStructure>

</mod>

5.5.3.4 Renumbering of a Bill

The first version of the bill has simple identifiers:

<article eId=”art_1”>

<num>1</num>

<content><p>Originally article 1</p></content>

</article>

<article eId= ”art_2 ”>

<num>2</num>

<content><p>Originally article 2</p></content>

</article>

<article eId=”art_3”>

<num>3</num>

<content><p>Originally article 3</p></content>

</article>

In the second version of the bill a new article 2 was inserted, which generated a renumbering of the subsequent articles. This version uses identifiers to specify the original identifiers, regardless of the position, and uses eId to specify the identifier each article should have if this were a new document.

<article eId=”art_1”>

<num>1</num>

<content><p>Originally article 1</p></content>

</article>

<article eId= ”art_2 ”>

<num>2</num>

<content><p>New article 2</p></content>

</article>

<article wId=”art_2” eId=”art_3”>

<num>3</num>

<content><p>Originally article 2</p></content>

</article>

<article wId=”art_3” eId=”art_4”>

<num>4</num>

<content><p>Originally article 3</p></content>

</article>

Since bills mostly receive static references, and since static references always include the version number, it is always very clear what refers to what – references to art_2 in version 1 of the bill will lead to the same article as references to art_3 in version 2, while references to art_2 in version 2 will lead to the newly inserted article.

5.5.3.5 Renumbering of Acts

Suppose that, while act Y is in version 1, on date D1 act X makes a (Work-level) reference to art.2 of act Y. Subsequently, on date D2, act Y gets renumbered, and in version 2 art.2 becomes art.15 and a new art.2 is introduced in its stead. Subsequently, on date 3, act W makes a (dynamic) reference to art.15 of act Y (which is the new name for art.2) and on date D4 act Z makes a reference to art.2 of act Y (which is a new article that did not exist previously)”.

The structure of the document is similar to the previous example. Then the following facts would be true [6] :

• In act X the Work-level reference to art.2 of act Y would be is Y/ ~ art_2 . This corresponds to the structure that in version 1 had eId=”art_2”.

• In act W the Work-level reference to art.15 of act Y is Y/ ~ art_15 . This corresponds to the same structure that in version 2 had eId=”art_15” and wId=”art_2”

• In act Z the Work-level reference to art.2 of act Y is Y/ ~ art_2 . This corresponds to the structure that in version 2 had eId=”art_2” and no wId.

When accessing one of these references, the date of the source Expression (i.e., the one containing the reference must be compared with the date of the Expression of the destination document. If the date of the source is before the date of the destination, then the wId must be used for navigation. Otherwise the eId must be used.