Editorial Update/XMetaL and XML tagging
Introduction to XML Tagging
Electronic Legislation is edited using XML, (Extensible Markup Language), which enables the content of a document to be separated from the structure and it’s formatting. We use XMetaL to edit the XML.
It is the XML Tagging Structure, on which the legislation data is set, which enables it to be edited electronically.
For example, in a paper hardcopy version of legislation, the text to a heading would be highlighted by the boldness and size of the font, i.e. The Heading
In XML, the heading is enclosed by tags which describe the content,
i.e. <heading>the heading</heading>
The tags, denoted as grey arrows making them distinguishable from the text, will always come in pairs with an opening tag and a closing tag - (identified with a forward slash at the end), see below.
Tagging Hierarchies
The tagging structure in legislation is based upon a strict hierarchical structure.
For example, in relation to a section which includes commentary annotations, the ukl:Fragment “open” tag would be the first tag. In primary legislation this would be followed by the ukl:Primary tag. Its “closing” tag, /ukl:Primary, would be the last tag within the provision, (followed by any commentary annotations). See below.
Set within this outer ‘shell’ of tagging would be an ordered sequence of open and closing tags.
The sequence of tagging on the next page for a typical provision in primary legislation broadly follows the illustrated screen shot of the provision above. (Note the forward slash / denotes closing tags);
ukl:Fragment
ukl:Primary
ukl:P1group
ukl:Title
/ukl:Title
ukl:P1
ukl:Pnumber
/ukl:Pnumber
ukl:P1para
ukl:Text
/ukl:Text
/ukl:P1para
/ukl:P1
/ukl:P1group
/ukl:Primary
/ukl:Fragment
The same hierarchical tagging logic applies also to secondary legislation where instead of a uk:Primary tag following the ukl:Fragment tag at the beginning it is instead followed by a ukl:Secondary tag. These pairs of two tags form the outer shell of the provision as their accompanying closing tags will dovetail the tagging sequence by being also the last two closing tags within the provision.
This format is in much the same tagging order as the primary provision example previously illustrated.
The screenshot below is part of a secondary provision which also includes sub-provisions and sub-sub-provisions.
By following the screenshot example above you can identify that set within this provision are sub-provisions i.e. (a) and (b). They are set upon a structure of ukl:P3 tagging.
Within these sub-provisions are sub-sub-provisions i.e. (i)(ii)(iii) etc. which are set on ukl:P4 tags. The same logic applies as if they were ukl:P1 tags in that each echelon of tagging must fit within a tagging hierarchy of open and close tags of it’s own kind.
For example a ukl:P4 tag being a low level sub-sub-provision must have it’s closing tag before a closing ukl:P3 tag because the ukl:P3 is of a higher tagging hierarchy and would not ‘fit’ into P4 tagging. Likewise the highest hierarchy to a provision being a ukl:P1 tag it’s closing tag would always be the last tag before the closing ukl:Fragment and never a closing tag of a lower hierarchy, say that of a sub provision P2 tag. (Think Russian Doll theory.)
Below is a general overview of the tags in the secondary provision that includes the tagging of sub-provisions (P3 tags) and sub-sub-provisions (P4 tags), with the text tags which make up the content of that particular provision.
ukl:Fragment
ukl:Secondary
ukl:P1group
ukl:Title
/ukl:Title
ukl:P1
ukl:Pnumber
/ukl:Pnumber
ukl:P1para
ukl:Text
/ukl:Text
ukl:P3
ukl:Pnumber
/ukl:Pnumber
ukl:P3para
ukl:Text
/ukl:Text
ukl:P4
ukl:Pnumber
/ukl:Pnumber
ukl:P4para
ukl:Text
/ukl:Text
/ukl:P4para
/ukl:P4
/ukl:P3para
/ukl:P3
/ukl:P1para
/ukl:P1
/ukl:P1group
/ukl:Secondary
/ukl:Fragment
Note that other tagging such as ukl:Emphasis or ukl:Strong tags are used within ukl:Text tagging to format text in italics or bold.
Viewing Formats in XMetaL
When you are using the XMetaL Editing facility the tagging structure of a document can be revealed by selecting any of the four different View modes.
These can be accessed either via the View menu, on the top menu bar, or via the tagging symbols in the bottom left of the screen. This option is displayed below.
When carrying out editorial work, you will usually have the screen view mode set to the "tags on view" option as displayed above, (second option from the left). This allows you to see exactly where the cursor should be positioned within the parameters of ‘open’ and ‘close’ tagging surrounding the relevant field of text when carrying out an amendment.
As well as the tagging view the other options are, plain text view (extreme left), the view one would expect to see before the document has been published and an assumed view of how it might be viewed on the Legislation site after it has been published (see symbol of the globe – extreme right).
For added information a screenshot of the secondary provision in plain text view can be seen on the next page. We would not normally expect editors to edit in plain text view. However, it is useful to be aware of how the legislation appears in this view.
The screenshot below in plain text view illustrates the distinction, in tagging hierarchy terms, between sub-provision and sub-sub provision tags.
Note that the opening and closing 'number' tags of the sub-sub provison as well as the 'text' tags which make up the content of that sub-provision sub-sub-provision sit within each sub-provision. See tagging breakdown below.
ukl:P3para
ukl:Text
/ukl:Text
ukl:P4
ukl:Pnumber
/ukl:Pnumber
ukl:P4para
ukl:Text
/ukl:Text
/ukl:P4para
/ukl:P4
/ukl:P3para
Collapsing and Expanding Tagging
When the screen view mode is set to the "tags on view", it is possible to isolate relevant text by “collapsing” other sets of tagging surrounding it. This is achieved by selecting the minus symbol on an “open” tag, which has the effect of “swallowing” all the text, and any other tags, between that tag and the corresponding “close” tag.
The screenshot below illustrates this point where the ukl:P1para tag has had the minus symbol selected resulting in all the text in the provision, between this tag and the close /ukl:P1para, now disappearing - enclosed within the ukl:P1 tag.
You should bear in mind that this can easily be done by accident, however no lasting damage is done. Simply select the plus symbol in the ukl:P1 tag and all the enclosed text together with the close /ukl:P1para tag reappears.
(See screenshot below.)
Working with XMetaL
See Starting Update Tasks and in particular Setting up your XMetaL Workspace for details on checking out the amending provision and launching XMetaL.
When XMetaL has launched, you will see the amended provision in the upper pane of the screen. By default the legislation will be shown in ‘tags on view’:
Resource Manager
In the lower pane, the Resource Manager window shows the amending tasks you need to carry out. The list will be collapsed by default. To expand, click on the small cross to the left of the word task:
Note:
- If the Resource Manager window does not open automatically it can be opened by selecting View - Resource Manager. The Resource Manager window can be moved around the page to a position that suits you for editing.
- At the moment the tasks in the Resource Manager window not always give as much information as the task information shown on the Update Details page or in the amending legislation. They may also be in a different order. Work is underway to give more information in this task pane.
Opening the Amending Provision
The amending provision can be opened by double clicking on the task in the Resource Manager window. You can view the amended and amending provisions separately by alternating between the appropriate tabs in the bottom left of the upper pane OR you can view the amended and amending documents simultaneously by selecting Window - Tile Horizontally in the menu bar.
Manually opening the amending document
In some cases, double clicking on the task will fail to open the amending document. In such cases it is possible to manually open the amending document:
- From the menu bar select Legislation - Download Amending Document:
- A text box will appear asking you to enter the amending document URI:
- Use legislation.gov.uk to find the URI details for your amending provision:
- Edit the ‘Download Amending Document’ text box with this information and click OK: Note: You don’t need to amend the whole URI, just the highlighted section. Don’t forget to amend the type of legislation (i.e. ukpga, uksi, etc.). Also, note that primary and secondary legislation are referenced differently (use ‘enacted’ for primary and ‘made’ for secondary’ to make sure you download the original version of the legislation).
- Your amending provision will open in a new window and you will be able to continue with your update task.
See also:
Setting up your XMetaL workspace
Element List Window
The Element List option is a useful facility in XMetaL that can help you when trying to decide where you can ‘legally’ carry out an amendment. By selecting the View option from the toolbar, you can choose to have the Element List windows displayed on screen next to the selected provision.
The Element List details the permissible tagging options that could be inserted at the specific point of the cursor within the document.
In the example below, where the cursor is positioned between the open ukl:P1para tag and open ukl:Text tag the Element List window, (to the right), displays the acceptable tagging alternatives that could be inserted into the provision at this point. Although it is the ukl:P2group tag which has been selected the other tags listed in the Element List window, are also the tags that may be inserted at that particular point without corrupting the document.
When editing a piece of legislation you can use the Element List as confirmation to ensure that you are positioning your amendment in the correct place. The Element List can also be used to insert additional tagging into the legislation you are editing. This might be necessary where, for example, the amendment is incorrectly tagged in the amending document and you need to add in some tags in the amended document to ensure that the amendment is valid. Having established what tagging is permissible from the Element List, you may proceed to insert it into the document by clicking on the “Apply” button positioned at the bottom right of the window.
There are two facilities windows in XMetaL that can help the Editor see which tagging is permissible or illegal at any particular point in a document. By selecting the View option from the toolbar, one can choose to have the Attribute Inspector and/or Element List windows displayed on screen next to the selected amended provision. These facilities enable the editor to identify the permissible tagging options available to the editor at that particular point of where the cursor is positioned on the computer screen.
Attribute Inspector
By selecting the View option from the top menu there is also the opportunity to display the Attribute Inspector window (displayed to the right in the screenshot below). This facility lists an element’s metadata attributes, which can be particularly useful when we need to edit hyperlinks.
Note that it is possible to tile the Attribute Inspector and Element List so both windows can be displayed at the same time, one above the other.
To view an element's attributes, make sure your cursor is placed within the opening and closing tagging of the relevant element (the easiest way to do this is to place the cursor just after the opening tag of the element). Then select Attribute Inspector from the drop-down list under View in the top menu. The first row of the Attribute Inspector displays the element name that you are viewing the attributes of (i.e. ukl:Citation in the example above).
Attributes used in provision tagging
| Video demonstration: Description of provision Attributes (confers power, restrict extent, etc.) (link will only work if you have access to Sharepoint). |
ConfersPower Attribute
The ConfersPower attribute is set to "true" for power-conferring provisions. Where your newly inserted or substituted provision contains a power you will need to set the ConfersPower attribute to "true" for the whole provision. The TOES data for the amendment should contain a Comment for Editor stating “Contains power”, however, you should not rely on this but always double check the provision for powers yourself. Place your cursor to the right of the relevant opening ukl:P1Group tag (or ukl:P1 tag for Schedule paragraphs which do not have headings) and open up the Attribute Inspector:
Set the ConfersPower attribute in the ukl:P1Group to "true" using the drop-down menu:
You can see if the ConfersPower attribute has been set to "true" in the Newly Edited Version:
Note: if the power is contained in a sub-provision, you should set the ConfersPower attribute to "true" at the level of the whole provision.
RestrictExtent Attribute
The RestrictExtent Attribute sets the extent of a provision (at high level e.g. Schedule, Part, etc. and at the level of an individual whole provision):
You can view the extent of a provision in Preview, by selecting "Show Geographical Extent" under "Advanced Features", this will show the extent at high-level and also for lower-level provisions. For lower-level provisions, you can also view the extent attribute in the Newly Edited Version on the Update Details Page.
Note: you should always check the extent attributes when you are inserting or substituting whole provisions (also higher level insertions and substitutions).
How to amend the extent of a provision in the Attribute Inspector
The extent of the amended Pt. 1 in this Schedule was initially incorrectly set as "N.I.", when it should have been "U.K.":
This was corrected to U.K. by checking out the Schedule in XMetaL, placing the cursor to the right of the opening ukl:Part tag and opening up the Attribute Inspector:
E+W+S+N.I. was selected from the drop-down menu and the Schedule was checked back in:
The preview shows that the extent has been amended:
RestrictStartDate Attribute
The RestrictStartDate attribute is used to define the start date of an updated provision and, where a provision has prevously been updated (or brought into force), will correspond with the RestrictEndDate attribute for version of that provision at the previous PiT.
Attributes used in amendment tagging
CommentaryRef Attribute
To view the CommentaryRef attribute for an amendment, place the cursor just after the opening square bracket of an amendment in XMetaL, beside the key-ID:
ukl:Repeal[key-6048ecf16894b46abc61f2fb6529ee10/ukl:repeal
You will see that this key-ID commentary reference number is held in the CommentaryRef attribute within the Attribute Inspector:
This key-ID commentary reference number is also held with the ID attribute of the annotation itself:
You can view this ID in the Attribute Inspector by placing the cursor after the key-ID number that follows the opening ukl:Commentary tag of an annotation:
ukl:Commentary key-6048ecf16894b46abc61f2fb6529ee10
Using the CommentaryRef Attribute to link an amendment to a new annotation
If you need to link an amendment to a new annotation (for example, when applying an amendment to earlier affecting provision effect), you can copy the key-ID of the new annotation (you just need to click on it in the Attribute Inspector to highlight it) and paste it over the existing CommentaryRef number within the Attribute Inspector, to link the amendment to the new annotation.
| WARNING: Do not alter the Change ID reference number in the Attribute Inspector, as this will cause problems with the update. |
Extent attribute
The extent attribute of an amendment element (i.e. ukl:Addition, ukl:Repeal or ukl:Substitution tag) contains the extent of the amendment, and is populated with the extent during limited extent amendments for example:
Note: You will need to amend the Extent attribute for an existing limited extent amendment if the same amendment gets made for another jurisdiction.
Retain Text attribute
This attribute is set to “true” in the ukl:Repeal tagging of limited extent and retained text substitutions and repeals, where the existing text gets retained.
When a partially in force repeal where text has been retained comes fully into force, we can amend this attribute to “false” so that the text gets replaced by a dotty line and F-note. See Applying partially in force amendments which are then brought further into force over time.
Attributes used in annotation tagging
Operative Attribute
References to provisions in annotations are hyperlinked to the source document and are presented in bold if the provision is operative (i.e. it is the affecting provision which contains the effect itself). In this example, the operative provision is Sch. 9 para. 43(2):
Annotation on the website:
Tagging in XMetaL:
The Attribute Inspector is used to set the operative attribute within the ukl:CitationSubref (i.e. place your cursor just to the right of the opening ukl:CitationSubref tag to view the operative attribute. Setting it to "true" will make the link bold for operative provisions. It should be set to "false" for non-operative provisions (i.e. commencing provisions and savings), which will mean these provisions are not displayed in bold.
For more detail on editing hyperlinks, see Fixing Hyperlinks.
Type Attribute
It is possible to change the type of annotation (for example from an F-note to a C-note or M-note), by selecting the relevant Type attribute from the drop-down menu in the Attribute Inspector within the ukl:Commentary tagging of an annotation:
You might need to change the type of annotation where you are inserting an annotation reference using the Insert Commentary option in the Legislation/Non-textual Amendments menu, for example when you are carrying out an amendment to earlier affecting provision amendment.
See more about the various types of annotation on the Annotation Conventions page.
Title Attribute
The Title attribute is populated with the legislation title within ukl:Citation tagging, and this is the title that gets displayed in a pop-up box when you hover over the hyperlink in Preview:
Fixing XML errors in XMetaL
Fixing incorrectly tagged amending provisions
Sometimes amending provisions are incorrectly tagged, and this needs to be fixed by the editor during update as it can be difficult to fix at review stage.
Example: Pt. 6A is inserted into National Health Service Commissioning Board and Clinical Commissioning Groups (Responsibilities and Standing Rules) Regulations 2012 (S.I. 2012/2996) (1.4.2014) by The National Health Service Commissioning Board and Clinical Commissioning Groups (Responsibilities and Standing Rules) (Amendment) Regulations 2013 (S.I. 2013/2891), regs. 1(2), 3.
But, the block amendment in reg. 3 is wrongly tagged:
http://www.legislation.gov.uk/uksi/2013/2891/regulation/3/made
The part number is in Title tagging and the title is in a Number tag within Chapter tagging:
<Part>
<Title>PART 6A</Title>
<Chapter>
<Number>Standing rules: personal health budgets</Number>
This should be tagged as:
<Part>
<Number>Part 6A</Number>
<Title>Standing rules: personal health budgets</Title>
This was corrected by using the Element List in XMetaL to add in the appropriate tagging to create the correct XML structure in the amended provision. Then the relevant text (e.g. the Part number and the words in the heading) were copied and inserted into the correct locations using the Legislation menu so that the appropriate annotation was generated. Finally, the amendment brackets were moved into the appropriate positions.
See on the published site: http://www.legislation.gov.uk/uksi/2012/2996/part/6A/2019-12-02
Removing unwanted tagging
See Specific update Issues - ‘Tidying up’ amendment text and removing unwanted tagging.
Fixing hyperlinks
See also Specific Update Issues - Check that hyperlinks have been generated in annotations.
Missing hyperlinks
Where the hyperlinks for some or all affecting provisions in an annotation are not appearing, this is quickly solved by checking the fragment out, copying the annotation from the Preview and pasting that over the annotation in the commentary tagging in XMetaL. This leaves just text with no ukl:Citation or ukl:CitationSubRef tags. When you check the fragment back in, the system will see that it has no links and will add them in for you. Note that where punctuation is incorrect or the annotation is incorrectly ordered, that may prevent the links from appearing and you will have to correct that first before this solution will work. Also note that this code assumes all legislation is primary and therefore that the commencement provision comes after the operative provision, so it makes the wrong one bold (Note: the operative provision should be bold, not the commencement provision). This can be fixed by going back into the annotation and within the Attribute Inspector changing the operative provision attribute in the ukl:CitationSubRef tag from =false to =true or vice versa.
Broken hyperlinks
| Video demonstration: Fixing broken hyperlinks (link will only work if you have access to Sharepoint). |
Where there is a hyperlink, but it does not work, this is usually because the link is pointing to the wrong place:
- the provision it’s pointing to may have been repealed, in which case rather than point at a sub-provision (e.g. section-1-1-a), you can get it to work by pointing it at the whole provision instead (e.g. section-1) in the attribute for the
ukl:CitationSubRefin the commentary tagging. Note: this is really a bug in the auto redirects code on the website that TSO need to fix, so this fix is just a workaround. - the link may be pointing to two sub-provisions and therefore confusing the system. E.g. if your annotation mentions “s. 1(3)(5)” (rather than s. 1(3)(a) or s. 1(3)-(5), for example) then the target link will point to “section-1-3-5” which doesn’t exist (there is no sub-sub (5) under sub (3), they are both at the same level and the system can’t cope with that – although it can cope with ranges). The simplest way to fix this is to choose one sub-provision and make the link point to that, e.g. “section-1-3”, or make it point at the whole provision, e.g. “section-1” (by amending the SectionRef attribute). Note that if the URI field is populated with a URI, you will also need to amend this to point to the same place as you have specified in the SectionRef attribute.
To amend the link attributes, place the cursor in the
ukl:CitationSubReftagging:
Edit the SectionRef and URI (if there is one) attributes to point to only one provision:
Hyperlinks pointing to the wrong item of legislation
If hyperlinks in your annotation are pointing to the wrong item of legislation, check the URI and Class attributes within the ukl:Citation tagging in the Attribute Inspector, and make sure that the correct type of legislation is referenced. Also check the Title attribute (if populated), to make sure the title of the legislation is correct.
Note: There is currently a bug in the way that the annotation Edit function in Preview creates hyperlinks for Acts of the Northern Ireland Assembly (NIAs) - although the links look right superficially, they may point to UK Public General Acts (UKPGAs) rather than NIAs.
For example:
S. 9(3)(c) and word omitted (6.4.2016) by virtue of Pensions Act (Northern Ireland) 2015 (c. 5), s. 53(3), Sch. 13 para. 51
In this example, after the amendment was carried out, at first glance the links looked as though they had been correctly generated by the Editorial System, however they turned out to be pointing to the wrong item of legislation and the links to the provisions were broken, as those provisions didn't exist in the item of legislation the link was pointing to.
The hyperlinks were pointing to the National Insurance Contributions Act 2015 (c. 5) rather than the Pensions Act (Northern Ireland) 2015 (c. 5), because the Editorial System had mistakenly assigned the hyperlink the attributes for a UK Public General Act rather than an Act of the Northern Ireland Assembly:
To fix this, the provision was checked out in XMetaL and the cursor was placed inside the ukl:Citation tagging of the affecting document:
In the Attribute Inspector, the legislation type of the URI attribute was changed to NIA, and the class attribute was set to “Northern Ireland Act”:
The legislation type of the URI attribute was also changed to NIA in the ukl:CitationSubRef tagging of the affecting provisions:
In this example, the Title attribute was not populated, however, this attribute should also be checked if your link is pointing to the wrong item of legislation, and if a title is present in this attribute make sure that it relates to the correct item of legislation.
Only part of the legislation title in an annotation is hyperlinked
There is currently a bug in the way that the annotation Edit function in Preview creates hyperlinks for legislation titles, whereby sometimes only part of the title gets hyperlinked:
To fix this, you will need to check the relevant provision out in XMetaL and copy the portion of the title from outside the Citation tagging and paste it into the Citation tagging (you could also just select and drag it to the correct location), as follows:
From this:
To this:
You should also correct the Title attribute, so that it contains the complete title:
From this:
To this:
The whole title is now hyperlinked, and if you hover over the link, the full title should also be displayed in the pop-up box because you also amended the Title attribute:
Adding hyperlink to ANAW title in a manual annotation
There is currently a bug in the manual annotations code which means that links are not being created to the affecting legislation or operative and commencing provisions where the affecting document is an Act of the National Assembly for Wales (anaw), for example:
The workaround for this is to select the title of the Act in the annotation and put ukl:Citation tags round it using the element list:
After this, place your cursor within the new ukl:Citation tags and open the Attribute Inspector in order to add Year, Number and Class = "Act of the National Assembly for Wales" from the dropdown menu. When you check this in the system will create a link for the title:
It's too much extra effort to also add links for the operative and commencing provisions, although it is possible (you would insert ukl:CitationSubref tags around the provisions and then add the Citation id to them to link them with the ukl:Citation tagging).
XMetaL error messages
See Update Troubleshooting - Resetting Workspace in XMetaL.
Related Pages
Approach, errors and troubleshooting: