Works and expressions

Listing and fetching works and expressions.
Two important concepts that are an essential part of the API are works and expressions.
  • A Work is a piece of legislation, such as an act, regulation or by-law. A work may be amended over time and may even have its title changed. A work is uniquely identified by a work FRBR URI which never changes.
  • An Expression is a version of a Work in specific language at a particular point in time. A work can have many expressions, usually one for each official language and amendment. An expression is uniquely identified by its own expression FRBR URI, which is derived from the work's FRBR URI.
An example of a work is the South African Employment Equity Amendment Act, 2013 (Act 55 of 1998) with unique work FRBR URI /akn/za/act/1998/55. This act has been amended a number of times since it was first passed. Each amended version (also called a point in time) is a unique expression of the work.
The English expression of the work, as it was amended on 17 January 2014, is uniquely identified by the expression FRBR URI /act/1998/55/[email protected]. You can see that this is built from the work's URI, with a language code eng and the expression date 2014-01-17 included.
When fetching details from the API, you are always fetching details for a particular expression of the work. The expression will also include information related to the expression's work, such as the work's FRBR URI and publication information. Even if you don't specific a particular date for the expression, the API will return the latest expression applicable for the date of the request.
The API supports the language and date aspects defined in the Akoma Ntoso naming convention standard.
get
https://api.laws.africa
/v2/akn/:country/.:format
List works for a place
Supported content types: JSON, PDF, ePub, zip
get
https://api.laws.africa
/v2/:frbr-uri.:format
A single expression
Supported content types: JSON, HTML, PDF, ePub, zip

Work expression attributes

The fields of the work and expression endpoints are described in the table below.
Field
Description
Type
amendments
List of amendments that have been applied to create this expression of the work.
See below
as_at_date
Date up to which this work is known to be up-to-date.
ISO8601
assent_date
Date when the work was assented to.
ISO8601
content_url
URL of the full content of the work.
URL
country
ISO 3166-1 alpha-2 country code that this work is applicable to.
String
created_at
Timestamp of when the work was first created.
ISO8601
draft
Is this a draft work or is it available in the public API?
Boolean
expression_date
Date of this expression of the work.
ISO8601
commencement_date
Date on which this work commences.
ISO8601
commencing_work
Details of the work which commenced this work, if any.
Object
commencements
Details of the commencements which apply to this work.
See below
expression_frbr_uri
FRBR URI of this expression of this work.
String
frbr_uri
FRBR URI for this work.
String
id
Unique ID of this work.
Integer
language
Three letter ISO-639-2 language code for this expression of the work.
String
links
A description of links to other formats of this expression that are available through the API.
Array
locality
The code of the locality within the country.
String
nature
The nature of this work, normally "act".
String
number
Number of this work with its year, or some other unique way of identifying it within the year.
String
parent_work
The parent of this work. For subsidiary legislation, this is the principal legislation.
Object
points_in_time
Points in time that are available for this work.
See below
publication_date
Date of original publication of the work.
ISO8601
publication_name
Name of the publication in which the work was originally published.
String
publication_number
Number of the publication in which the work was originally published.
String
repeal
Description of the repeal of this work, if it has been repealed.
See below
subtype
Subtype code of the work.
String
title
Short title of the work, in the appropriate language.
String
updated_at
Timestamp of when the work was last updated.
ISO8601
url
URL for fetching details of this work.
URL
year
Year of the work.
Stri

Amendments

The fields of the amendments property of the response are described below. These are the amendments that have been applied to produce this particular expression.
Field
Description
Type
amending_title
Title of the amending work
String
amending_uri
Work FRBR URI of the amending work
String
date
Date on which the amendment takes place
ISO8601

Commencements

The items in the commencements property describe the various commencements that apply to this work, and are the same for all expressions.
In most cases, either the work is not commenced or a single work commences all of the work's provisions. In some edge cases, different provisions commence at different times and these objects describe those events.
In some extreme cases, the work that performed the commencement, or the commencement date, might not be known.
Field
Description
Type
commencing_title
Title of the commencing work (optional)
String
commencing_frbr_uri
FRBR URI of the commencing work (optional)
String
date
Date of the commencement event (optional)
ISO8601
main
Is this considered the primary or main commencement event? This is usually the event that commences the bulk of the work.
Boolean
all_provisions
Does this event commence all provisions? If this is true, there will only be one of these commencement objects.
Boolean
provisions
A list of IDs of the provisions that are commenced by this event. This is always empty if all_provisions is true.
List

Points in Time

The fields of the points_in_time property of the response are described below. These are all the available points in time available for this work.
Field
Description
Type
date
Date of the point-in-time for which expressions are available
ISO8601
expressions
A list of expressions for this work available at this point in time
List
url
The API URL to fetch information on the expression
URL
language
Three-letter language code of the language of the expression
String
expression_frbr_uri
Unique Expression FRBR URI for this expression
String
expression_date
Date of this expression
ISO8601
title
Title of the work, appropriate for the expression in the expression's language)
String

Expressions at specific points in time

Works may be amended and change over time. You can fetch different amended versions of a work by specifying the language and date in the FRBR URI of the request.
The available points in time of a work are listed in the points_in_time field of the JSON description of the work. Each point in time includes a date and a list of expressions available at that date, one for each available language.
To fetch the very first expression of a work, use frbr-uri/:[email protected], for example: /akn/za/act/1998/5/[email protected].
To fetch a specific point in time, use frbr-uri/:[email protected]:date, for example: /akn/za/act/1998/5/[email protected].
To fetch the most recent point in time at or before a specific date, use frbr-uri/:language::date, for example /akn/za/act/1998/5/eng:2014-01-17.
The .format part of the FRBR URI is placed after the @YYYY-MM-DD part.
If you use @ to specify a particular date and the API doesn't have a version at exactly that date, it will return a 404 response. If you need the expression of the work closest to a particular date, use : instead.

Date formats for specific points in time

Date Format
Meaning
Example Expression FRBR URI
@
Very first expression of a work.
/akn/za/act/1998/55/[email protected]
@YYYY-MM-DD
Expression at the specific date.
/akn/za/act/1998/55/[email protected]
:YYYY-MM-DD
Most recent expression at or before a date.
/akn/za/act/1998/55/eng:2015-01-01
(none)
The most recent expression at or before today's date. Equivalent to using : with today's date.
/akn/za/act/1998/55/eng