1. Introduction: ninjs is News in JSON
ninjs standardises the representation of news content in JSON, a lightweight, easy-to-parse data interchange format.
We have identified key properties and structures required to represent news and publishing information, and crafted JSON representations that are designed to result in lightweight instance documents. While keeping it simple, we have been careful to map ninjs concepts to the IPTC News Architecture, so you can rest assured that ninjs concepts can interoperate with other markup languages such as NewsML-G2.
We have created some tools to help get users started. These include a simple ninjs generator that shows how easily a real ninjs document can be created, and a JSON schema to validate ninjs objects.
The latest version of the standard is 3.0. Version 3.0 of the ninjs schema was made available in November 2024.
The latest version in the 2.x branch is 2.1, which was made avaialble in June 2023. See below for more information on the differences between the 1.x and 2.x branches.
The latest version in the 1.x branch is 1.5, which was also made avaialble in June 2023. See below for more information on the differences between the 1.x and 2.x branches.
1.1. Built for both APIs and data at rest
In creating ninjs, we focused on two main use cases:
-
Data interchange - such as via APIs
-
ninjs documents can be very concise, allowing for the inclusion of just the most important properties - such as byline, headline, and body text - as determined by a given provider.
-
ninjs allows the provider to indicate whether there are more properties available using the
representationtype: "partial"
construct. -
Version 3.x of ninjs has been created to work well with both GraphQL and OpenAPI/Swagger, the two main standards for JSON-based APIs.
-
Versions 2.x and 3.x of the ninjs schema have been created in such a way that they can easily be converted into a schema for a binary data serialisation protocol such as Protocol Buffers, Avro, Thrift or CBOR / CDDL. We include a Protocol Buffers schema in the GitHub repository as an example.
-
-
Data at rest - such as in search engines or content management systems
-
ninjs documents can convey a rich set of news publishing properties, such as information that is necessary for the pre-publishing workflow or custom properties that a particular provider wants to express in a standard way.
-
ninjs is designed to be customisable by a particular provider, so that they can express just what they require, without unnecessary overhead. ninjs is suitable for use in JSON-native engines, such as MongoDB or Elasticsearch.
-
1.2. The ninjs data model in a nutshell
As the below diagram shows, every ninjs object describes an Item - either a News Item, Planning Item or Event. All ninjs items must have a unique ID given by a URI. They can have administrative metadata (describing who created the news item and when), descriptive metadata (describing people, places, genres, subjects, organisations and events related to the item) and rights-based metadata (copyright, licensing and usage terms).
The content of the item can be a body, containing text, HTML or other representation of the text of a news item, renditions of the news item as images, videos or multimedia, or both body and renditions.
Associations are a means of linking ninjs items together.
1.4. A simple example
ninjs can be very simple. This is an example of something that might be returned by an API call.
-
ninjs 3.0
-
ninjs 2.1
-
ninjs 1.5
{
"uri" : "http://ninjs.example.com/newsitems/20130709simp123",
"type" : "text",
"versionCreated" : "2013-07-09T10:37:00Z",
"by" : "Paulo Santalucia and Frances d'Emilio",
"headlines" : [
{
"role": "main",
"value": "Captain of wrecked cruise ship on trial in Italy"
}
],
"bodies" : [
{
"role": "main",
"value": "GROSSETO, Italy (AP) -- The trial of the captain of the shipwrecked Costa Concordia cruise liner has begun in a theater converted into a courtroom in Tuscany to accommodate all the survivors and relatives of the 32 victims who want to see justice carried out in the 2012 tragedy. The sole defendant, Francesco Schettino, his eyes shaded by sunglasses and slipping into a back door, made no comment to reporters as he arrived for his trial Tuesday on charges of multiple manslaughter, abandoning ship and causing the shipwreck near the island of Giglio. His lawyer, Domenico Pepe, told reporters that, as expected, the judge was postponing the hearing due to an eight-day nationwide lawyers' strike. Pepe said some 1,000 witnesses are expected to eventually testify. Many of them are expected to be from among the 4,200 passengers and crew aboard the ship that struck a jagged reef off Giglio, took on water and capsized. Schettino has denied wrongdoing."
}
]
}
{
"uri" : "http://ninjs.example.com/newsitems/20130709simp123",
"type" : "text",
"versioncreated" : "2013-07-09T10:37:00Z",
"by" : "Paulo Santalucia and Frances d'Emilio",
"headlines" : [
{
"role": "main",
"value": "Captain of wrecked cruise ship on trial in Italy"
}
],
"bodies" : [
{
"role": "main",
"value": "GROSSETO, Italy (AP) -- The trial of the captain of the shipwrecked Costa Concordia cruise liner has begun in a theater converted into a courtroom in Tuscany to accommodate all the survivors and relatives of the 32 victims who want to see justice carried out in the 2012 tragedy. The sole defendant, Francesco Schettino, his eyes shaded by sunglasses and slipping into a back door, made no comment to reporters as he arrived for his trial Tuesday on charges of multiple manslaughter, abandoning ship and causing the shipwreck near the island of Giglio. His lawyer, Domenico Pepe, told reporters that, as expected, the judge was postponing the hearing due to an eight-day nationwide lawyers' strike. Pepe said some 1,000 witnesses are expected to eventually testify. Many of them are expected to be from among the 4,200 passengers and crew aboard the ship that struck a jagged reef off Giglio, took on water and capsized. Schettino has denied wrongdoing."
}
]
}
{
"uri" : "http://ninjs.example.com/newsitems/20130709simp123",
"type" : "text",
"versioncreated" : "2013-07-09T10:37:00Z",
"byline" : "Paulo Santalucia and Frances d'Emilio",
"headline_main": "Captain of wrecked cruise ship on trial in Italy",
"body_main": "GROSSETO, Italy (AP) -- The trial of the captain of the shipwrecked Costa Concordia cruise liner has begun in a theater converted into a courtroom in Tuscany to accommodate all the survivors and relatives of the 32 victims who want to see justice carried out in the 2012 tragedy. The sole defendant, Francesco Schettino, his eyes shaded by sunglasses and slipping into a back door, made no comment to reporters as he arrived for his trial Tuesday on charges of multiple manslaughter, abandoning ship and causing the shipwreck near the island of Giglio. His lawyer, Domenico Pepe, told reporters that, as expected, the judge was postponing the hearing due to an eight-day nationwide lawyers' strike. Pepe said some 1,000 witnesses are expected to eventually testify. Many of them are expected to be from among the 4,200 passengers and crew aboard the ship that struck a jagged reef off Giglio, took on water and capsized. Schettino has denied wrongdoing."
}
You can make your own ninjs documents for demonstration or testing purposes using the ninjs generator tool on iptc.org.
1.5. Versions of ninjs: ninjs 3.0, 2.1 and 1.5
IPTC manages three versions of ninjs: the 3.x branch (where the latest version is 3.0), the 2.x branch (where the latest version is 2.1) and the 1.x branch (where the latest version is 1.5).
The 1.x series continues the version of ninjs that started with ninjs 1.0 in
2013, adding new features in a way that is fully backwards-compatible. The
latest release in this series is 1.5, which includes new properties such as
contactinfo
, symbol
and symboltype
(see the full list of
changes).
The 2.x series fixes some issues that made the 1.x series tricky for some developers to work with. The main change is that ninjs 2.x avoids the use of patternProperties, so all properties now have well-defined names. This change is intended to make ninjs easier for projects based on binary protocols such as Protocol Buffers and Avro. We also took the opportunity to make property names more consistent with NewsML-G2 and to add some fields to handle rights.
The 3.x series includes support for news planning and events, including live events. It also adds support for live streamed renditions. In a major change, we also change the case of all ninjs properties to "camelCase" format, in keeping with JSON best practices, especially regarding GraphQL usage. ninjs 3.0 was created alongside the LPX (Live Production Exchange) project from the DPP, with the help of experts from CNN, Reuters, Arqiva and more.
All new users are strongly recommended to use version 3.0.
ninjs 3.0 was approved by the IPTC Standards Committee on October 2nd, 2024. The 2.1 and 1.5 versions of ninjs were approved by the IPTC Standards Committee on May 17th, 2023.
This document focuses on the 3.0 version, but includes notes where the 2.x and 1.x versions differ. Those who must use version 2.x or 1.x for backwards compatibility reasons can find the JSON Schema file for ninjs 2.1 at https://iptc.org/std/ninjs/ninjs-schema_2.1.json and the schema file for ninjs 1.5 at https://iptc.org/std/ninjs/ninjs-schema_1.5.json.
1.6. Differences between ninjs 1.x, 2.x and 3.x
We maintain the 1.x and 2.x branches for those who can’t move to the new 3.0 version.
1.6.1. patternProperties vs arrays
In the ninjs 1.x schema, some properties are implemented as "patternProperties",
which means that the name must start with a certain text string (such as headline_
)
but can end in any string (such as subhead
). This was used to distinguish objects
from each other.
This can cause problems with binary serialisations and queries based on the schema, including Protocol Buffers, Avro, CBOR and GraphQL which all require well-known, pre- defined property names.
Therefore, in the 2.x and 3.x versions of the schema, we instead use simple arrays
with well-defined names, and a role
property that defines the type of the value.
For example, a subheadline is defined in ninjs 1.x as
{
"headline_subhead": "My subheadline"
}
The same subheadline would be defined in ninjs 2.x or 3.x as
{
"headlines": [
{
"role": "subhead",
"value": "My subheadline"
}
]
}
This applies to the following properties:
-
description_XXX
(1.x) /descriptions
(2.x, 3.x) -
body_XXX
(1.x) /bodies
(2.x, 3.x) -
headline_XXX
(1.x) /headlines
(2.x, 3.x)
1.6.2. Renditions and Associations converted to arrays
The renditions
and associations
properties are objects in ninjs 1.x,
using the object name as the distinguishing element. This caused similar
problems, so we use arrays in ninjs 2.x and 3.x.
For example, in ninjs 1.x a rendition may look like the following:
{
"renditions": {
"highres": {
...
}
}
}
The same rendition in ninjs 2.x or 3.x would look like:
{
"renditions": [
{
"name": "highres",
...
}
]
}
Associations work the same way in all ninjs versions.
1.6.3. Property names converted to plural form
In addition, the following property names were converted to plural form for ninjs 2.x. They were not changed in any other way.
In ninjs 3.x, property names were converted to camelCase.
ninjs 1.x | ninjs 2.x | ninjs 3.x |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
1.7. Which version of ninjs should I choose for my project?
If you are starting a green-field project, we recommend using the latest version in the ninjs 3.x branch, currently ninjs 3.0. This version should be easiest for developers to work with.
If you are already using a 1.x or 2.x version of ninjs, we recommend at least upgrading to the latest version in that branch, currently 1.5 and 2.1. This should be an easy change, because all new minor versions in a branch are backwards-compatible with earlier minor versions in the same branch.
1.8. ninjs and other standards
JSON is an increasingly popular alternative to (or replacement for) XML. ninjs is designed in such a way that it can be used either standalone or alongside other IPTC news markup formats such as NewsML-G2, NITF, IPTC7901 and rNews.
2. About the IPTC ninjs User Guide
2.1. Copyright
Copyright © 2024 IPTC, International Press Telecommunications Council.
The IPTC ninjs User Guide document is published under the Creative Commons Attribution 4.0 license - see the full license agreement at http://creativecommons.org/licenses/by/4.0/.
By obtaining, using and/or copying this document, you (the licensee) agree that you have read, understood, and will comply with the terms and conditions of the license.
Materials used in this guide are either in the public domain or are available with the permission of their respective copyright holders. All materials of this IPTC standard covered by copyright shall be licensable at no charge.
2.2. Acknowledgements
This document is the result of a team effort by members of the News in JSON Working Group of the International Press Telecommunications Council (IPTC), with input and assistance from other contributors.
Contributors to this document include: Paul Harman (Bloomberg), Johan Lindgren (TT), Stuart Myles (previously with AP), Brendan Quinn (IPTC), Michael Steidl (previous with IPTC), Evan Sandhaus (previously with NYT), and Ian Young (PA Media / Alamy).
2.3. How to contact IPTC
All users of ninjs are encouraged to join the public IPTC ninjs discussion group: https://groups.io/g/iptc-ninjs/
Staff from organisations who are members of the IPTC are welcome to join the members-only discussion list for the ninjs development team.
For questions, comments or suggestions, you can raise an issue on our public GitHub repository: https://github.com/iptc/newsinjson/issues
You can also submit a message on our website: https://iptc.org/about-iptc/contact-us/
Visit the ninjs section on IPTC’s website: https://iptc.org/standards/ninjs/
To stay up to date on developments with ninjs and other areas, follow IPTC on Twitter: @IPTC
2.4. About IPTC
The IPTC, based in London, brings together the world’s leading news agencies, publishers and industry vendors. It develops and promotes efficient technical standards to improve the management and exchange of information between content providers, intermediaries and consumers. IPTC standards enable easy, cost-effective and rapid innovation and include the IPTC Photo Metadata standard, the Video Metadata Hub, the news exchange formats NewsML-G2, ninjs, SportsML-G2 and NITF, rNews for marking up online news, the rights expression language RightsML, and NewsCodes taxonomies for categorising news.
IPTC is a not-for-profit membership organisation registered in England. Find more about joining IPTC.
Business address:
IPTC International Press Telecommunications Council 25 Southampton Buildings London WC2A 1AL United Kingdom
3. ninjs in Detail
Here we document each property that can be used in a ninjs object.
The "uri" property is required at the top level. In some array objects, other
properties may be required; for example, if rightsInfo
is used, then either
linkedRights
or encodedRights
is required.
These tables primarily describe the ninjs 3.0 schema. Where possible, we note differences in the 1.x and 2.x schemas, but the ultimate reference for each version of ninjs is the relevant JSON Schema file.
3.1. Administrative properties
These properties concern the structure, type and creation details of the content.
ninjs 3.0 property |
ninjs 1.x / 2.x property |
Description | Data type | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
The identifier for this news object |
URI |
||||||||||||
|
|
The generic news type of this news object |
One of: |
||||||||||||
|
|
A short natural-language name for the item. |
string |
||||||||||||
|
|
An object with information about standard, version and schema this instance is valid against.
|
object |
||||||||||||
|
|
Alternative identifiers for the item. It is up to the individual provider to
name and set type on the alternative identifiers they like to use.
|
array of objects (2.x, 3.x) |
||||||||||||
|
|
Indicates the completeness of this representation of a news item. |
One of: |
||||||||||||
|
|
An identifier for the structure of the news object. This can be any string but we suggest something identifying the structure of the content such as |
string |
||||||||||||
|
|
The version of the news object which is identified by the uri property. |
string |
||||||||||||
|
|
Indicates when the first version of the item was created. |
date-time |
||||||||||||
|
|
The date and time when this version of the news object was created. |
date-time |
||||||||||||
|
|
The date and time when the content of this ninjs object was originally created. |
date-time |
||||||||||||
|
|
The date and time before which all versions of the news object are embargoed. If absent, this object is not embargoed. |
date-time |
||||||||||||
|
|
The date and time after which the Item is no longer considered editorially relevant by its provider. nar:expires (Added in ninjs 2.1) |
date-time |
||||||||||||
|
|
The publishing status of the news object, its value is |
One of: |
||||||||||||
|
|
The editorial urgency of the content from 1 to 9. 1 represents the highest urgency, 9 the lowest. |
number |
||||||||||||
|
|
A note that is intended to be read by internal staff at the receiving organisation, but not published to the end-user. |
string |
||||||||||||
|
|
The human language used by the content. The value should follow IETF BCP47 format. |
string |
3.2. Rights properties
3.3. Editorial properties
Properties representing the actual story that will be shown to the audience.
ninjs 3.0 property |
ninjs 1.x / 2.x property |
Description | Data type | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
(in 2.x and 3.x) An array of objects containing various types of headlines.
|
Array of objects |
||||||||||||||||||
|
|
A human-readable identifier for the item. |
string |
||||||||||||||||||
|
|
The name(s) of the creator(s) of the content |
string |
||||||||||||||||||
|
|
An array of body objects with the content as text or with markup.
|
Array of objects |
||||||||||||||||||
|
|
An array of one or more descriptions of the ninjs object. See also ednote for information from provider to reciever. Descriptions are seen as metadata. This property is an object with the following child properties:
|
Array of objects |
3.4. Metadata properties
ninjs allows content to be marked up with one simple string-based metadata property located
, plus several rich metadata properties that can link to pre-defined controlled vocabularies describing people, organisations, places subjects, objects and events.
ninjs 3.0 property |
ninjs 1.x / 2.x property |
Description | Data type | ||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
The name of the location from which the content originates.
|
string |
||||||||||||||||||||||||
|
|
The nature, intellectual or journalistic form of the content. This property is an array of objects with the following properties:
|
array |
||||||||||||||||||||||||
|
|
An array of objects describing individual human beings.
|
array |
||||||||||||||||||||||||
|
|
An array of objects describing administrative and functional structures which may act as as a business, as a political party or not-for-profit party. |
array |
||||||||||||||||||||||||
|
|
An array of named locations.
|
array |
||||||||||||||||||||||||
|
|
An array of objects holding concepts with a relationship to the content.
|
array |
||||||||||||||||||||||||
|
|
An array of objects describing something which happens in a planned or unplanned manner.
|
array |
||||||||||||||||||||||||
|
|
An array of objects describing something material, excluding persons.
|
array |
||||||||||||||||||||||||
|
|
An array of parties (person or organisation) which originated, modified, enhanced, distributed, aggregated or supplied the content or provided some information used to create or enhance the content.
|
array |
||||||||||||||||||||||||
|
|
An array of objects to allow links to documents about trust indicators, intended to show
the trustworthiness of the news provider.
|
array |
3.4.1. Contact Info structure
The Contact Info structure is used for the contents of the contactinfo
property in items in the people
, organisations
, places
and infosources
arrays.
Property name | Description | Data type | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Type would be method of communication like phone, mobile, address etc. |
string |
||||||||||||||||||
|
Role refers to type and could be private, office etc |
string |
||||||||||||||||||
|
If this contactinfo object need to be qualified with what language it is in. The value should follow IETF BCP47. |
string |
||||||||||||||||||
|
Human readable name of the contact method, like name for a web page, name of persons twitter account etc |
string |
||||||||||||||||||
|
Actual phone number, email address, web url etc. |
string |
||||||||||||||||||
|
The address of a person, place or organisation.
|
object |
3.4.2. Organisation Structure
The Contact Info structure is used for the contents of the contactinfo
property in items in the people
, organisations
, places
and infosources
arrays.
Property name | Description | Data type |
---|---|---|
|
The name of the organisation |
string |
|
The relationship of the content of the news object to the organisation |
string |
|
The identifier of the organisation as a complete uri |
URI |
|
The code for the organisation as a literal |
string |
|
Symbols used for a financial instrument linked to the organisation at a specific market place.
|
array |
|
Contact and/or location information for the organisation as a ContactInfo structure. |
4. Events and Planned Coverage
This section applies to ninjs 3.0 only. |
A news organisation may wish to distribute information about forthcoming events and planned news coverage in advance of the event. In this way, customers of the news organisation (for example, news outlets and broadcasters who are customers of a wire service) can plan to broadcast or republish the coverage, or plan their own coverage around the work of the upstream news provider.
To handle this in ninjs, we introduce events and planned coverage. The event includes information about a real-world event that is being covered in some way. The planning item includes information about news coverage that the provider intends to release at some point in the future.
4.1. Events
A ninjs event conveys information about a real-world event that may (or may not) be covered by a news organisation: a press conference, a sports event, a webinar, an election.
Information about the event may change over time. For example, we know that there will be a Summer Olympic Games in Brisbane in 2032, but we don’t yet know the start time of the Opening Ceremony.
While specifying an event, we can include as much or as little information as we have at the time.
Here’s an example of a simple event:
-
ninjs 3.0
-
ninjs 2.1
-
ninjs 1.5
{
"standard": {
"name": "ninjs",
"version": "3.0",
"schema": "http://www.iptc.org/std/ninjs/ninjs-schema_3.0.json"
},
"uri": "urn:nato.int:2023-nato-summit-press-conference",
"type": "event",
"title": "2023 NATO Summit Press Conference",
"eventDetails": {
"dates": {
"expectedStartDate": "2023-07-11"
}
},
"places": [
{
"name": "LITEXPO",
"contactInfo": [
{
"type": "physical",
"address": {
"locality": "Vilnius",
"country": "Lithuania"
}
}
]
}
]
}
Planned news events are not handled in ninjs 2.1.
Planned news events are not handled in ninjs 1.5.
The main new object to cover such events is the eventDetails object, which contains the following properties:
Property name | Description | Data type |
---|---|---|
|
Status of the event (as opposed to the status of coverage of the event). |
uri |
|
Status of the coverage (as opposed to the status of the event itself). |
uri |
|
Dates and times for this event. |
|
|
A person or organisation organising the event. |
Events include a rich date structure which allows for uncertain start and end dates and times and also recurring events. The data model is based on EventsML-G2, part of the NewsML-G2 family of standards.
It’s worth noting that this is different from the events metadata object used for news items. That object is intended to convey metadata about an event that is related to a published news item. |
4.2. Planned Coverage
A ninjs item may contain a plannedCoverage
property which contains an array of planned coverage items using the following structure:
Property name (3.0 only) |
Description | Data type | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
The local identifier of the element which MUST be persistent for all versions of the item, i.e. for its entire lifecycle.", |
string |
||||||||||||
|
A human-readable title for the planned content", |
string |
||||||||||||
|
The publishing status of the plannedCoverage object, its value is usable by default. nar:pubStatus |
string with possible values "usable", "withheld" |
||||||||||||
|
The generic news type of the planned content. |
One of: |
||||||||||||
|
Information about the commissioning of this content. |
|||||||||||||
|
Dates and times for this planned content. |
|||||||||||||
|
Intended audiences for the planned content. Array of objects with the following structure:
|
Array of objects |
||||||||||||
|
Additional natural language information about the planned content addressed to the editorial people receiving and processing the item. |
string |
||||||||||||
|
The editorial urgency of the planned content, as scoped by the parent element. |
number (1-9) |
||||||||||||
|
The human language used by the planned content. The value should follow IETF BCP47. |
string |
||||||||||||
itemCount` |
Number of planned items of this kind expressed by a range. This is an object with the following structure:
|
object |
||||||||||||
|
The count of words of textual content. |
integer |
||||||||||||
|
An array of objects showing the planned renditions of the news object. |
Array of rendition objects |
4.2.1. Commissioning Structure
Property name (3.0 only) |
Description | Data type | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
|
The person or party that commissioned the content. |
string |
|||||||||
|
The date at which the content was commissioned. |
date-time |
|||||||||
|
Identifiers that help with the commissioning process such as purchase orders and work order numbers.
|
Array of objects |
4.3. Dates for Events and Planning
This section applies to dates in events and news coverage planning items in ninjs 3.0 only. |
A news organisation may wish to distribute information about forthcoming events and planned news coverage that has not yet been finalised. Therefore dates and times may not yet be known.
Also, events may recur at regular intervals.
To handle this situation, in ninjs 3.0 we introduce a dates
object which contains several properties:
Property name (3.0 only) |
Description | Data type | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
|
The date and time at which the event starts (if known) |
date-time |
|||||||||
|
The date and time at which the event ends (if known) |
date-time |
|||||||||
|
The approximate date (and optionally time) at which the event or coverage is expected to start. |
||||||||||
|
The approximate date (and optionally time) at which the event or coverage is expected to end. |
||||||||||
|
The time period that the event or coverage is expected to last. Must use the iCalendar duration format (RFC 5545). (Actual duration can be calculated from startDate and endDate) |
string |
|||||||||
|
Specifies recurrence information about the event.
|
object |
The above date object can be used for [eventDetails/dates] and [plannedCoverage/dates].
4.3.1. Truncated DateTime
Used in expectedStartDate, expectedEndDate and the recurrenceDates property of Recurrence Rules, the "truncated DateTime" is a property that allows dates to be "truncated from the right", i.e. specified with resolution of only the year, year/month, year/month/day or other combinations.
This is based on the equivalent TruncatedDateTime type in NewsML-G2 and is implemented in ninjs using a regular expression.
The full list of allowed date/time parts is:
-
year only (xs:gYear, YYYY)
-
year/month (xs:gYearMonth, YYYY-MM)
-
year/month/day (xs:date YYYY-MM-DD)
-
full datetime (xs:dateTime, YYYY-MM-DDTHH:MM:SS+HH:MM)
All of these can carry an optional timezone suffix.
Note that this does NOT include ISO8601 month of year (xs:gMonth, --MM) or yearly day (xs:gMonthDay, --MM-DD)
Note that other date objects (startDate, endDate, firstCreated, versionCreated etc) require a fully-specified ISO8601 date and time.
4.3.2. Recurrence Rules
Used to specify recurring events within the recurrenceRules property.
This follows the structure of EventsML-G2 / NewsML-G2 recurrence rules, which in turn follows the iCalendar specification.
Property name (3.0 only) |
Description | Data type |
---|---|---|
|
The FREQ rule part identifies the type of recurrence rule. |
string: one of: |
|
The INTERVAL rule part contains a positive integer representing how often the recurrence rule repeats. |
integer |
|
The UNTIL rule part defines a date-time value which bounds the recurrence rule in an inclusive manner.", |
date-time |
|
The COUNT rule part defines the number of occurrences at which to range-bound the recurrence. |
integer |
4.4. Renditions
The renditions
property is a wrapper for different renditions of content of the news object, such as articles, images, videos or PDF documents.
It contains a set of one or more keys, each with a name and an object as the value. The name can be any text or numbers, and should represent a given rendition type such as "thumbnail" or "preview". The object should include the below properties.
4.4.1. Properties of renditions
ninjs 3.0 property |
ninjs 1.x / 2.x property |
Description | Data type | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
The name of this object in the array of renditions. Required. |
string |
|||||||||
|
|
The URL for accessing the rendition as a resource. |
URI |
|||||||||
|
|
The IANA Media Type which applies to this rendition. |
string |
|||||||||
|
|
A title for the link to the rendition resource. |
string |
|||||||||
|
|
For still and moving images: the height of the display area measured in pixels. |
integer (3.0) |
|||||||||
|
|
For still and moving images: the width of the display area measured in pixels. |
integer (3.0) |
|||||||||
|
|
The size of the rendition resource in bytes. |
integer (3.0) |
|||||||||
|
|
The total time duration of the content in seconds (fractional seconds are allowed) |
number |
|||||||||
|
|
A refinement of a generic content type (i.e. IANA media type) by a literal string value. |
string |
|||||||||
|
n/a |
Aspect ratio of the video file, which is the ratio of the width of video to its height, such as 16:9 and 4:3. |
string |
|||||||||
|
n/a |
The video encoding system used to create the content. Suggested CV: http://cv.iptc.org/newscodes/videocodec/ |
string |
|||||||||
|
n/a |
The number of video frames per second, which is the rate at which the material should be shown in order to achieve the intended visual effect |
number |
|||||||||
|
n/a |
The point of interest of the rendition. This property is an object with the following child properties:
|
object |
|||||||||
|
n/a |
The transport/flow type of the flow (B2B stream). |
string |
|||||||||
|
n/a |
The scan type of the video. The only allowed values are 'progressive' and 'interlaced'. |
One of: |
|||||||||
|
n/a |
The bitrate of the video. Should always include units, eg 400 kbps. |
string |
4.4.2. Renditions example
-
ninjs 3.0
-
ninjs 2.1
-
ninjs 1.5
{
"uri": "renditions-example",
"bodies": [
{
"value": "..."
}
],
"renditions": [
{
"name": "thumbnail",
"href": "http://mms.businesswire.com/media/newsItemId/en/221373/2/dell_blue_rgb.jpg",
"contentType": "image/jpeg",
"height": 70,
"width": 70,
"sizeInBytes": 4380
},
{
"name": "highres",
"href": "http://mms.businesswire.com/media/newsItemId/en/221373/5/dell_blue_rgb.jpg",
"contentType": "image/jpeg",
"height": 432,
"width": 432,
"sizeInBytes": 33116
}
]
}
{
"uri": "renditions-example",
"bodies": [
{
"value": "..."
}
],
"renditions": [
{
"name": "thumbnail",
"href": "http://mms.businesswire.com/media/newsItemId/en/221373/2/dell_blue_rgb.jpg",
"contenttype": "image/jpeg",
"height": 70,
"width": 70,
"sizeinbytes": 4380
},
{
"name": "highres",
"href": "http://mms.businesswire.com/media/newsItemId/en/221373/5/dell_blue_rgb.jpg",
"contenttype": "image/jpeg",
"height": 432,
"width": 432,
"sizeinbytes": 33116
}
]
}
{
"uri": "renditions-example",
"body_main": "...",
"renditions": {
"thumbnmail": {
"href": "http://mms.businesswire.com/media/newsItemId/en/221373/2/dell_blue_rgb.jpg",
"mimetype": "image/jpeg",
"height": 70,
"width": 70,
"sizeinbytes": 4380
},
"highres": {
"href": "http://mms.businesswire.com/media/newsItemId/en/221373/5/dell_blue_rgb.jpg",
"mimetype": "image/jpeg",
"height": 432,
"width": 432,
"sizeinbytes": 33116
}
}
}
4.5. Associations
The associations
property contains associated valid ninjs objects, each with a required name
explaining the nature of the association.
This can be used to link news items together, or to associate images with a text story, for example.
4.5.1. Associations example
This example shows a press release. The body of the story is in the single object in the bodies
property. A logo and an image are associated to the story. Both the logo and the image have two renditions, a "thumbnail" and a "highres" version.
-
ninjs 3.0
-
ninjs 2.1
-
ninjs 1.5
{
"uri": "http://www.businesswire.com/news/home/20130515006361/en",
"type":"composite",
"version": "1",
"versionCreated": "2013-05-16T04:01:00Z",
"headlines": [
{
"role": "simple",
"contentType": "text/plain",
"value": "Dell Redefines Workstation Computing Boundaries with Smallest Tower and Most Powerful Rack Workstations"
}
],
"bodies": [
{
"role": "richtext",
"contentType": "application/xhtml+xml",
"value": "[ ... ]"
}
],
"associations": [
{
"name": "logo",
"uri":"http://mms.businesswire.com/media/newsItemId/en/221373/3/dell_blue_rgb.jpg",
"type":"graphic",
"versionCreated": "2013-05-16T04:01:00Z",
"renditions": [
{
"name": "thumbnail"
},
{
"name": "highres"
}
]
},
{
"name": "photo",
"uri":"http://mms.businesswire.com/media/newsItemId/en/369394/3/0025lf.jpg",
"type":"picture",
"versionCreated": "2013-05-16T04:01:00Z",
"renditions": [
{
"name": "thumbnail"
},
{
"name": "highres"
}
]
}
]
}
{
"uri": "http://www.businesswire.com/news/home/20130515006361/en",
"type":"composite",
"version": "1",
"versioncreated": "2013-05-16T04:01:00Z",
"headlines": [
{
"role": "simple",
"contenttype": "text/plain",
"value": "Dell Redefines Workstation Computing Boundaries with Smallest Tower and Most Powerful Rack Workstations"
}
],
"bodies": [
{
"role": "richtext",
"contenttype": "application/xhtml+xml",
"value": "[ ... ]"
}
],
"associations": [
{
"name": "logo",
"uri":"http://mms.businesswire.com/media/newsItemId/en/221373/3/dell_blue_rgb.jpg",
"type":"graphic",
"versioncreated": "2013-05-16T04:01:00Z",
"renditions": [
{
"name": "thumbnail"
},
{
"name": "highres"
}
]
},
{
"name": "photo",
"uri":"http://mms.businesswire.com/media/newsItemId/en/369394/3/0025lf.jpg",
"type":"picture",
"versioncreated": "2013-05-16T04:01:00Z",
"renditions": [
{
"name": "thumbnail"
},
{
"name": "highres"
}
]
}
]
}
{
"uri": "http://www.businesswire.com/news/home/20130515006361/en",
"type":"composite",
"version": "1",
"versioncreated": "2013-05-16T04:01:00Z",
"headline_simple": "Dell Redefines Workstation Computing Boundaries with Smallest Tower and Most Powerful Rack Workstations",
"body_richtext": "[ ... ]",
"associations": {
"logo": {
"uri":"http://mms.businesswire.com/media/newsItemId/en/221373/3/dell_blue_rgb.jpg",
"type":"graphic",
"versioncreated": "2013-05-16T04:01:00Z",
"renditions": {
"thumbnail": { },
"hughres": { }
}
},
"photo": {
"uri":"http://mms.businesswire.com/media/newsItemId/en/369394/3/0025lf.jpg",
"type":"picture",
"versioncreated": "2013-05-16T04:01:00Z",
"renditions": {
"thumbnail": { },
"hughres": { }
}
}
}
}
5. ninjs Examples
5.1. Text-only examples
5.1.1. A simple text article
Key features:
-
A
uri
must be present as an identifier for this content -
type
indicates that the generic content type is 'text' -
by
andheadlines
are typical text news metadata -
The text of article itself is represented by
bodies
, in two format variants: plain text and HTML.
-
ninjs 3.0
-
ninjs 2.1
-
ninjs 1.5
{
"uri" : "http://ninjs.example.com/newsitems/20130709simp123",
"type" : "text",
"versionCreated" : "2013-07-09T10:37:00Z",
"by" : "Paulo Santalucia and Frances d'Emilio",
"headlines" : [
{
"role": "main",
"value": "Captain of wrecked cruise ship on trial in Italy"
}
],
"bodies" : [
{
"role": "main",
"contentType": "text/plain",
"value": "GROSSETO, Italy (AP) -- The trial of the captain of the shipwrecked Costa Concordia cruise liner has begun in a theater converted into a courtroom in Tuscany to accommodate all the survivors and relatives of the 32 victims who want to see justice carried out in the 2012 tragedy. The sole defendant, Francesco Schettino, his eyes shaded by sunglasses and slipping into a back door, made no comment to reporters as he arrived for his trial Tuesday on charges of multiple manslaughter, abandoning ship and causing the shipwreck near the island of Giglio. His lawyer, Domenico Pepe, told reporters that, as expected, the judge was postponing the hearing due to an eight-day nationwide lawyers' strike. Pepe said some 1,000 witnesses are expected to eventually testify. Many of them are expected to be from among the 4,200 passengers and crew aboard the ship that struck a jagged reef off Giglio, took on water and capsized. Schettino has denied wrongdoing."
},
{
"role": "richtext",
"contentType": "body_xhtml",
"value": "<p>GROSSETO, Italy (AP) -- The trial of the captain of the shipwrecked Costa Concordia cruise liner has begun in a theater converted into a courtroom in Tuscany to accommodate all the survivors and relatives of the 32 victims who want to see justice carried out in the 2012 tragedy.</p> <p>The sole defendant, Francesco Schettino, his eyes shaded by sunglasses and slipping into a back door, made no comment to reporters as he arrived for his trial Tuesday on charges of multiple manslaughter, abandoning ship and causing the shipwreck near the island of Giglio.</p> <p>His lawyer, Domenico Pepe, told reporters that, as expected, the judge was postponing the hearing due to an eight-day nationwide lawyers' strike.</p> <p>Pepe said some 1,000 witnesses are expected to eventually testify. Many of them are expected to be from among the 4,200 passengers and crew aboard the ship that struck a jagged reef off Giglio, took on water and capsized. Schettino has denied wrongdoing.</p>"
}
]
}
{
"uri" : "http://ninjs.example.com/newsitems/20130709simp123",
"type" : "text",
"versioncreated" : "2013-07-09T10:37:00Z",
"by" : "Paulo Santalucia and Frances d'Emilio",
"headlines" : [
{
"role": "main",
"value": "Captain of wrecked cruise ship on trial in Italy"
}
],
"bodies" : [
{
"role": "main",
"contenttype": "text/plain",
"value": "GROSSETO, Italy (AP) -- The trial of the captain of the shipwrecked Costa Concordia cruise liner has begun in a theater converted into a courtroom in Tuscany to accommodate all the survivors and relatives of the 32 victims who want to see justice carried out in the 2012 tragedy. The sole defendant, Francesco Schettino, his eyes shaded by sunglasses and slipping into a back door, made no comment to reporters as he arrived for his trial Tuesday on charges of multiple manslaughter, abandoning ship and causing the shipwreck near the island of Giglio. His lawyer, Domenico Pepe, told reporters that, as expected, the judge was postponing the hearing due to an eight-day nationwide lawyers' strike. Pepe said some 1,000 witnesses are expected to eventually testify. Many of them are expected to be from among the 4,200 passengers and crew aboard the ship that struck a jagged reef off Giglio, took on water and capsized. Schettino has denied wrongdoing."
},
{
"role": "richtext",
"contenttype": "body_xhtml",
"value": "<p>GROSSETO, Italy (AP) -- The trial of the captain of the shipwrecked Costa Concordia cruise liner has begun in a theater converted into a courtroom in Tuscany to accommodate all the survivors and relatives of the 32 victims who want to see justice carried out in the 2012 tragedy.</p> <p>The sole defendant, Francesco Schettino, his eyes shaded by sunglasses and slipping into a back door, made no comment to reporters as he arrived for his trial Tuesday on charges of multiple manslaughter, abandoning ship and causing the shipwreck near the island of Giglio.</p> <p>His lawyer, Domenico Pepe, told reporters that, as expected, the judge was postponing the hearing due to an eight-day nationwide lawyers' strike.</p> <p>Pepe said some 1,000 witnesses are expected to eventually testify. Many of them are expected to be from among the 4,200 passengers and crew aboard the ship that struck a jagged reef off Giglio, took on water and capsized. Schettino has denied wrongdoing.</p>"
}
]
}
{
"uri" : "http://ninjs.example.com/newsitems/20130709simp123",
"type" : "text",
"versioncreated" : "2013-07-09T10:37:00Z",
"byline" : "Paulo Santalucia and Frances d'Emilio",
"headline_main": "Captain of wrecked cruise ship on trial in Italy",
"body_main" : "GROSSETO, Italy (AP) -- The trial of the captain of the shipwrecked Costa Concordia cruise liner has begun in a theater converted into a courtroom in Tuscany to accommodate all the survivors and relatives of the 32 victims who want to see justice carried out in the 2012 tragedy. The sole defendant, Francesco Schettino, his eyes shaded by sunglasses and slipping into a back door, made no comment to reporters as he arrived for his trial Tuesday on charges of multiple manslaughter, abandoning ship and causing the shipwreck near the island of Giglio. His lawyer, Domenico Pepe, told reporters that, as expected, the judge was postponing the hearing due to an eight-day nationwide lawyers' strike. Pepe said some 1,000 witnesses are expected to eventually testify. Many of them are expected to be from among the 4,200 passengers and crew aboard the ship that struck a jagged reef off Giglio, took on water and capsized. Schettino has denied wrongdoing.",
"body_richtext": "<p>GROSSETO, Italy (AP) -- The trial of the captain of the shipwrecked Costa Concordia cruise liner has begun in a theater converted into a courtroom in Tuscany to accommodate all the survivors and relatives of the 32 victims who want to see justice carried out in the 2012 tragedy.</p> <p>The sole defendant, Francesco Schettino, his eyes shaded by sunglasses and slipping into a back door, made no comment to reporters as he arrived for his trial Tuesday on charges of multiple manslaughter, abandoning ship and causing the shipwreck near the island of Giglio.</p> <p>His lawyer, Domenico Pepe, told reporters that, as expected, the judge was postponing the hearing due to an eight-day nationwide lawyers' strike.</p> <p>Pepe said some 1,000 witnesses are expected to eventually testify. Many of them are expected to be from among the 4,200 passengers and crew aboard the ship that struck a jagged reef off Giglio, took on water and capsized. Schettino has denied wrongdoing.</p>"
}
5.1.2. A more complex example
-
Metadata about the content are added to the example above.
-
person
,place
andorganisation
employ a structure which provides human readable names for the entity but also machine readable identifiers by thescheme
andcode
properties.
-
ninjs 3.0
-
ninjs 2.1
-
ninjs 1.5
{
"uri" : "http://ninjs.example.com/newsitems/20130709med123",
"type" : "text",
"profile" : "text-only",
"versionCreated" : "2013-07-09T10:37:00Z",
"copyrightNotice" : "Copyright 2013 The News Agency, www.tna.org - all rights reserved.",
"language" : "en",
"people" : [
{
"name" : "Francesco Schettino",
"rel" : "about",
"uri" : "http://www.wikidata.org/entity/Q4421821"
}
],
"places" : [
{
"name" : "Grossetto",
"rel" : "mentions"
},
{
"name" : "Tuscany",
"rel" : "mentions"
},
{
"name" : "Italy",
"rel" : "mentions",
"uri" : "http://cvx.iptc.org/iso3166-1a2/it"
}
],
"organisations" : [
{
"name" : "Costa Crociere SpA",
"rel" : "mentions"
}
],
"by" : "Paulo Santalucia and Frances d'Emilio",
"located" : "Grossetto, Italy",
"headlines" : [
{
"role": "main",
"value": "Captain of wrecked cruise ship on trial in Italy"
}
],
"bodies": [
{
"role": "main",
"contentType": "text/plain",
"value" : "GROSSETO, Italy (AP) -- The trial of the captain of the shipwrecked Costa Concordia cruise liner has begun in a theater converted into a courtroom in Tuscany to accommodate all the survivors and relatives of the 32 victims who want to see justice carried out in the 2012 tragedy. The sole defendant, Francesco Schettino, his eyes shaded by sunglasses and slipping into a back door, made no comment to reporters as he arrived for his trial Tuesday on charges of multiple manslaughter, abandoning ship and causing the shipwreck near the island of Giglio. His lawyer, Domenico Pepe, told reporters that, as expected, the judge was postponing the hearing due to an eight-day nationwide lawyers' strike. Pepe said some 1,000 witnesses are expected to eventually testify. Many of them are expected to be from among the 4,200 passengers and crew aboard the ship that struck a jagged reef off Giglio, took on water and capsized. Schettino has denied wrongdoing."
},
{
"role": "richtext",
"contentType": "application/xhtml+xml",
"value": "<p>GROSSETO, Italy (AP) -- The trial of the captain of the shipwrecked Costa Concordia cruise liner has begun in a theater converted into a courtroom in Tuscany to accommodate all the survivors and relatives of the 32 victims who want to see justice carried out in the 2012 tragedy.</p> <p>The sole defendant, Francesco Schettino, his eyes shaded by sunglasses and slipping into a back door, made no comment to reporters as he arrived for his trial Tuesday on charges of multiple manslaughter, abandoning ship and causing the shipwreck near the island of Giglio.</p> <p>His lawyer, Domenico Pepe, told reporters that, as expected, the judge was postponing the hearing due to an eight-day nationwide lawyers' strike.</p> <p>Pepe said some 1,000 witnesses are expected to eventually testify. Many of them are expected to be from among the 4,200 passengers and crew aboard the ship that struck a jagged reef off Giglio, took on water and capsized. Schettino has denied wrongdoing.</p>"
}
]
}
{
"uri" : "http://ninjs.example.com/newsitems/20130709med123",
"type" : "text",
"profile" : "text-only",
"versioncreated" : "2013-07-09T10:37:00Z",
"copyrightnotice" : "Copyright 2013 The News Agency, www.tna.org - all rights reserved.",
"language" : "en",
"people" : [
{
"name" : "Francesco Schettino",
"rel" : "about",
"uri" : "http://www.wikidata.org/entity/Q4421821"
}
],
"places" : [
{
"name" : "Grossetto",
"rel" : "mentions"
},
{
"name" : "Tuscany",
"rel" : "mentions"
},
{
"name" : "Italy",
"rel" : "mentions",
"uri" : "http://cvx.iptc.org/iso3166-1a2/it"
}
],
"organisations" : [
{
"name" : "Costa Crociere SpA",
"rel" : "mentions"
}
],
"by" : "Paulo Santalucia and Frances d'Emilio",
"located" : "Grossetto, Italy",
"headlines" : [
{
"role": "main",
"value": "Captain of wrecked cruise ship on trial in Italy"
}
],
"bodies": [
{
"role": "main",
"contenttype": "text/plain",
"value" : "GROSSETO, Italy (AP) -- The trial of the captain of the shipwrecked Costa Concordia cruise liner has begun in a theater converted into a courtroom in Tuscany to accommodate all the survivors and relatives of the 32 victims who want to see justice carried out in the 2012 tragedy. The sole defendant, Francesco Schettino, his eyes shaded by sunglasses and slipping into a back door, made no comment to reporters as he arrived for his trial Tuesday on charges of multiple manslaughter, abandoning ship and causing the shipwreck near the island of Giglio. His lawyer, Domenico Pepe, told reporters that, as expected, the judge was postponing the hearing due to an eight-day nationwide lawyers' strike. Pepe said some 1,000 witnesses are expected to eventually testify. Many of them are expected to be from among the 4,200 passengers and crew aboard the ship that struck a jagged reef off Giglio, took on water and capsized. Schettino has denied wrongdoing."
},
{
"role": "richtext",
"contenttype": "application/xhtml+xml",
"value": "<p>GROSSETO, Italy (AP) -- The trial of the captain of the shipwrecked Costa Concordia cruise liner has begun in a theater converted into a courtroom in Tuscany to accommodate all the survivors and relatives of the 32 victims who want to see justice carried out in the 2012 tragedy.</p> <p>The sole defendant, Francesco Schettino, his eyes shaded by sunglasses and slipping into a back door, made no comment to reporters as he arrived for his trial Tuesday on charges of multiple manslaughter, abandoning ship and causing the shipwreck near the island of Giglio.</p> <p>His lawyer, Domenico Pepe, told reporters that, as expected, the judge was postponing the hearing due to an eight-day nationwide lawyers' strike.</p> <p>Pepe said some 1,000 witnesses are expected to eventually testify. Many of them are expected to be from among the 4,200 passengers and crew aboard the ship that struck a jagged reef off Giglio, took on water and capsized. Schettino has denied wrongdoing.</p>"
}
]
}
{
"uri" : "http://ninjs.example.com/newsitems/20130709med123",
"type" : "text",
"profile" : "text-only",
"versioncreated" : "2013-07-09T10:37:00Z",
"copyrightnotice" : "Copyright 2013 The News Agency, www.tna.org - all rights reserved.",
"language" : "en",
"person" : [
{
"name" : "Francesco Schettino",
"rel" : "about",
"code" : "http://www.wikidata.org/entity/Q4421821"
}
],
"place" : [
{
"name" : "Grossetto",
"rel" : "mentions"
},
{
"name" : "Tuscany",
"rel" : "mentions"
},
{
"name" : "Italy",
"rel" : "mentions",
"scheme" : "http://cvx.iptc.org/iso3166-1a2/",
"code" : "it"
}
],
"organisation" : [
{
"name" : "Costa Crociere SpA",
"rel" : "mentions"
}
],
"byline" : "Paulo Santalucia and Frances d'Emilio",
"located" : "Grossetto, Italy",
"headline_main" : "Captain of wrecked cruise ship on trial in Italy",
"body_main": "GROSSETO, Italy (AP) -- The trial of the captain of the shipwrecked Costa Concordia cruise liner has begun in a theater converted into a courtroom in Tuscany to accommodate all the survivors and relatives of the 32 victims who want to see justice carried out in the 2012 tragedy. The sole defendant, Francesco Schettino, his eyes shaded by sunglasses and slipping into a back door, made no comment to reporters as he arrived for his trial Tuesday on charges of multiple manslaughter, abandoning ship and causing the shipwreck near the island of Giglio. His lawyer, Domenico Pepe, told reporters that, as expected, the judge was postponing the hearing due to an eight-day nationwide lawyers' strike. Pepe said some 1,000 witnesses are expected to eventually testify. Many of them are expected to be from among the 4,200 passengers and crew aboard the ship that struck a jagged reef off Giglio, took on water and capsized. Schettino has denied wrongdoing.",
"body_richtext": "<p>GROSSETO, Italy (AP) -- The trial of the captain of the shipwrecked Costa Concordia cruise liner has begun in a theater converted into a courtroom in Tuscany to accommodate all the survivors and relatives of the 32 victims who want to see justice carried out in the 2012 tragedy.</p> <p>The sole defendant, Francesco Schettino, his eyes shaded by sunglasses and slipping into a back door, made no comment to reporters as he arrived for his trial Tuesday on charges of multiple manslaughter, abandoning ship and causing the shipwreck near the island of Giglio.</p> <p>His lawyer, Domenico Pepe, told reporters that, as expected, the judge was postponing the hearing due to an eight-day nationwide lawyers' strike.</p> <p>Pepe said some 1,000 witnesses are expected to eventually testify. Many of them are expected to be from among the 4,200 passengers and crew aboard the ship that struck a jagged reef off Giglio, took on water and capsized. Schettino has denied wrongdoing.</p>"
}
5.1.3. More Examples on GitHub
You can find more examples of ninjs representations of text-based news releases in the ninjs GitHub repository.
5.2. Photo-only example
A simple photo-only example.
Key features:
-
A "uri" must be present
-
"type" indicates that the generic content type is 'a picture'
-
"by", "headlines", "descriptions" (in plain text and HTML format) are typical photo metadata
-
The image itself is represented by "renditions". Two are available in this example: a main version and a small version.
-
ninjs 3.0
-
ninjs 2.1
-
ninjs 1.5
{
"uri" : "http://ninjs.example.com/newsitems/20130709simpPh123",
"type" : "picture",
"versionCreated" : "2013-07-08T08:12:00Z",
"by" : "Paulo Santalucia",
"headlines" : [
{
"role": "main",
"value": "Costa Concordia cruise ship"
}
],
"descriptions": [
{
"role": "text",
"contentType": "text/plain",
"value": "The Costa Concordia cruise ship lies on its side in the waters of the Tuscan island of Giglio, Italy, Monday, July 8, 2013. The luxury cruise ship ran aground off the coast of Tuscany on Jan 13, 2012, sending water pouring in through a 160-foot (50-meter) gash in the hull and forcing the evacuation of some 4,200 people from the listing vessel early."
},
{
"role": "richtext",
"contentType": "description_xhtml",
"value": "<p>The Costa Concordia cruise ship lies on its side in the waters of the Tuscan island of Giglio, Italy,<br /> Monday, July 8, 2013. The luxury cruise ship ran aground off the coast of Tuscany on Jan 13, 2012, sending water pouring in through a 160-foot (50-meter) gash in the hull and forcing the evacuation of some 4,200 people from the listing vessel early.</p>"
}
],
"renditions" : [
{
"name": "main",
"href" : "http://hosted.ap.org/photos/2/2643c588-dc8d-4923-bebd-e3b904edbb3a-big.jpg",
"contentType": "image/jpg",
"title" : "Mid Resolution",
"height" : 281,
"width" : 429
},
{
"name": "small",
"href" : "http://hosted.ap.org/photos/2/2643c588-dc8d-4923-bebd-e3b904edbb3a-small.jpg",
"contentType": "image/jpg",
"title" : "Low Resolution",
"height" : 117,
"width" : 179
}
]
}
{
"uri" : "http://ninjs.example.com/newsitems/20130709simpPh123",
"type" : "picture",
"versioncreated" : "2013-07-08T08:12:00Z",
"by" : "Paulo Santalucia",
"headlines" : [
{
"role": "main",
"value": "Costa Concordia cruise ship"
}
],
"descriptions": [
{
"role": "text",
"contenttype": "text/plain",
"value": "The Costa Concordia cruise ship lies on its side in the waters of the Tuscan island of Giglio, Italy, Monday, July 8, 2013. The luxury cruise ship ran aground off the coast of Tuscany on Jan 13, 2012, sending water pouring in through a 160-foot (50-meter) gash in the hull and forcing the evacuation of some 4,200 people from the listing vessel early."
},
{
"role": "richtext",
"contenttype": "description_xhtml",
"value": "<p>The Costa Concordia cruise ship lies on its side in the waters of the Tuscan island of Giglio, Italy,<br /> Monday, July 8, 2013. The luxury cruise ship ran aground off the coast of Tuscany on Jan 13, 2012, sending water pouring in through a 160-foot (50-meter) gash in the hull and forcing the evacuation of some 4,200 people from the listing vessel early.</p>"
}
],
"renditions" : [
{
"name": "main",
"href" : "http://hosted.ap.org/photos/2/2643c588-dc8d-4923-bebd-e3b904edbb3a-big.jpg",
"contenttype": "image/jpg",
"title" : "Mid Resolution",
"height" : 281,
"width" : 429
},
{
"name": "small",
"href" : "http://hosted.ap.org/photos/2/2643c588-dc8d-4923-bebd-e3b904edbb3a-small.jpg",
"contenttype": "image/jpg",
"title" : "Low Resolution",
"height" : 117,
"width" : 179
}
]
}
{
"uri" : "http://ninjs.example.com/newsitems/20130709simpPh123",
"type" : "picture",
"versioncreated" : "2013-07-08T08:12:00Z",
"byline" : "Paulo Santalucia",
"headline_main" : "Costa Concordia cruise ship",
"description_text": "The Costa Concordia cruise ship lies on its side in the waters of the Tuscan island of Giglio, Italy, Monday, July 8, 2013. The luxury cruise ship ran aground off the coast of Tuscany on Jan 13, 2012, sending water pouring in through a 160-foot (50-meter) gash in the hull and forcing the evacuation of some 4,200 people from the listing vessel early.",
"description_richtext": "<p>The Costa Concordia cruise ship lies on its side in the waters of the Tuscan island of Giglio, Italy,<br /> Monday, July 8, 2013. The luxury cruise ship ran aground off the coast of Tuscany on Jan 13, 2012, sending water pouring in through a 160-foot (50-meter) gash in the hull and forcing the evacuation of some 4,200 people from the listing vessel early.</p>",
"renditions" : {
"main": {
"href" : "http://hosted.ap.org/photos/2/2643c588-dc8d-4923-bebd-e3b904edbb3a-big.jpg",
"mimetype": "image/jpg",
"title" : "Mid Resolution",
"height" : 281,
"width" : 429
},
"small": {
"href" : "http://hosted.ap.org/photos/2/2643c588-dc8d-4923-bebd-e3b904edbb3a-small.jpg",
"mimetype": "image/jpg",
"title" : "Low Resolution",
"height" : 117,
"width" : 179
}
}
}
5.3. Multimedia example
Example for multimedia content.
The ninjs object includes:
-
text news as main object
-
a main picture illustrating the text news (in ninjs terms: associated with the text news)
-
a portrait of a person the text news is about (also: associated)
-
ninjs 3.0
-
ninjs 2.1
-
ninjs 1.5
{
"uri" : "http://ninjs.example.com/newsitems/20130709cplx456",
"type" : "composite",
"profile" : "text-photo",
"versionCreated" : "2013-07-09T10:39:00Z",
"copyrightNotice" : "Copyright 2013 The News Agency, www.tnag.org - all rights reserved.",
"language" : "en",
"people" : [
{
"name" : "Francesco Schettino",
"rel" : "about",
"uri" : "http://www.wikidata.org/entity/Q4421821"
}
],
"places" : [
{
"name" : "Grossetto",
"rel" : "mentions"
},
{
"name" : "Tuscany",
"rel" : "mentions"
},
{
"name" : "Italy",
"rel" : "mentions",
"uri" : "http://cvx.iptc.org/iso3166-1a2/it"
}
],
"organisations" : [
{
"name" : "Costa Crociere SpA",
"rel" : "mentions"
}
],
"by" : "Paulo Santalucia and Frances d'Emilio",
"located" : "Grossetto, Italy",
"headlines" : [
{
"value": "Captain of wrecked cruise ship on trial in Italy"
}
],
"bodies": [
{
"role": "text",
"contentType": "text/plain",
"value": "GROSSETO, Italy (AP) -- The trial of the captain of the shipwrecked Costa Concordia cruise liner has begun in a theater converted into a courtroom in Tuscany to accommodate all the survivors and relatives of the 32 victims who want to see justice carried out in the 2012 tragedy. The sole defendant, Francesco Schettino, his eyes shaded by sunglasses and slipping into a back door, made no comment to reporters as he arrived for his trial Tuesday on charges of multiple manslaughter, abandoning ship and causing the shipwreck near the island of Giglio. His lawyer, Domenico Pepe, told reporters that, as expected, the judge was postponing the hearing due to an eight-day nationwide lawyers' strike. Pepe said some 1,000 witnesses are expected to eventually testify. Many of them are expected to be from among the 4,200 passengers and crew aboard the ship that struck a jagged reef off Giglio, took on water and capsized. Schettino has denied wrongdoing."
},
{
"role": "text",
"contentType" : "application/xhtml+xml",
"value": "<p>GROSSETO, Italy (AP) -- The trial of the captain of the shipwrecked Costa Concordia cruise liner has begun in a theater converted into a courtroom in Tuscany to accommodate all the survivors and relatives of the 32 victims who want to see justice carried out in the 2012 tragedy.</p> <p>The sole defendant, Francesco Schettino, his eyes shaded by sunglasses and slipping into a back door, made no comment to reporters as he arrived for his trial Tuesday on charges of multiple manslaughter, abandoning ship and causing the shipwreck near the island of Giglio.</p> <p>His lawyer, Domenico Pepe, told reporters that, as expected, the judge was postponing the hearing due to an eight-day nationwide lawyers' strike.</p> <p>Pepe said some 1,000 witnesses are expected to eventually testify. Many of them are expected to be from among the 4,200 passengers and crew aboard the ship that struck a jagged reef off Giglio, took on water and capsized. Schettino has denied wrongdoing.</p>"
}
],
"associations" : [
{
"name": "mainpic",
"uri" : "http://ninjs.example.com/newsitems/20130709simpPh123",
"type" : "picture",
"versionCreated" : "2013-07-08T08:12:00Z",
"copyrightNotice" : "Copyright 2013 The News Agency, www.tna.org - all rights reserved.",
"objects" : [
{
"name" : "Costa Concordia",
"rel" : "about",
"uri" : "http://www.wikidata.org/entity/Q190542"
}
],
"places" : [
{
"name" : "Giglio",
"rel" : "mentions"
},
{
"name" : "Tuscany",
"rel" : "mentions"
},
{
"name" : "Italy",
"rel" : "mentions",
"uri" : "http://cvx.iptc.org/iso3166-1a2/it"
}
],
"organisations" : [
{
"name" : "Costa Crociere SpA",
"rel" : "mentions"
}
],
"by" : "Paulo Santalucia",
"headlines" : [
{
"value": "Costa Concordia cruise ship"
}
],
"descriptions": [
{
"role": "text",
"contentType": "text/plain",
"value": "The Costa Concordia cruise ship lies on its side in the waters of the Tuscan island of Giglio, Italy, Monday, July 8, 2013. The luxury cruise ship ran aground off the coast of Tuscany on Jan 13, 2012, sending water pouring in through a 160-foot (50-meter) gash in the hull and forcing the evacuation of some 4,200 people from the listing vessel early."
},
{
"role": "richtext",
"contentType": "application/xhtml+xml",
"value": "<p>The Costa Concordia cruise ship lies on its side in the waters of the Tuscan island of Giglio, Italy,</ br> Monday, July 8, 2013. The luxury cruise ship ran aground off the coast of Tuscany on Jan 13, 2012, sending water pouring in through a 160-foot (50-meter) gash in the hull and forcing the evacuation of some 4,200 people from the listing vessel early. </p>"
}
],
"renditions" : [
{
"name": "main",
"href" : "http://hosted.ap.org/photos/2/2643c588-dc8d-4923-bebd-e3b904edbb3a-big.jpg",
"contentType": "image/jpg",
"title" : "Mid Resolution",
"height" : 281,
"width" : 429
},
{
"name": "small",
"href" : "http://hosted.ap.org/photos/2/2643c588-dc8d-4923-bebd-e3b904edbb3a-small.jpg",
"contentType": "image/jpg",
"title" : "Low Resolution",
"height" : 117,
"width" : 179
}
]
},
{
"name": "portrait",
"uri" : "http://ninjs.example.com/newsitems/20130709simpPh456",
"type" : "picture",
"versionCreated" : "2013-07-09T10:12:00Z",
"copyrightNotice" : "Copyright 2013 The News Agency, www.tna.org - all rights reserved.",
"people" : [
{
"name" : "Francesco Schettino",
"rel" : "about",
"uri" : "http://www.wikidata.org/entity/Q4421821"
}
],
"places" : [
{
"name" : "Grossetto",
"rel" : "mentions"
},
{
"name" : "Tuscany",
"rel" : "mentions"
},
{
"name" : "Italy",
"rel" : "mentions",
"uri" : "http://cvx.iptc.org/iso3166-1a2/it"
}
],
"organisations" : [
{
"name" : "Costa Crociere SpA",
"rel" : "mentions"
}
],
"by" : "Paulo Santalucia",
"headlines" : [
{
"value": "Francesco Schettino at court"
}
],
"descriptions": [
{
"value": "Francesco Schettino the captain of the Costa Concordia cruise ship at court in Grossetto, Italy, on 9 July 2013"
}
],
"renditions" : [
{
"name": "main",
"href" : "http://hosted.ap.org/photos/2/2643c588-dc8d-4923-bebd-e3b904xyz000-big.jpg",
"contentType": "image/jpg",
"title" : "Mid Resolution",
"height" : 430,
"width" : 280
},
{
"name": "small",
"href" : "http://hosted.ap.org/photos/2/2643c588-dc8d-4923-bebd-e3b904xyz000-small.jpg",
"contentType": "image/jpg",
"title" : "Low Resolution",
"height" : 180,
"width" : 120
}
]
}
]
}
{
"uri" : "http://ninjs.example.com/newsitems/20130709cplx456",
"type" : "composite",
"profile" : "text-photo",
"versioncreated" : "2013-07-09T10:39:00Z",
"copyrightnotice" : "Copyright 2013 The News Agency, www.tnag.org - all rights reserved.",
"language" : "en",
"people" : [
{
"name" : "Francesco Schettino",
"rel" : "about",
"uri" : "http://www.wikidata.org/entity/Q4421821"
}
],
"places" : [
{
"name" : "Grossetto",
"rel" : "mentions"
},
{
"name" : "Tuscany",
"rel" : "mentions"
},
{
"name" : "Italy",
"rel" : "mentions",
"uri" : "http://cvx.iptc.org/iso3166-1a2/it"
}
],
"organisations" : [
{
"name" : "Costa Crociere SpA",
"rel" : "mentions"
}
],
"by" : "Paulo Santalucia and Frances d'Emilio",
"located" : "Grossetto, Italy",
"headlines" : [
{
"value": "Captain of wrecked cruise ship on trial in Italy"
}
],
"bodies": [
{
"role": "text",
"contenttype": "text/plain",
"value": "GROSSETO, Italy (AP) -- The trial of the captain of the shipwrecked Costa Concordia cruise liner has begun in a theater converted into a courtroom in Tuscany to accommodate all the survivors and relatives of the 32 victims who want to see justice carried out in the 2012 tragedy. The sole defendant, Francesco Schettino, his eyes shaded by sunglasses and slipping into a back door, made no comment to reporters as he arrived for his trial Tuesday on charges of multiple manslaughter, abandoning ship and causing the shipwreck near the island of Giglio. His lawyer, Domenico Pepe, told reporters that, as expected, the judge was postponing the hearing due to an eight-day nationwide lawyers' strike. Pepe said some 1,000 witnesses are expected to eventually testify. Many of them are expected to be from among the 4,200 passengers and crew aboard the ship that struck a jagged reef off Giglio, took on water and capsized. Schettino has denied wrongdoing."
},
{
"role": "text",
"contenttype" : "application/xhtml+xml",
"value": "<p>GROSSETO, Italy (AP) -- The trial of the captain of the shipwrecked Costa Concordia cruise liner has begun in a theater converted into a courtroom in Tuscany to accommodate all the survivors and relatives of the 32 victims who want to see justice carried out in the 2012 tragedy.</p> <p>The sole defendant, Francesco Schettino, his eyes shaded by sunglasses and slipping into a back door, made no comment to reporters as he arrived for his trial Tuesday on charges of multiple manslaughter, abandoning ship and causing the shipwreck near the island of Giglio.</p> <p>His lawyer, Domenico Pepe, told reporters that, as expected, the judge was postponing the hearing due to an eight-day nationwide lawyers' strike.</p> <p>Pepe said some 1,000 witnesses are expected to eventually testify. Many of them are expected to be from among the 4,200 passengers and crew aboard the ship that struck a jagged reef off Giglio, took on water and capsized. Schettino has denied wrongdoing.</p>"
}
],
"associations" : [
{
"name": "mainpic",
"uri" : "http://ninjs.example.com/newsitems/20130709simpPh123",
"type" : "picture",
"versioncreated" : "2013-07-08T08:12:00Z",
"copyrightnotice" : "Copyright 2013 The News Agency, www.tna.org - all rights reserved.",
"objects" : [
{
"name" : "Costa Concordia",
"rel" : "about",
"uri" : "http://www.wikidata.org/entity/Q190542"
}
],
"places" : [
{
"name" : "Giglio",
"rel" : "mentions"
},
{
"name" : "Tuscany",
"rel" : "mentions"
},
{
"name" : "Italy",
"rel" : "mentions",
"uri" : "http://cvx.iptc.org/iso3166-1a2/it"
}
],
"organisations" : [
{
"name" : "Costa Crociere SpA",
"rel" : "mentions"
}
],
"by" : "Paulo Santalucia",
"headlines" : [
{
"value": "Costa Concordia cruise ship"
}
],
"descriptions": [
{
"role": "text",
"contenttype": "text/plain",
"value": "The Costa Concordia cruise ship lies on its side in the waters of the Tuscan island of Giglio, Italy, Monday, July 8, 2013. The luxury cruise ship ran aground off the coast of Tuscany on Jan 13, 2012, sending water pouring in through a 160-foot (50-meter) gash in the hull and forcing the evacuation of some 4,200 people from the listing vessel early."
},
{
"role": "richtext",
"contenttype": "application/xhtml+xml",
"value": "<p>The Costa Concordia cruise ship lies on its side in the waters of the Tuscan island of Giglio, Italy,</ br> Monday, July 8, 2013. The luxury cruise ship ran aground off the coast of Tuscany on Jan 13, 2012, sending water pouring in through a 160-foot (50-meter) gash in the hull and forcing the evacuation of some 4,200 people from the listing vessel early. </p>"
}
],
"renditions" : [
{
"name": "main",
"href" : "http://hosted.ap.org/photos/2/2643c588-dc8d-4923-bebd-e3b904edbb3a-big.jpg",
"contenttype": "image/jpg",
"title" : "Mid Resolution",
"height" : 281,
"width" : 429
},
{
"name": "small",
"href" : "http://hosted.ap.org/photos/2/2643c588-dc8d-4923-bebd-e3b904edbb3a-small.jpg",
"contenttype": "image/jpg",
"title" : "Low Resolution",
"height" : 117,
"width" : 179
}
]
},
{
"name": "portrait",
"uri" : "http://ninjs.example.com/newsitems/20130709simpPh456",
"type" : "picture",
"versioncreated" : "2013-07-09T10:12:00Z",
"copyrightnotice" : "Copyright 2013 The News Agency, www.tna.org - all rights reserved.",
"people" : [
{
"name" : "Francesco Schettino",
"rel" : "about",
"uri" : "http://www.wikidata.org/entity/Q4421821"
}
],
"places" : [
{
"name" : "Grossetto",
"rel" : "mentions"
},
{
"name" : "Tuscany",
"rel" : "mentions"
},
{
"name" : "Italy",
"rel" : "mentions",
"uri" : "http://cvx.iptc.org/iso3166-1a2/it"
}
],
"organisations" : [
{
"name" : "Costa Crociere SpA",
"rel" : "mentions"
}
],
"by" : "Paulo Santalucia",
"headlines" : [
{
"value": "Francesco Schettino at court"
}
],
"descriptions": [
{
"value": "Francesco Schettino the captain of the Costa Concordia cruise ship at court in Grossetto, Italy, on 9 July 2013"
}
],
"renditions" : [
{
"name": "main",
"href" : "http://hosted.ap.org/photos/2/2643c588-dc8d-4923-bebd-e3b904xyz000-big.jpg",
"contenttype": "image/jpg",
"title" : "Mid Resolution",
"height" : 430,
"width" : 280
},
{
"name": "small",
"href" : "http://hosted.ap.org/photos/2/2643c588-dc8d-4923-bebd-e3b904xyz000-small.jpg",
"contenttype": "image/jpg",
"title" : "Low Resolution",
"height" : 180,
"width" : 120
}
]
}
]
}
{
"uri" : "http://ninjs.example.com/newsitems/20130709cplx456",
"type" : "composite",
"profile" : "text-photo",
"versioncreated" : "2013-07-09T10:39:00Z",
"copyrightnotice" : "Copyright 2013 The News Agency, www.tnag.org - all rights reserved.",
"language" : "en",
"person" : [
{
"name" : "Francesco Schettino",
"rel" : "about",
"code" : "http://www.wikidata.org/entity/Q4421821"
}
],
"place" : [
{
"name" : "Grossetto",
"rel" : "mentions"
},
{
"name" : "Tuscany",
"rel" : "mentions"
},
{
"name" : "Italy",
"rel" : "mentions",
"scheme" : "http://cvx.iptc.org/iso3166-1a2/",
"code" : "it"
}
],
"organisation" : [
{
"name" : "Costa Crociere SpA",
"rel" : "mentions"
}
],
"byline" : "Paulo Santalucia and Frances d'Emilio",
"located" : "Grossetto, Italy",
"headline": "Captain of wrecked cruise ship on trial in Italy",
"body_text": "GROSSETO, Italy (AP) -- The trial of the captain of the shipwrecked Costa Concordia cruise liner has begun in a theater converted into a courtroom in Tuscany to accommodate all the survivors and relatives of the 32 victims who want to see justice carried out in the 2012 tragedy. The sole defendant, Francesco Schettino, his eyes shaded by sunglasses and slipping into a back door, made no comment to reporters as he arrived for his trial Tuesday on charges of multiple manslaughter, abandoning ship and causing the shipwreck near the island of Giglio. His lawyer, Domenico Pepe, told reporters that, as expected, the judge was postponing the hearing due to an eight-day nationwide lawyers' strike. Pepe said some 1,000 witnesses are expected to eventually testify. Many of them are expected to be from among the 4,200 passengers and crew aboard the ship that struck a jagged reef off Giglio, took on water and capsized. Schettino has denied wrongdoing.",
"body_richtext": "<p>GROSSETO, Italy (AP) -- The trial of the captain of the shipwrecked Costa Concordia cruise liner has begun in a theater converted into a courtroom in Tuscany to accommodate all the survivors and relatives of the 32 victims who want to see justice carried out in the 2012 tragedy.</p> <p>The sole defendant, Francesco Schettino, his eyes shaded by sunglasses and slipping into a back door, made no comment to reporters as he arrived for his trial Tuesday on charges of multiple manslaughter, abandoning ship and causing the shipwreck near the island of Giglio.</p> <p>His lawyer, Domenico Pepe, told reporters that, as expected, the judge was postponing the hearing due to an eight-day nationwide lawyers' strike.</p> <p>Pepe said some 1,000 witnesses are expected to eventually testify. Many of them are expected to be from among the 4,200 passengers and crew aboard the ship that struck a jagged reef off Giglio, took on water and capsized. Schettino has denied wrongdoing.</p>",
"associations" : {
"mainpic": {
"uri" : "http://ninjs.example.com/newsitems/20130709simpPh123",
"type" : "picture",
"versioncreated" : "2013-07-08T08:12:00Z",
"copyrightnotice" : "Copyright 2013 The News Agency, www.tna.org - all rights reserved.",
"object" : [
{
"name" : "Costa Concordia",
"rel" : "about",
"code" : "http://www.wikidata.org/entity/Q190542"
}
],
"place" : [
{
"name" : "Giglio",
"rel" : "mentions"
},
{
"name" : "Tuscany",
"rel" : "mentions"
},
{
"name" : "Italy",
"rel" : "mentions",
"scheme" : "http://cvx.iptc.org/iso3166-1a2/",
"code" : "it"
}
],
"organisation" : [
{
"name" : "Costa Crociere SpA",
"rel" : "mentions"
}
],
"byline" : "Paulo Santalucia",
"headline": "Costa Concordia cruise ship",
"description_text": "The Costa Concordia cruise ship lies on its side in the waters of the Tuscan island of Giglio, Italy, Monday, July 8, 2013. The luxury cruise ship ran aground off the coast of Tuscany on Jan 13, 2012, sending water pouring in through a 160-foot (50-meter) gash in the hull and forcing the evacuation of some 4,200 people from the listing vessel early.",
"description_richtext": "<p>The Costa Concordia cruise ship lies on its side in the waters of the Tuscan island of Giglio, Italy,</ br> Monday, July 8, 2013. The luxury cruise ship ran aground off the coast of Tuscany on Jan 13, 2012, sending water pouring in through a 160-foot (50-meter) gash in the hull and forcing the evacuation of some 4,200 people from the listing vessel early. </p>",
"renditions" : {
"main": {
"href" : "http://hosted.ap.org/photos/2/2643c588-dc8d-4923-bebd-e3b904edbb3a-big.jpg",
"mimetype": "image/jpg",
"title" : "Mid Resolution",
"height" : 281,
"width" : 429
},
"small": {
"href" : "http://hosted.ap.org/photos/2/2643c588-dc8d-4923-bebd-e3b904edbb3a-small.jpg",
"mimetype": "image/jpg",
"title" : "Low Resolution",
"height" : 117,
"width" : 179
}
}
},
"portrait": {
"uri" : "http://ninjs.example.com/newsitems/20130709simpPh456",
"type" : "picture",
"versioncreated" : "2013-07-09T10:12:00Z",
"copyrightnotice" : "Copyright 2013 The News Agency, www.tna.org - all rights reserved.",
"person" : [
{
"name" : "Francesco Schettino",
"rel" : "about",
"code" : "http://www.wikidata.org/entity/Q4421821"
}
],
"place" : [
{
"name" : "Grossetto",
"rel" : "mentions"
},
{
"name" : "Tuscany",
"rel" : "mentions"
},
{
"name" : "Italy",
"rel" : "mentions",
"scheme" : "http://cvx.iptc.org/iso3166-1a2/",
"code" : "it"
}
],
"organisation" : [
{
"name" : "Costa Crociere SpA",
"rel" : "mentions"
}
],
"byline" : "Paulo Santalucia",
"headline_main" : "Francesco Schettino at court",
"description_main": "Francesco Schettino the captain of the Costa Concordia cruise ship at court in Grossetto, Italy, on 9 July 2013",
"renditions" : {
"main": {
"href" : "http://hosted.ap.org/photos/2/2643c588-dc8d-4923-bebd-e3b904xyz000-big.jpg",
"mimetype": "image/jpg",
"title" : "Mid Resolution",
"height" : 430,
"width" : 280
},
"small": {
"href" : "http://hosted.ap.org/photos/2/2643c588-dc8d-4923-bebd-e3b904xyz000-small.jpg",
"mimetype": "image/jpg",
"title" : "Low Resolution",
"height" : 180,
"width" : 120
}
}
}
}
}
6. ninjs Best Practices and How Tos
Here we describe some best practices for working with ninjs in your own organisation.
6.1. Best Practice for identifying objects in arrays
The first generation of ninjs used patternproperties to identify and name bodies, headlines etc. With 2.0 these are now arrays of objects. If you, for example, only have one headline you only need to use the value property. If there are more than one headline you can use the role and/or contenttype properties to convey to the receivers of your items what each object is meant for and what format it has.
6.2. How to escape XML content for inclusion in JSON objects
JSON string values cannot contain characters: "
, \
, and various control characters like tabs. Therefore, we need to escape these characters in our content when marshaling data into JSON objects. We have provided an XSL stylesheet to do this using XSL.
The XSL Template at https://raw.githubusercontent.com/iptc/newsinjson/master/tools/xslt/nitf-to-json.xslt extracts the body of an NITF document (NITF samples are available from https://iptc.org/standards/nitf/using-nitf/) and creates a simple JSON object. The resulting object is not yet a valid ninjs object, however it will be valid JSON.
6.3. How to create provider-specific extensions
In some cases, your news releases may have content that does not fit into the objects that are defined in the ninjs standard. In these cases, you can (and should) copy and extend the IPTC ninjs schema.
To do this, do the following:
-
make a copy of the schema file
-
change the URL of the "id" property of IPTC’s ninjs 3.0 …
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "id" : "http://www.iptc.org/std/ninjs/ninjs-schema_3.0.json#", "type" : "object", ...
to your own ID, for example
example.com-ninjs-0.1
:{ "$schema": "https://json-schema.org/draft/2020-12/schema", "id" : "http://www.example.com/extended-ninjs-schema_0.1.json#", "type" : "object", ...
-
add your own properties to your copy of the schema. For example, to add a property explaining the reason for an embargo:
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "id" : "http://www.example.com/extended-ninjs-schema_0.1.json#", "type" : "object", ... "embargoed": { "title": "Embargoed", "description": "The date and time before which all versions of the news object are embargoed. If absent, this object is not embargoed. nar:embargoed", "type": "string", "format": "date-time" }, "embargoedReason" : { "description" : "Textual description of why article is embargoed.", "type" : "string" }, ...
-
save your new schema to a location where users of the schema can access it, which should be the same as the URL used for the "id" property. For the example above, the file should be accessible at http://www.example.com/e-ninjs-schema_0.1.json
This is an example ninjs document that includes the added property giving the reason for the embargo in an extended ninjs document:
{
"uri": "http://ninjs.example.com/newsitems/20130709simp123",
"type": "text",
"versioncreated": "2013-07-09T10:37:00Z",
"embargoed": "2013-07-09T14:00:00Z",
"embargoedreason": "The nomination is made public at this time."
}
6.3.1. Using standard
With the standard
field, providers can indicate in each JSON file exactly
which schema the file is valid against. So the above example of extending the
schema could be shown like this:
{
"uri": "http://ninjs.example.com/newsitems/20130709simp123",
"standard": {
"name": "e-ninjs-schema",
"schema" : "http://www.example.com/e-ninjs-schema_0.1.json",
"version" : "0.1"
},
"type": "text",
"versioncreated": "2013-07-09T10:37:00Z",
"embargoed": "2013-07-09T14:00:00Z",
"embargoedreason": "The nomination is made public at this time."
...
}
7. Tools for developing with ninjs
7.1. Validating a ninjs document
JSON Schema is the de-facto standard for validating JSON documents. The IPTC maintains schemas for each version of the ninjs standard. These schemas can be used to validate ninjs documents.
The latest IPTC ninjs schema is available for download at https://iptc.org/std/ninjs/ninjs-schema_2.1.json
7.2. Sample Code
Sample code demonstrating how to validate ninjs documents, along with example ninjs documents, can be found in the IPTC newsinjson github repository.
7.3. Online "ninjs generator" tool
The IPTC has created a simple form-based tool that can be used to generate sample ninjs documents. It supports ninjs versions 1.5, 2.1 and 3.0, so it is also a handy way to see the differences between each schema version.
The tool can be accessed at https://iptc.org/std/ninjs/generator/.
7.4. TypeScript type definition
Ian Young of PA Media Group has created a TypeScript type for ninjs 2 that can be used to ease development with ninjs in TypeScript. We plan to release a type for ninjs 3.0 soon.
8. Mapping between ninjs and NewsML-G2
ninjs and NewsML-G2 are not intended to be equivalent to each other, but they both adhere to the IPTC News Architecture, so they share many properties.
Here is a summary of the properties shared by ninjs and NewsML-G2:
ninjs 3.x property name | ninjs 2.x property name | NewsML-G2 equivalent |
---|---|---|
|
|
|
|
|
|
|
title` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
nar:headline with @role |
|
|
nar:contentType |
|
|
|
|
|
|
|
|
|
|
|
nar:charcount |
|
|
nar:wordcount |
|
|
nar:contentType |
|
|
|
|
|
nar:contentType |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
nar:link with @rel |
|
|
|
|
|
nar:remoteContent@ref |
|
|
nar:remoteContent@contenttype |
|
|
nar:remoteContent@height |
|
|
nar:remoteContent@width |
|
|
nar:remoteContent@format |
|
|
nar:remoteContent@duration |
|
|
9. ninjs Revision History
9.1. ninjs 1.0
Version 1.0 of the ninjs schema was approved by the IPTC Standards Committee on 23 October 2013.
9.2. ninjs 1.1
Version 1.1 of the ninjs schema was made available in March 2014.
Version 1.1 moved to JSON Schema version 4, and added the urgency
, usageterms
and geometry_*
properties.
An error in the association reference URI in the version 1.1 JSON Schema document was corrected in September 2017.
9.3. ninjs 1.2
Version 1.2 of the ninjs schema was approved by the IPTC Standards Committee and made available in October 2019.
Version 1.2 added the firstcreated
, charcount
, wordcount
, slugline
, ednote
, infosource
, title
and slugline
properties. It also added the value component
under type. It changed the description of the renditions
property and added sub-properties duration
and format
.
9.4. ninjs 1.3
Version 1.3 of the ninjs schema was approved by the IPTC Standards Committee and made available in May 2020.
Version 1.3 added the headline_
, altids
, trustindicator
, $standard
and genre
properties.
9.5. ninjs 1.4
Version 1.4 of the ninjs schema was approved by the IPTC Standards Committee in May 2022. It contains new fields contentcreated, expires and rightsinfo.
9.6. ninjs 1.5
Version 1.5 of the ninjs schema was approved by the IPTC Standards Committee in May 2023. It includes the new contactInfo
type which can be applied to the person
, organisation
, place
and infosource
properties. ninjs 1.5 also includes the new symboltype
and symbol
properties under symbols
, and new properties creator
, relevance
and confidence
under subject
. Use of ticker
under symbols
is now deprecated.
In addition, some changes to the schema were made to fix a validation bug in previous versions. In order to accommodate these changes, the ninjs 1.5 schema uses the http://json-schema.org/draft-07/schema#
version of JSON Schema.
9.7. ninjs 2.0
Version 2.0 of the ninjs schema was approved by the IPTC Standards Committee and made available in October 2021.
Many changes were made for Version 2.0, some of them breaking backwards compatibility:
-
headline_*
changed toheadlines
-
body_*
changed tobodies
-
description_*
changed todescriptions
-
altid_*
changed toaltids
-
byline
changed toby
to become more consistent with IPTC News Architecture and NewsML-G2 -
person
changed topeople
-
organisation
changed toorganisations
-
place
changed toplaces
-
event
changed toevents
-
object
changed toobjects
-
infosource
changed toinfosources
-
trustindicator
changed totrustindicators
-
infosource/rel
changed toinfosource/role
to be more consistent with other properties and the IPTC News Architecture -
all metadata properties now use URIs with an optional literal instead of schemes and codes
-
Clarified definition of
uri
-
Removed
mimetype
property -
Added
contentcreated
property -
Changed
representationtype
enum values from complete and incomplete to full and partial -
charcount
andwordcount
moved to properties ofbodies
elements -
`$standard" changed to "standard"
-
Added a new
rightsinfo
property with eitherlinkedrights
orembeddedrights
as a child property
An errata release of 2.0 in May 2022 fixed a problem with the GeoJSON property in the places
object.
9.8. ninjs 2.1
Version 2.1 of the ninjs schema was approved by the IPTC Standards Committee in May 2023 and made available in June 2023.
ninjs 2.1 includes the new contactInfo
type which can be applied to the people
, organisations
, places
and infosources
properties. ninjs 2.1 also includes the new symboltype
and symbol
properties under symbols
, and new properties creator
, relevance
and confidence
under subjects
. The ticker
sub-property under symbols
is now deprecated.
In addition, some changes to the schema were made to fix a validation bug in previous versions. In order to accommodate these changes, the ninjs 2.1 schema uses the https://json-schema.org/draft/2020-12/schema
version of JSON Schema.
9.9. ninjs 3.0
Version 3.0 of the ninjs schema was approved by the IPTC Standards Committee in October 2024 and made available in November 2024.
ninjs 3.0 is a comprehensive update including several major new features:
* Support for news events and planned news coverage, including expected dates (to be used when exact dates and times are not known), event recurrence information and support for commissioning information on planned coverage
* Switch to camelCase for all properties, to better align with JSON and GraphQL best practice
* Additional rendition properties such as videoCodec
, frameRate
, scanType
and transportProtocol
to better support video content, including live streamed video
* Removal of deprecated properties such as ticker
and tidying up of descriptions throughout
10. Additional Resources
10.1. On the Web
The IPTC web site www.iptc.org has a wealth of resources for implementers. The page www.iptc.org/standards summarises all of the IPTC’s standards and provides links to further resources for each, including ninjs, NewsML-G2, SportsML-G2 and RightsML.
There are also user groups at Groups.io for all those seeking answers to questions about ninjs or other IPTC standards, and for those who would like to participate in development work:
-
https://groups.io/g/iptc-ninjs/ is the public group for discussing ninjs and other representations of news content in the JSON format.
-
https://groups.io/g/iptc-newsml-g2/ is the public group for NewsML-G2 and Events in NewsML-G2 topics.
-
Staff from IPTC Member organisations are welcome to join the members-only discussion list for the ninjs development team.
10.2. Join the IPTC
The IPTC welcomes new members. Membership is the backbone of the IPTC, and levels vary for both organisations and individuals. Additionally, several "working parties" and "working groups" focus on specific topic areas and standards. IPTC also hosts two face-to-face meetings a year around the globe, where its working parties discuss and develop their ideas to support information exchange and the rapid innovation of media.
To find out more, visit https://www.iptc.org/participate