Quick Start - Packages
| We recommend reading the Quick Start Guide to NewsML-G2 Basics before this Quick Start Guide. |
1. Introduction
The ability to package together items of news content is important to news organisations and customers. Using packages, different facets of the coverage of a news story can be viewed in a named relationship, such as "Main Article", "Sidebar", Background". Another frequent application of packages is to aggregate content for news products, for example "Top Ten" news packages such as that illustrated below
| A description of how to create this type of package with ordered components can be found further on in this document. |
Packages can range from simple collections on a common theme, to rich hierarchical structures.
NewsML-G2 is flexible in allowing a provider to package content that has already been published, or a package may be sent together with all of its content resources in a single News Message. See the Guidelines section on News Messages.
2. Packages and Links: the difference
The NewsML-G2 <link> property is a useful way to indicate optional supplementary resources that may be retrieved by the end-user when processing or consuming a NewsML-G2 Item. Links should not be used as a lightweight method of packaging news; a NewsML-G2 processor would not be able to distinguish between News Items with some optional resources, and News Items that are intended to be pseudo-packages using links. It is also a basic NewsML-G2 rule that a News Item only conveys one piece of content.
By contrast, Packages:
-
Express structure, allowing news to be packaged as a list, or as a named hierarchy of content resources.
-
Have a mode property that enables the expression of a relationship between the components of a package group.
3. Package Structure
A simple Package has a structure as shown in the example below. The top level for content of a Package Item is one and only one <groupSet> element, followed by at least one <group> structure containing one or more <ItemRef> references to content. The <group> structure may also be repeated, but this example has only one. The diagram below shows a skeleton of the XML elements in a simple package and a visualisation of the relationship that this structure creates:
The following NewsML-G2 document illustrates the package structure above.
(All Scheme Aliases used in listing below indicate IPTC NewsCodes vocabularies, except for the following alias values: staffjobs, mystaff, svc, group.)
<?xml version="1.0" encoding="UTF-8"?>
<packageItem
xmlns="http://iptc.org/std/nar/2006-10-01/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://iptc.org/std/nar/2006-10-01/
./NewsML-G2_2.28-spec-All-Power.xsd"
standard="NewsML-G2"
standardversion="2.28"
conformance="power"
guid="tag:example.com,2008:UK-NEWS-TOPTEN:UK20081220098658" version="12">
<catalogRef
href="http://www.iptc.org/std/catalog/catalog.IPTC-G2-Standards_34.xml" />
<catalogRef
href="http:/www.example.com/customer/cv/catalog4customers-1.xml" />
<itemMeta>
<itemClass qcode="ninat:composite" />
<provider qcode="nprov:AcmeNews" />
<versionCreated>2019-11-17T12:30:00Z</versionCreated>
<firstCreated>2008-12-20T12:25:35Z</firstCreated>
<pubStatus qcode="stat:usable" />
<profile versioninfo="1.0.0.2">simple_text_with_picture.xsl</profile>
<service qcode="svc:uktop">
<name>Top UK News stories hourly</name>
</service>
<title>UK-TOPNEWS</title>
<edNote>Updates the previous version</edNote>
<signal qcode="sig:update" />
</itemMeta>
<contentMeta>
<contributor jobtitle="staffjobs:cpe" qcode="mystaff:MDancer">
<name>Maurice Dancer</name>
<name>Chief Packaging Editor</name>
<definition validto="2019-11-17T17:30:00Z">
Duty Packaging Editor
</definition>
<note validto="2019-11-17T17:30:00Z">
Available on +44 207 345 4567 until 17:30 GMT today
</note>
</contributor>
<headline xml:lang="en">UK</headline>
</contentMeta>
<groupSet root="G1">
<group id="G1" role="group:main">
<itemRef residref="urn:newsml:iptc.org:20081007:tutorial-item-A"
contenttype="application/vnd.iptc.g2.newsitem+xml"
size="2345">
<itemClass qcode="ninat:text" />
<provider qcode="nprov:AcmeNews"/>
<pubStatus qcode="stat:usable"/>
<title>Obama annonce son équipe</title>
<description role="drol:summary">Le rachat il y a deux ans de la
propriété par Alan Gerry, magnat local de la télévision câblée, a
permis l'investissement des 100 millions de dollars qui étaient
nécessaires pour le musée et ses annexes, et vise à favoriser le
développement touristique d'une région frappée par le chômage.
</description>
</itemRef>
<itemRef residref="urn:newsml:iptc.org:20081007:tutorial—item-B"
contenttype="application/vnd.iptc.g2.newsitem+xml"
size="300039">
<itemClass qcode="ninat:picture" />
<provider qcode="nprov:AcmeNews"/>
<pubStatus qcode="stat:usable"/>
<title>Barack Obama arrive à Washington</title>
<description role="drol:caption">Si nous avons aujourd'hui un
afro-américain et une femme dans la course à la présidence.
</description>
</itemRef>
</group>
</groupSet>
</packageItem>4. Document structure
The building blocks of the Package Item are the <packageItem> root element, with additional wrapping elements for metadata about the Package (itemMeta), metadata about the content (contentMeta) and the package content (groupSet). The top level (root) element <packageItem> attributes are:
<packageItem xmlns="http://iptc.org/std/nar/2006-10-01/"
guid="tag:example.com,2008:UK-NEWS-TOPTEN:UK20081220098658"
version="12">
standard="NewsML-G2"
standardversion="2.28"
conformance="power"This is followed by Catalog information:
<catalogRef
href="http://www.iptc.org/std/catalog/catalog.IPTC-G2-Standards_34.xml" />
<catalogRef
href="http:/www.example.com/customer/cv/catalog4customers-1.xml" />5. Item Metadata
The <itemMeta> wrapper contains properties that are aids to processing the package contents.
5.1. Profile
The <profile> element allows a provider to name a pre-arranged template or transformation stylesheet that can be used to process the package, for example "text and picture" could be the name of a template; "textpicture.xsl" would be an xsl stylesheet. The @versioninfo of a <profile> enables the template or stylesheet to be versioned:
<profile versioninfo="1.0.0.2">simple_text_with_picture.xsl</profile>5.2. Item Metadata in full
<itemMeta>
<itemClass qcode="ninat:composite" />
<provider qcode="nprov:AcmeNews" />
<versionCreated>2019-11-07T12:30:00Z</versionCreated>
<firstCreated>2008-12-20T12:25:35Z</firstCreated>
<pubStatus qcode="stat:usable" />
<profile versioninfo="1.0.0.2">simple_text_with_picture.xsl</profile>
<service qcode="svc:uktop">
<name>Top UK News stories hourly</name>
</service>
<title>UK-TOPNEWS</title>
<edNote>Updates the previous version</edNote>
<signal qcode="sig:update" />
</itemMeta>6. Content Metadata
The <contentMeta> wrapper in this example contains extended metadata about the person who compiled the package, including hours of duty and contact telephone number.
<contentMeta>
<contributor jobtitle="staffjobs:cpe" qcode="mystaff:MDancer">
<name>Maurice Dancer</name>
<name>Chief Packaging Editor</name>
<definition validto="2019-11-17T17:30:00Z">Duty Packaging Editor</definition>
<note validto="2019-11-17T17:30:00Z">Available on +44 207 345 4567 until 17:30 GMT today</note>
</contributor>
<headline xml:lang="en">UK</headline>
</contentMeta>7. Group Set
The <groupSet> has a mandatory root attribute that references the primary child <group> element. The primary <group> element must identify itself using an @id that matches the @root of <groupSet>.
<groupSet root="G1">7.1. Group
Although the id attribute is optional, in practice one must be provided to match the mandatory root attribute of the <groupSet>, even if there is only one <group>. If there is more than one <group> element, one and only one can be identified as the root group.
Group elements must also contain a role attribute to declare its role within the package structure. The role is a QCode, but a Scheme of Roles may typically contain values representing "main", "sidebar" or other editorial terms that express how the content is intended to be used in the package.
<group id="G1" role="group:main">7.2. Item Reference
The <itemRef> element identifies an Item or a Web resource using @href and/or @residref. The IPTC recommends that Package Items should reference NewsML-G2 Items if they are available (typically News Items) rather than other types of resource, such as "raw" news objects. Referring to other kinds of Web-accessible resource is allowed and is a legitimate use-case, however it has some disadvantages. Resources referred to in this way cannot be managed or versioned: if one of the resources is changed, the entire package may need to be re-compiled and sent, whereas a reference to a managed object such as a <newsItem> may refer to the latest (or a specific) version.
The example versions the referenced Items using @version, and gives processing or usage hints using @contenttype and @size. The @contenttype uses the registered IANA Media Type for a NewsML-G2 News Item:
<itemRef residref="urn:newsml:iptc.org:20081007:tutorial-item-A"
contenttype="application/vnd.iptc.g2.newsitem+xml"
size="2345">The Item Reference includes properties from the referenced Item that have been extracted as an aid to processing:
<itemClass qcode="ninat:text" />
<provider qcode="nprov:AcmeNews"/>
<pubStatus qcode="stat:usable"/>
<title>Obama annonce son équipe</title>
<description role="drol:summary">Le rachat il y a deux ans de la
propriété par Alan Gerry, magnat local de la télévision câblée, a
permis l'investissement des 100 millions de dollars qui étaient
nécessaires pour le musée et ses annexes, et vise à favoriser le
développement touristique d'une région frappée par le chômage.
</description>
</itemRef>8. Hierarchical Package Structure
Hierarchies of Groups and Item References can be created by adding multiple Groups to Packages and using <groupRef>, to reference other Groups by @idref, as illustrated by the following diagram:
The code listing below shows how such a hierarchical package would be fully expressed in XML in a NewsML-G2 Group Set:
All Scheme Aliases used in listing below indicate IPTC NewsCodes vocabularies, except for group,
<groupSet root="G1">
<group id="G1" role="group:main">
<itemRef residref="urn:newsml:iptc.org:20081007:tutorial—item-A"
contenttype="application/vnd.iptc.g2.newsitem+xml"
size="2345">
<itemClass qcode="ninat:text" />
<title>Obama annonce son équipe</title>
</itemRef>
<itemRef residref="urn:newsml:iptc.org:20081007:tutorial—item-B"
contenttype="application/vnd.iptc.g2.newsitem+xml"
size="300039">
<itemClass qcode="ninat:picture" />
<title>Barack Obama arrive à Washington</title>
</itemRef>
<groupRef idref="G2" />
</group>
<group id="G2" role="group:sidebar">
<itemRef residref="urn:newsml:iptc.org:20081007:tutorial—item-C"
contenttype="application/vnd.iptc.g2.newsitem+xml"
size="1503">
<itemClass qcode="ninat:text" />
<title>Clinton reprend son rôle de chef de la santé</title>
</itemRef>
<itemRef residref="urn:newsml:iptc.org:20081007:tutorial—item-D"
contenttype="application/vnd.iptc.g2.newsitem+xml"
size="350280">
<itemClass qcode="ninat:picture" />
<title>Hillary Clinton à une rassemblement à New York</title>
</itemRef>
</group>
</groupSet>In the example, the "root" group is identified as the group with id="G1". This group has a role of "main" and consists of a text story and a picture of Barack Obama. The group with id="G2" has the role of "sidebar" and contains a text and picture of Hillary Clinton. It is referenced by a <groupRef> in Group G1.
9. List Type Package Structure
The @mode indicates the relationship between components of a group using one of three values from the IPTC Package Group Mode NewsCodes (recommended Scheme Alias "pgrmod"):
-
pgrmod:bag – an unordered collection of components, for example different components of a web news page with no special order, as in the example below. This is the default @mode.
-
pgrmod:seq – denotes a sequential package group set in descending order, for example a "Top Ten" list: each sub-group would provide references to a text article and a related picture.
-
pgrmod:alt – an unordered collection. Each sub-group is an alternative to its peer groups in the set, for example coverage of a news event supplied in different languages.
The diagram above shows a package containing two Items in the root group, and a group reference to a "group of groups" with package mode set to "alt" indicating that the child groups contain alternative content. The example uses groups of associated video suitable for different Android device screen sizes as indicated by the @role of each group.
The code overview shows the root group referencing the two Items and the <groupRef> element referencing the group with @id "G2". Group G2 has its package mode set to "alt" and its components are references to alternate groups G3, G4 and G5, which reference videos at the required rendition for each screen type.
The right-hand image in the diagram is a visual representation of the relationship expressed through this package structure.
Note the <group> that has its Mode set to "alt" – not the "main" group but the second group with @id "G2". The components of this group are alternatives: each references a group containing the video content. The code example below shows how this relationship is fully expressed in NewsML-G2:
All Scheme Aliases used in listing below indicate IPTC NewsCodes vocabularies, except for group,
<groupSet root="G1">
<group id="G1" role="group:main">
<itemRef residref="urn:newsml:iptc.org:20081007:tutorial—item-A"
contenttype="application/vnd.iptc.g2.newsitem+xml"
size="2345">
<itemClass qcode="ninat:text" />
<title>Obama annonce son équipe</title>
</itemRef>
<itemRef residref="urn:newsml:iptc.org:20081007:tutorial—item-B"
contenttype="application/vnd.iptc.g2.newsitem+xml"
size="1503">
<itemClass qcode="ninat:text" />
<title>Clinton reprend son rôle de chef de la santé</title>
</itemRef>
<groupRef idref="G2" />
</group>
<group id="G2" role="group:video" mode="pgrmod:alt">
<groupRef idref="G3" />
<groupRef idref="G4" />
<groupRef idref="G5" />
</group>
<group id="G3" role="group:mdpi">
<itemRef residref="urn:newsml:iptc.org:20081007:tutorial—item-C"
contenttype="video/mp4" width="480" height="320">
<itemClass qcode="ninat:video" />
<title>Barack Obama arrive à Washington</title>
</itemRef>
<itemRef residref="urn:newsml:iptc.org:20081007:tutorial—item-D"
contenttype="video/mp4" width="480" height="320">
<itemClass qcode="ninat:video" />
<title>Hillary Clinton à une rassemblement à New York</title>
</itemRef>
</group>
<group id="G4" role="group:hdpi">
<itemRef residref="urn:newsml:iptc.org:20081007:tutorial—item-E"
contenttype="video/mp4" width="720" height="480">
<itemClass qcode="ninat:video" />
<title>Barack Obama arrive à Washington</title>
</itemRef>
<itemRef residref="urn:newsml:iptc.org:20081007:tutorial—item-F"
contenttype="video/mp4" width="720" height="480">
<itemClass qcode="ninat:video" />
<title>Hillary Clinton à une rassemblement à New York</title>
</itemRef>
</group>
<group id="G5" role="group:xhdpi">
<itemRef residref="urn:newsml:iptc.org:20081007:tutorial—item-G"
contenttype="video/mp4" width="960" height="640">
<itemClass qcode="ninat:video" />
<title>Barack Obama arrive à Washington</title>
</itemRef>
<itemRef residref="urn:newsml:iptc.org:20081007:tutorial—item-H"
contenttype="video/mp4" width="960" height="640">
<itemClass qcode="ninat:video" />
<title>Hillary Clinton à une rassemblement à New York</title>
</itemRef>
</group>
</groupSet>10. A Sequential "Top Ten" Package
The screenshot at the start of this Chapter shows a "Top Ten" list of news items in order of importance. The package mode of "seq" indicates that the components are in descending order and a code skeleton and visual representation of the package structure is shown in the diagram below:
Note how the <group> sets the Mode for its components, in this case the component group references of the "main" group are sequentially ordered. The relationship is fully-expressed in XML in NewsML-G2 as shown below:
All Scheme Aliases used in listing below indicate IPTC NewsCodes vocabularies, except for group,
<groupSet root="G1">
<group id="G1" role="group:main" mode="pgrmod:seq">
<groupRef idref="G2" />
<groupRef idref="G3" />
<groupRef idref="G4" />
<groupRef idref="G5" />
<groupRef idref="G6" />
<groupRef idref="G7" />
<groupRef idref="G8" />
<groupRef idref="G9" />
<groupRef idref="G10" />
<groupRef idref="G11" />
</group>
<group id="G2" role="group:top" >
<itemRef residref="urn:newsml:iptc.org:20081007:tutorial-item-A"
contenttype="application/vnd.iptc.g2.newsitem+xml"
size="3452">
<itemClass qcode="ninat:text" />
<provider qcode="nprov:AcmeNews"/>
<pubStatus qcode="stat:usable"/>
<title>Bank cuts interest rates to record low</title>
<description role="drol:summary">London (Reuters) - The Bank of England cut
interest rates by half a percentage point on Thursday to a record low of
1.5 percent and economists expect it to cut again in February as it
battles to prevent Britain from falling into a deep slump.
</description>
</itemRef>
<itemRef residref="urn:newsml:iptc.org:20081007:tutorial—item-B"
contenttype="application/vnd.iptc.g2.newsitem+xml"
size="230003">
<itemClass qcode="ninat:picture" />
<provider qcode="nprov:AcmeNews "/>
<pubStatus qcode="stat:usable"/>
<title>BoE Rate Decision</title>
</itemRef>
</group>
<group id="G3" role="group:two" >
<itemRef residref="urn:newsml:iptc.org:20081007:tutorial-item-C"
contenttype="application/vnd.iptc.g2.newsitem+xml"
size="2345">
<itemClass qcode="ninat:text" />
<provider qcode="nprov:AcmeNews"/>
<pubStatus qcode="stat:usable"/>
<title>Government denies it will print more cash</title>
<description role="drol:summary">London (Reuters) – Chancellor
Alistair Darling dismissed reports on Thursday that the government was about
to boost the money supply to ease the impact of recession.
</description>
</itemRef>
<itemRef residref="urn:newsml:iptc.org:20081007:tutorial—item-D"
contenttype="application/vnd.iptc.g2.newsitem+xml"
size="24065">
<itemClass qcode="ninat:picture" />
<provider qcode="nprov:AcmeNews "/>
<pubStatus qcode="stat:usable"/>
<title>Sterling notes and coin</title>
</itemRef>
</group>
<group id="G4" role="group:three" >
<itemRef residref="urn:newsml:iptc.org:20081007:tutorial-item-E"
contenttype="application/vnd.iptc.g2.newsitem+xml"
size="2345">
<itemClass qcode="ninat:text" />
<provider qcode="nprov:AcmeNews"/>
<pubStatus qcode="stat:usable"/>
<title>Rugby's Mike Tindall banned for drink-driving</title>
<description role="drol:summary">London (Reuters) - England rugby player Mike
Tindall was banned from driving for three years and fined £500 on Thursday
for his second drink-drive offence.
</description>
</itemRef>
<itemRef residref="urn:newsml:iptc.org:20081007:tutorial—item-F"
contenttype="application/vnd.iptc.g2.newsitem+xml"
size="25346">
<itemClass qcode="ninat:picture" />
<provider qcode="nprov:AcmeNews "/>
<pubStatus qcode="stat:usable"/>
<title>Mike Tindall in rugby action for England</title>
</itemRef>
</group>
<group id="G5" role="group:four" >
<itemRef residref="urn:newsml:iptc.org:20081007:tutorial—item-G"
contenttype="application/vnd.iptc.g2.newsitem+xml"
size="3654">
<itemClass qcode="ninat:text" />
<title>Crunch forces employees to work unpaid overtime</title>
</itemRef>
</group>
<group id="G6" role="group:five" >
<itemRef residref="urn:newsml:iptc.org:20081007:tutorial—item-H"
contenttype="application/vnd.iptc.g2.newsitem+xml"
size="5123">
<itemClass qcode="ninat:text" />
<title>Government warns of tax fraudsters</title>
</itemRef>
</group>
<group id="G7" role="group:six" >
<itemRef residref="urn:newsml:iptc.org:20081007:tutorial—item-I"
contenttype="application/vnd.iptc.g2.newsitem+xml"
size="4323">
<itemClass qcode="ninat:text" />
<title>Nissan to cut 1,200 jobs at Sunderland plant</title>
</itemRef>
</group>
<group id="G8" role="group:seven" >
<itemRef residref="urn:newsml:iptc.org:20081007:tutorial—item-J"
contenttype="application/vnd.iptc.g2.newsitem+xml"
size="3122">
<itemClass qcode="ninat:text" />
<title>Sainsbury sales tops forecast</title>
</itemRef>
</group>
<group id="G9" role="group:eight" >
<itemRef residref="urn:newsml:iptc.org:20081007:tutorial—item-K"
contenttype="video/mp4-480x320"
size="322443">
<itemClass qcode="ninat:video" />
<title>Cause of wind turbine damage unknown</title>
</itemRef>
</group>
<group id="G10" role="group:nine" >
<itemRef residref="urn:newsml:iptc.org:20081007:tutorial—item-L"
contenttype="application/vnd.iptc.g2.newsitem+xml"
size="4123">
<itemClass qcode="ninat:text" />
<title>Muslims warn Gaza crisis could provoke extremism</title>
</itemRef>
</group>
<group id="G11" role="group:ten" >
<itemRef residref="urn:newsml:iptc.org:20081007:tutorial—item-M"
contenttype="application/vnd.iptc.g2.newsitem+xml"
size="8192">
<itemClass qcode="ninat:text" />
<title>Banks hiring young Britons to prepare for upturn</title>
</itemRef>
</group>
</groupSet>11. Package Processing Considerations
11.1. Other NewsML-G2 Items
In the above examples, the referenced resources in the package have been News Items, but <itemRef> may also refer to other Items, such as Package Items. The following example of <itemRef> shows how a Package Item can be used as part of a Package Item. This type of "Super Package" could be used to send a "Top Ten" package (a themed list of news) where each referenced item is also a package consisting of references to the text, picture and video coverage of each news story.
The advantage of using this "package of packages" approach is that it promotes more efficient re-use of content. Once created, any of the "sub-packages" can be easily referenced by more than one "super-package": a package about a given story could be used by both "Top News This Hour" and by "Today’s Top News". If the individual News Items that make up a sub-package were to be referenced directly, these references have to be assembled each time the story is used, either by software or a journalist, which would be less efficient.
As these sub-packages are managed objects, we use @residref to identify and locate the referenced items. Each referenced item may be a Package Item, shown by the Item Class of "composite" and the Content Type of "application/vnd.iptc.g2.packageitem+xml". Each <itemRef> would then resemble the following:
<itemRef residref="tag:afp.com,2008:TX-PAR:20080529:JYC99"
contenttype="application/vnd.iptc.g2.packageitem+xml"
size="28047">
<itemClass qcode="ninat:composite" />
<provider qcode="nprov:AFP"/>
<pubStatus qcode="stat:usable"/>
<title>Tiger Woods cherche son retour</title>
<description role="drol:summary"> Tiger Woods lorem ipsum dolor sit amet,
consectetur adipiscing elit. Etiam feugiat. Pellentesque ut enim eget
eros volutpat consectetur. Quisque sollicitudin, tortor ut dapibus
porttitor, augue velit vulputate eros, in tempus orci nunc vitae nunc.
Nam et lacus ut leo convallis posuere. Nullam risus.
</description>
</itemRef>11.2. Facilitating the Exchange of Packages
There needs to be some consideration of how such a "Super Package" should be processed by the receiver. The power and flexibility inherent in NewsML-G2 Packages could lead to confusion and processing complexity unless provider and receiver agree on a method for specifying the structure of packages and signalling this to the receiving application. Processing hints such as the <profile> property (described above) intended to help resolve this issue.
In the example below, we maintain flexibility and inter-operability with potential partner organisations by defining any number of standard package "templates" – termed Profiles – for the Package, among other processing hints. Partners would agree in advance on the Profiles and rules for processing them. All that the provider then needs to do is place the pre-arranged Profile name, or the name of a transformation script, in the <profile> property.
Package profiles could be represented as diagrams like those shown below:
In this example, the Profile Name is intended to be a signal to the processor that references to each member of the Top Ten list are placed in their own group, and that we create our Top Ten list in the "root" group of the Package Item as an ordered list of <groupRef> elements. (as in the "Top Ten" list profile shown in the above diagram)
The properties in <itemMeta> that can be used to provide information on processing are:
<generator>, a versioned string denoting the name of the process or service that created the package:
<generator versioninfo="3.0">MyNews Top Ten Packager</generator><profile>, as discussed, sets the template or transformation stylesheet of the package
<profile versioninfo="1.0.0.2">ranked_idref_list</profile><signal> is a flexible type property (may have a @qcode, @uri, or @literal value) that instructs the receiver to perform any required actions upon receiving the Item. An <edNote> may contain natural-language instructions, if necessary, and a <link> property denotes the previous version of the package.
<signal qcode="signal:update" />
<edNote>Updates the previous package</edNote>
<link
rel="irel:previousVersion"
residref="tag:example.com,2008:UK-NEWS-TOPTEN:UK20081220098658"
version="1"
/>