8 Appendices
8.1 RSS V1.0 specification
8.1.1 Description
RSS is a lightweight, multipurpose, extensible metadata description and syndication format. RSS is an XML application that conforms to the W3C's RDF specification and is extensible via XML-namespace and/or RDF-based modularisation (see below).
Essentially, an RSS file is a document describing a "channel" consisting of URL-retrievable items. Each item consists of a title, link and brief description.
8.1.2 Specification
The RSS V1.0 specification can be found at http://web.resource.org/rss/1.0/spec This specification defines the core RSS schema.
Elements can be added to the core schema by using imported modules that extend its namespace (namespace-based modularisation). This gives RSS V1.0 extensibility. The modules that come with RSS V1.0 are Dublin Core, Content and Syndication.
For more information, go to the appropriate module documentation:
- Dublin Core: http://purl.org/rss/1.0/modules/dc/
- Syndication: http://purl.org/rss/1.0/modules/syndication/
8.2 A government-specific module
The core set, together with the modules above, does not provide all the elements required to describe government's data set. For example, there is no agency element.
Importing NZGLS into the core RSS schema solves this problem and provides future-proofing. The schema can be extended if new elements are needed. NZGLS was defined as part of the e-GIF: http://www.nzgls.govt.nz/standard/
Please note that Appendix 8.4 lists the elements and syntax of the NZGLS module.
8.3 RSS schema
The news import files should be formatted as XML 1.0, with a single channel. The file must be encoded as UTF-8. See Unicode for more information: http://www.unicode.org/
All RSS core schema elements along with the three modules (defined above) and the NZGLS extensions (see below) can be used within an RSS file. They may be used as required and within the limits of the standard.
The following samples should be used as a guide only. They may contain information that is fictional or only partially complete.
8.3.1 Header
Each RDF document should start as follows:
The top three modules (xmlns - XML namespace includes) are always required. The other modules can be left out if not required.
8.3.2 Channel
A channel declaration should follow the header. The URL specified in the rdf:about attribute of the channel should be unique within an RSS file. This URL is usually the place where the RSS file can be found (it may be the home page of the content described, as well).
The channel must contain a title that describes the source of this news. The link element must be present and point to a place where a text version of this news can be found. Usually this is a URL that points to a HTML page. The optional description can be used to describe this channel. In the example above the description contains the name of the news source.
The Dublin Core elements (dc) allow the creator to add specific information about the channel. The examples above show use of the creator, language and the publisher elements.
These elements are optional but highly recommended. As a general rule, NZGLS elements should be used in preference to Dublin Core elements for government-specific information. In this instance, Dublin Core elements are ideal because the information is not government-specific and they are more widely understood by software.
The syndication elements (syn) allow the feed to hint to the aggregator how often the content should be fetched. In this example, the feed has hinted that it should be fetched twice daily. As this is a hint, the aggregator may choose to ignore this information. These elements are optional but highly recommended.
The channel must contain a list of links of the news items present in the file. This is represented using an RDF sequence of links to the actual news items. There should be a link at this point for every news item that will appear in the file (after the closing channel element).
8.3.3 Items
The actual news content should be formatted as follows. Each item must include atitle,link, nzgls:date.valid, nzgls:identifier andnzgls:type.agency at a minimum. Fields can be added from NZGLS, Dublin Core or content as required (within the limitations of the specification).
The content of the description field should consist of pure text and not contain any HTML or XML mark-up.
8.3.4 The end
The RDF closing statement marks the end of the document:
8.4 NZGLS elements and syntax
This appendix lists details of the NZGLS elements used in the example above. Each element shows its required syntax and default values if these cannot be specified.
8.4.1 < nzgls:date.valid >(required)
This defines a date (and time) range that the item is valid. Date ranges should follow the Dublin Core Metadata Initiative (DCMI) Period specification for defining start and end dates. While this element controls an item's validity period, the validity of an item does not guarantee its publication.
This element is required. A date should always be expressed as YYYY-MM-DD.
At a minimum, it is sufficient to specify the start date only.
The default end date and time is seven days from the start date at 23:59 local time. An item with a start date in the future, but with no end date will also get an end date of seven days from the start date (rounded up to 23:59).
The time (if specified) must always be expressed as HH:MM:SS+12:00. The +12:00 is needed because the W3C specifies that the time will always be in Unified Time Co-ordinated (UTC) unless the time offset is included.
A fully specified date and time is therefore defined as:
YYYY-MM-DDTHH:MM:SS+1200
Please note that the separating ‘T’ between the date and time is required when specifying a date and time. Some example values for date and time are:
2002-10-15
2002-10-15T11:25:00+12:00
See http://www.w3.org/TR/NOTE-datetime for more information about date and time formatting.
See http://dublincore.org/documents/2000/07/28/dcmi-period/ for detailed information about using DCMI-Period.
Syntax: < nzgls:date.valid >start={DATE}; end={DATE}< /nzgls:date.valid >
Requirement: Required
Required attribute(s): none
Default: See description above
Examples: < nzgls:date.valid >2002-10-07< /nzgls:date.valid >
< nzgls:date.valid >start=2002-10-07< /nzgls:date.valid >
< nzgls:date.valid >start=2002-10-07; end=2002-11-12< /nzgls:date.valid >
< nzgls:date.valid >start=2002-10-07; end=2002-11-12T19:00:00+12:00< /nzgls:date.valid >
< nzgls:date.valid > start=2002-10-07T09:00:00+12:00; end=2002-11-12T19:00:00+12:00 < /nzgls:date.valid >
8.4.2 < nzgls:coverage.spatial >(optional)
This defines the regional relevance of a given item, to allow for regional content delivery.
This element is optional. Any item without this element will be assumed to be valid for the entire country. This element may be up to 128 characters long.
The aggregator separates content into regions using regional council boundaries: Northland, Auckland, Waikato, Bay of Plenty, Gisborne, Hawke's Bay, Taranaki, Manawatu (Wanganui), Wellington, Marlborough, Nelson, Westland, Canterbury, Otago and Southland.
If an item is for more than one region, then each region should be listed separated by commas. An item that applies to a particular region and the whole country can use the specific region name followed by "New Zealand".
Syntax: < nzgls:coverage.spatial >{REGION NAME}< /nzgls:coverage.spatial >
Requirement: Optional
Required Attribute(s): none
Examples: < nzgls:coverage.spatial >Canterbury< /nzgls:coverage.spatial >
< nzgls:coverage.spatial >Canterbury, Wellington< /nzgls:coverage.spatial >
< nzgls:coverage.spatial >New Zealand< /nzgls:coverage.spatial > < nzgls:coverage.spatial >New Zealand, Wellington< /nzgls:coverage.spatial >
8.4.3 < nzgls:identifier >(required)
This defines a unique identifier for each record. This element is required - any item without it will be ignored.
The aggregator detects duplicates and updates to previously published news items using the unique identifier. A news item may have changed entirely, but as long as the identifier remains valid, it can be successfully updated.
The identifier can be up to 64 characters, from the set [0-9a-zA-Z-+_]. The identifier must consist of a YYYYMMDD date (optionally hyphen separated), followed by a sequence number and an abbreviated agency name, all separated by hyphens.
By preference, the date should be the date the item is published, but this is not mandatory. The sequence number ensures uniqueness and can be a simple sequence number or internal reference number.
The identifier must remain the same for all instances of the same item; otherwise the item in question may be published multiple times.
8.4.4 < nzgls:type.agency >(required)
This defines the agency that published the item. While it is highly likely that all the items within a single feed will contain the same information in this element, this element is still required; any item without this element will be ignored.
This element may be up to 128 characters long.
This element is required so that an aggregated output feed will contain the correct values for this element.
Syntax: < nzgls:type.agency >{AGENCY NAME}< /nzgls:type.agency >
Requirement: Required
Required attribute(s): none
Examples:
< nzgls:type.agency >State Services Commission< /nzgls:type.agency >
8.4.5 < nzgls:type.document >(optional)
This defines the type of this particular item. This element is optional. Items without this element will be categorised as "News".
The type should be one of:
- news
- consulting
- newsletter.
Other types can be added as needed. For example, agencies wishing to convey information about a vacancy could define the type "vacancy". At the moment the aggregator will silently ignore any types it does not recognise.
Syntax: < nzgls:type.document >{TYPE}< /nzgls:type.document >
Requirement: Optional
Required attribute(s): none
8.5 Agencies involved in the RSS pilot
|
Bioethics Council Climate Change Department of Conservation Department of Labour Environment Waikato Greater Wellington Regional Council Land Transport Safety Authority Ministry of the Environment Ministry of Culture and Heritage Ministry of Agriculture and Fisheries Ministry of Economic Development |
Ministry of Justice New Zealand Climate Change Office New Zealand Defence Force New Zealand Food Safety Authority New Zealand Police New Zealand Trade and Enterprise Inland Revenue Department Sport and Recreation New Zealand State Services Commission Statistics New Zealand |
8.6 Frequently asked questions
8.6.1 Which fields are required within an item?
The following fields are required at the very minimum:
- < title >
- < link >
- < nzgls:date.valiod >
- < nzgls:identifier
- < nzgls:type,agency >
More elements may be added. For example, the < description > element makes items a lot more useful!
8.6.2 What is the < nzgls:identifier > field used for?
This field provides each item with a unique identifier used to check for updates to a given item. It should consist of:
- the date
- a sequence number
- an abbreviated agency or unit name. [The agency may choose this name from a number of sources; e.g. Metalogue, machinery of government (MOG) or GLADIS (Archives). A programme to produce one authoritative source of agency details is in the planning stages by the SSC EGU. None of the fields are publicly viewable.]
These three parameters (in this order) ensure the identifier remains unique.
8.6.3 What happens to items with a future start date?
An item with a future start date in the < nzgls:date.valid > element will not be published nor available in the aggregated output until that date and time.
8.6.4 Do items with an expired end date get deleted?
An item with an expired end date in the < nzgls:date.valid > element is simply not shown on the most recent list of articles. It is moved to the archive section of the aggregator. Expired items will not appear in the aggregated output.
8.6.5 What can I do if I need an item that expired today?
The expiry date of the item in the feed can be changed. When the item on the aggregator is synchronised with the item in the news-feed, it will immediately acquire the new expiry date.
8.6.6 How long should an item keep appearing within my news-feed?
An item should appear for at least seven days in the news-feed. This ensures items are never missed, even if there are service disruptions or "acts of God". A simpler solution is to ensure that the 10 (for example) most recent items are always present in your news-feed.
8.6.7 Why are <nzgls> elements used rather than < dc > elements?
The NZGLS metadata standard is the official New Zealand government standard for creating discovery-level metadata (see http://www.nzgls.govt.nz/). It is closely based on two well-established standards: the Dublin Core (DC) Metadata Element Set and the Australian Government Locator Service (AGLS). NZGLS elements should be used in preference to Dublin Core elements for government-specific information.
8.6.8 How much content should go into a < description >?
This is up to each news-feed provider to decide. The description should include sufficient information so that the item is complete in itself; and the reader can determine what the item is about and its main points. A description can contain the entire content, partial content or only a summary of the content.
8.6.9 Which encoding scheme should be used?
UTF-8 encoding. This means that all characters with an ASCII value higher than 127 (0x7F) are encoded as double byte sequences or as “ & #{NUMBER};”. Special characters like “&” should be encoded using the “& #{NUMBER};” notation.
[ Previous | Next ]
