Quick introduction to XML for Lawmaker users

Legislative drafting, amending and publishing programme

​

Topics

1. Introduction
2. What is XML
3. Akoma Ntoso, schema and validations

Introduction

Introduction

• XML is a way of storing data
• Lawmaker stores all legislation as XML
• Each SI or Bill etc. is stored as an XML document
• When you are editing legislation in Lawmaker, you are using an XML editor (called Oxygen)
• Although this editor presents the legislation pretty much as you would expect (it is a “WYSIWYG” editor), it is helpful to understand a little about the form and structure of XML
• The next few slides take you through the basics of XML as applied to legislation

?

What You See Is What You Get

What is XML?

What is XML?

• XML Stands for eXtensible Markup Language
• It is a way of encoding (marking up) documents so that a machine can read the document as well as a human. It is often used to easily and safely store and transport data because all of the encoding is done using text within the document.
• Put simply, it is text wrapped in tags.
• See the example XML in the box.

​

<chapter>

<num>Chapter 1</num>

<heading>Interpretation</heading>

<article>

<heading>Meaning of “XML”</heading>

<num>1</num>

<content>

<p>”XML” means eXtensible Markup Lanuage.</p>

</content>

</article>

</chapter>

Tags, elements, text and attributes

• Tags come in 3 flavours: start tags, end tags and empty tags. They all start and end with “<“ and “>”.
• Inside a tag you can put attributes which are additional pieces of metadata.
• Between the tags you can put text, more tags or a mix of both.
• An XML element is what we call the bit of an XML document from the start tag to the end tag and everything in between.
• The next slide has some simple examples

Examples of elements

• This snippet of XML represents a whole element. We might refer to it as the “heading element”.
• It has a start tag <heading> and an end tag </heading>.
• The start tag has an attribute called “id” with a value of “head1”.
• The text content of the element is ‘Meaning of “XML” .

<heading id=“head1”>Meaning of “XML”</heading>

Start tag

End tag

Attribute

Text

<heading id=“head1”>Meaning of “<acronym>XML</acronym>”</heading>

• This is the same as the previous example but demonstrates that an element can contain other elements as well as text.
• In this case, the heading element contains an acronym element as well as text.

Why does this matter for Lawmaker?

• In Lawmaker, when you are editing a document (or when you produce a PDF), what you see is generally only the text.
• But the XML tags (and the attributes in those tags) are important because Lawmaker uses them to:
• Work out how to format the text on screen and in the PDF
• Determine what provisions are allowed where, e.g. a subparagraph is only allowed within a paragraph
• Make many other features such as cross-references work correctly.
• One of the most important kinds of attributes that are added to tags are IDs. We use two:
• An eId which is a unique identifier given to each provision. It is based on the provision’s number and its hierarchical position in the document (and so changes as the document changes)
• A GUID which is a long random number and never changes once the provision is created (essential to maintain cross-references)

?

Expression Identifier

?

Globally unique identifier

XML is like a family tree

• XML is particularly suited to representing documents and data that are highly structured and contain lots of text.
• Legislation is a prime example of that. SIs and Bills etc. are highly structured, hierarchical documents which mainly consist of text.
• In legislative documents, the hierarchical structure means that provisions contain other provisions, e.g.
• Parts can contain Chapters
• Articles can contain paragraphs
• Sections can contain subsections
• This is reflected in the XML by an XML element representing a provision containing other XML elements representing other provisions.

XML is like a family tree cont.

A good way to visualise and describe an XML document is to think of it like a family tree.

​

• It’s a tree because XML documents form a tree structure starting at the root element and branching from the root to child elements (the leaves).
• It’s a family because terms like parent, child and sibling are used to describe the relationship between elements.

Click to see relationships

Two subsections in a section are siblings of one another

A subsection is a child of its parent section

In this diagram, the root element is the Bill element

The following slides contain more detailed example tree diagrams for SIs and Bills.

Example SI tree diagram

Example SI tree diagram: regulation

Lawmaker vs. word processors

• When using Lawmaker you are editing an XML document and so the behaviour of the editor is affected by the structure of the XML.
• In particular, the hierarchical structure and notion of containment is important.
• On the other hand, when you use a word processor, like Microsoft Word, there is little or no hierarchical structure; instead each paragraph of text is a sibling of the previous paragraph and the function of the paragraph (e.g. whether it is a number, heading, or the content of a section) is indicated by a style.
• The diagram on the next page illustrates the difference.

XML: provisions contain provisions

Word: all paragraphs are siblings of one another

Why does the tree structure matter in Lawmaker?

• Because provisions contain other provisions in XML, this has consequences for how you manipulate the document in Lawmaker. This is particularly relevant for provisions like Parts and Chapters.
• For example, if you have some regulations in an SI that you want to be in a Part then you need to wrap the existing regulation elements in a Part element so the Part contains the regulations (the Part becomes the parent of the regulations).
• It is called wrapping because it involves placing a start tag and an end tag around the existing elements.

<Part>

<num>Part 1</num>

<heading>Part Heading</heading>

<regulation></regulation>

<regulation></regulation>

</Part>

Akoma Ntoso, schemas & validation

Akoma Ntoso and XML schemas

• A schema is a set of rules that describe what is valid and what is not in a particular XML document. It defines an XML vocabulary and structure for documents in a particular context.
• Akoma Ntoso is an open international standard for representing legislative, parliamentary and judicial documents in an electronic form. It consists of a set of XML schemas.
• Lawmaker uses Akoma Ntoso to represent each document you create and edit.
• Other schemas you may have heard of:
• Crown Legislation Markup Language (CLML): this is the format used by legislation.gov.uk
• MathML: this is used to represent mathematical formulae as XML

?

“Linked hearts” in the Akan language of West Africa

Validation

• Lawmaker constantly checks the document you are editing to ensure it is valid.
• Validation is important to ensure your document can be reliably converted into other formats as part of its legislative journey, e.g. that a PDF can be produced for printing or the CLML version can be created for publication on www.legislation.gov.uk.
• But validation is also used to help ensure your document meets expected standards in terms of structure and coherence. Different standards apply for Bills and for SIs, and between Scotland and the UK.

Type of validation

• Lawmaker runs two types of validation rules at the moment (both show in the Document Checks panel):
• Akoma Ntoso Schema validation: this checks that the document is fundamentally sound and complies with the rules of Akoma Ntoso. The schema is very permissive, however, because it is designed to be able to represent legislation from any jurisdiction and legal system.
• Schematron validation: these rules we have specified which check that the document meets the particular business rules of our jurisdictions and legislatures. They cover the structure of the document but also things like, for example, cross-referencing and consistency between titles and citation provisions.

​

Related training videos

Reviewing and validating your SI/SSI

Creating an SI/SSI and drafting provisions

The end!