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 2.1. Version 2.1 of the ninjs schema was made available in June 2023.

The latest version in the 1.x branch is 1.5, which was 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:

  1. 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, if the recipient would like to request more, using the representationtype: "partial" construct.

    • Starting from version 2.0, the ninjs schema has been created in such a way that it 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 as an example.

  2. 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. ninjs data model in a nutshell

As the below diagram shows, every ninjs object describes a News Item. 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 news item.

The content itself 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 news items together.

ninjs Data Model diagram

1.3. ninjs object building blocks

ninjs Object Building Blocks diagram

1.4. A simple example

ninjs can be very simple. This is an example of something that might be returned by an API call.

{
  "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."
    }
  ]
}

You can make your own simple ninjs document using the ninjs generator tool on iptc.org.

1.5. Two versions of ninjs: ninjs 1.5 and ninjs 2.1

IPTC manages two current versions of ninjs: the 2.x branch (where the latest version is 2.1) and the 1.x branch (where the latest version is currently 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 backwardscompatible. 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.

We wanted to issue a new release which fixed these problems, but this meant breaking backwards compatibility with the 1.x versions of ninjs. This is why we decided to maintain two parallel branches: 1.x and 2.x.

All new users are strongly recommended to use version 2.1.

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 2.1 version, but those who must use version 1.5 for backwards compatibility reasons can find the JSON Schema file for ninjs 1.5 schema at https://iptc.org/std/ninjs/ninjs-schema_1.5.json.

1.6. Differences between ninjs 1.x and 2.x

We maintain the 1.x branch for those who can’t move to the new structure in 2.0. Most of the properties are the same as the ones in ninjs 2.x, with the exception of the multi-valued properties.

1.6.1. patternProperties converted to arrays

Some properties are implemented as "patternProperties" in the 1.x JSON Schema, 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 can be used to distinguish objects from each other. In the 2.x version of the schema, we converted them to be 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 as

{
  "headlines": [
    {
      "role": "subhead",
      "value": "My subheadline"
    }
  ]
}

This applies to the following properties:

  • description_XXX (1.x) / descriptions (2.x)

  • body_XXX (1.x) / bodies (2.x)

  • headline_XXX (1.x) / headlines (2.x)

1.6.2. Renditions and Associations converted to arrays

The renditions and associations properties are arrays in ninjs 2.x and objects in ninjs 1.x.

In ninjs 1.x a rendition may look like the following:

{
  "renditions": {
    "highres": {
      ...
    }
  }
}

The same rendition in ninjs 2.x would look like:

{
  "renditions": [
    {
      "name": "highres",
      ...
    }
  ]
}

Associations work the same way in both ninjs 1.x and ninjs 2.x.

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.

  • altid (ninjs 1.x) / altids (ninjs 2.x)

  • event (ninjs 1.x) / events (ninjs 2.x)

  • genre (ninjs 1.x) / genres (ninjs 2.x)

  • infosource (ninjs 1.x) / infosources (ninjs 2.x)

  • object (ninjs 1.x) / objects (ninjs 2.x)

  • organisation (ninjs 1.x) / organisations (ninjs 2.x)

  • person (ninjs 1.x) / people (ninjs 2.x)

  • place (ninjs 1.x) / places (ninjs 2.x)

  • subject (ninjs 1.x) / subjects (ninjs 2.x) and

  • trustindicator (ninjs 1.x) / trustindicators (ninjs 2.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 2.x branch: currently ninjs 2.1. This version should be easiest for developers to work with.

If you are already using a 1.x version of ninjs, we recommend at least upgrading to the latest version in the 1.x branch, currently 1.5. This should be an easy change, because 1.5 is backwards-compatible with earlier 1.x versions.

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

Copyright © 2023 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 (ex-AP), Brendan Quinn (IPTC), Michael Steidl (IPTC), Evan Sandhaus (ex-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 IPTC Member organisations 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. The 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 membership.

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.

3.1. Administrative properties

These properties concern the structure, type and creation details of the content.

Property Description Data type

uri

The identifier for this news object

URI

type

The generic news type of this news object

One of:
text
audio
video
picture
graphic
composite
component

title

A short natural-language name for the item.

string

standard

An object with information about standard, version and schema this instance is valid against.
This property is an object with the following child properties:

Property name Description Data type

name

The name of the standard, such as ninjs.

string

version

The version of the standard used, such as 2.1.

string

schema

The uri of the JSON schema to use for validation, such as https://www.iptc.org/std/ninjs/ninjs-schema_2.1.json

URI

object

altids

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.
This property is an object with the following child properties:

Property name Description Data type

role

The role of the alternative id (such as "internal")

string

value

The alternative id value

string

array of objects

representationtype

Indicates the completeness of this representation of a news item.
For a full document representation, the value should be full.
For a partial representation, for example a short extract provided as the results of an API call, the value partial should be used.

One of:
full
partial

profile

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 'text-only' or 'text-photo'. Profiles are typically provider-specific.

string

version

The version of the news object which is identified by the uri property.

string

firstcreated

Indicates when the first version of the item was created.

date-time

versioncreated

The date and time when this version of the news object was created.

date-time

contentcreated

The date and time when the content of this ninjs object was originally created.

date-time

embargoed

The date and time before which all versions of the news object are embargoed. If absent, this object is not embargoed.

date-time

expires

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

pubstatus

The publishing status of the news object, its value is usable by default.

One of:
usable
withheld
canceled

urgency

The editorial urgency of the content from 1 to 9. 1 represents the highest urgency, 9 the lowest.

number

ednote

A note that is intended to be read by internal staff at the receiving organisation, but not published to the end-user.

string

language

The human language used by the content. The value should follow IETF BCP47 format.

3.2. Rights properties

Property Description Data type

copyrightholder

The person or organisation claiming the intellectual property for the content.

string

copyrightnotice

Any necessary copyright notice for claiming the intellectual property for the content.

string

usageterms

A natural-language statement about the usage terms pertaining to the content.

string

rightsinfo

An expression of rights to be applied to the content.

This property is an object with the following child properties:

Property name Description Data type

langid

Identifier for the used Rights Expression language.

uri

linkedrights

A link from the current Item to Web resource with rights related information.

uri

encodedrights

Contains a rights expression as defined by a Rights Expression Language.

string

For each array element under rightsinfo, one of either linkedrights or encodedrights is required.

Array of objects

3.3. Editorial properties

Properties representing the actual story that will be shown to the audience.

Property Description Data type

headlines

Array of objects containing various types of headlines.

This property is an object with the following child properties:

Property name Description Data type

role

The role of this headline

string

contenttype

The IANA (Internet Assigned Numbers Authority) Media Type of the content of this headline. (Previously known as MIME Type.)

string

value

The headline identified with the above role and contenttype. Required in each object in the array.

string

Array of objects

slugline

A human-readable identifier for the item.

string

by

The name(s) of the creator(s) of the content

string

bodies

An array of body objects with the content as text or with markup.

This property is an object with the following child properties:

Property name Description Data type

role

The role of this body

string

contenttype

The IANA (Internet Assigned Numbers Authority) Media Type of the content of this body. (Previously known as MIME Type.)

string

value

The headline identified with the above role and contenttype. Required to exist in each array item.

string

charcount

The total character count in the article excluding figure captions.

number

wordcount

The total number of words in the article excluding figure captions.

number

Array of objects

descriptions

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:

Property name Description Data type

role

The role of this description

string

contenttype

The IANA (Internet Assigned Numbers Authority) Media Type of the content of this description. (Previously known as MIME Type.)

string

value

The descriptive text identified with the above role and contenttype. Required in each object in the array.

string

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.

Property name Description Data type

located

The name of the location from which the content originates.

See also places for locations which are mentioned in the content.

string

genres

The nature, intellectual or journalistic form of the content.

This property is an array of objects with the following properties:

Property name Description Data type

name

The human-readable name of the genre, such as Press Release.

string

uri

The identifier of the genre as a complete uri

URI

literal

The code for the genre as a string literal

string

array

people

An array of objects describing individual human beings.
This property is an array of objects with the following properties:

Property name Description Data type

name

The name of a person

string

rel

The relationship of the content of the news object to the person

string

uri

The identifier for the person as a complete uri with the code.

URI

literal

The code for the person as a literal value.

string

contactinfo

Contact and/or location information for the person as a ContactInfo structure.

Contact Info structure

array

organisations

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.
This property is an array of objects with the following properties:

Property name Description Data type

name

The name of the organisation

string

rel

The relationship of the content of the news object to the organisation

string

uri

The identifier of the organisation as a complete uri

URI

literal

The code for the organisation as a literal

string

symbols

Symbols used for a financial instrument linked to the organisation at a specific market place.
Array of objects with the properties:

  • exchange: Identifier for the marketplace which uses the ticker symbols of the ticker property (string)

  • symboltype: URI describing the type of the symbol. The CV http://cv.iptc.org/newscodes/financialinstrumentsymboltype is recommended.

  • symbol: Symbol identifier, including ticker symbols. We recommend using this sub-property.

  • ticker: Ticker symbol used for the financial instrument (string). This sub-property is allowed but deprecated.

array

contactinfo

Contact and/or location information for the organisation as a ContactInfo structure.

Contact Info structure

array

places

An array of named locations.
This property is an array of objects with the following properties:

Property name Description Data type

name

The name of the place

string

rel

The relationship of the content of the news object to the place

string

uri

The identifier for the place as a complete uri

URI

literal

The code for the place as a literal

string

contactinfo

Contact and/or location information for the place as a ContactInfo structure.

Contact Info structure

geojson

An object holding geo data of this place. From ninjs 2.0 onwards, the contents of this object must conform to the GeoJSON format defined in RFC 7946.

object

array

subjects

An array of objects holding concepts with a relationship to the content.
This property is an array of objects with the following properties:

Property name Description Data type

name

The name of the subject

string

rel

The relationship of the content of the news object to the subject

string

uri

The identifier of the subject as a complete uri

URI

literal

The code for the subject as a string literal

string

creator

Specifies which entity (person, organisation or system) that has created or last edited the property.

string

relevance

The relevance of the metadata to the news content to which it is attached.

integer (range 0-100)

confidence

The confidence with which the metadata has been assigned.

integer (range 0-100)

array

events

An array of objects describing something which happens in a planned or unplanned manner.
This property is an array of objects with the following properties:

Property name Description Data type

name

The name of the event

string

rel

The relationship of the content of the news object to the event

string

uri

The identifier for the event as a complete uri

URI

literal

The code for the event as a string literal

string

array

objects

An array of objects describing something material, excluding persons.
This property is an array of objects with the following properties:

Property name Description Data type

name

The name of the object

string

rel

The relationship of the content of the news object to the object

string

uri

The identifier for the object as a complete uri

URI

literal

The code for the object as a string literal

string

array

infosources

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.
This property is an array of objects with the following properties:

Property name Description Data type

name

The name of the infosource

string

role

The role the infosource in relationship to the content as a uri.

string

uri

The identifier of the infosource as a complete uri

URI

literal

The code for the infosource as a string literal

string

contactinfo

Contact and/or location information for the info source as a ContactInfo structure.

Contact Info structure

array

trustindicators

An array of objects to allow links to documents about trust indicators, intended to show the trustworthiness of the news provider.
This property is an array of objects with the following properties:

Property name Description Data type

role

The role of the trust indicator as a complete uri, such as http://cv.iptc.org/newscodes/trustindicator/editorialPolicy

URI

href

The URL for accessing the trust indicator resource, such as https://www.bbc.com/editorialguidelines/

string

title

The name of the resource being referenced, such as BBC Editorial Guidelines

string

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

Type would be method of communication like phone, mobile, address etc.

string

role

Role refers to type and could be private, office etc

string

lang

If this contactinfo object need to be qualified with what language it is in. The value should follow IETF BCP47.

string

name

Human readable name of the contact method, like name for a web page, name of persons twitter account etc

string

value

Actual phone number, email address, web url etc.

string

address

The address of a person, place or organisation. This property is an object with the following child properties:

Property name Description Data type

lines

An array of lines to construct an address. The order is important to construct a correct address.

array

locality

A city/town/village etc. part of the address.

string

area

A subdivision of a country part of the address.

string

postalcode

A postal code part of the address.

string

country

A country part of the address.

string

object

3.5. 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.

3.5.1. Properties of renditions

Property name Description Data type

name

The name of this object in the array of renditions. Required

string

href

The URL for accessing the rendition as a resource

URI

contenttype

A media type which applies to the rendition

string

title

A title for the link to the rendition resource

string

height

For still and moving images: the height of the display area measured in pixels

number

width

For still and moving images: the width of the display area measured in pixels

number

sizeinbytes

The size of the rendition resource in bytes

number

duration

The total time duration of the content in seconds

number

format

Binary format name

string

3.5.2. Renditions example

{
  "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
    }
  ]
}

3.6. 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.

3.6.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.

{
  "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"
        }
      ]
    }
  ]
}

4. ninjs Examples

4.1. Text-only examples

4.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 and headlines are typical text news metadata

  • The text of article itself is represented by bodies, in two format variants: plain text and HTML.

{
  "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>"
    }
  ]
}

4.1.2. A more complex example

  • Metadata about the content are added to the example above.

  • person, place and organisation employ a structure which provides human readable names for the entity but also machine readable identifiers by the scheme and code properties.

{
  "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>"
    }
  ]
}

4.1.3. More Examples on GitHub

You can find more examples of ninjs representations of text-based news releases in the ninjs GitHub repository.

4.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.

{
  "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
    }
  ]
}

4.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)

{
  "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
        }
      ]
    }
  ]
}

5. ninjs Best Practices and How Tos

Here we describe some best practices for working with ninjs in your own organisation.

5.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.

5.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.

5.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:

  1. make a copy of the schema file

  2. change the URL of the "id" property of IPTC’s ninjs 2.1 …​

    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "id" : "http://www.iptc.org/std/ninjs/ninjs-schema_2.1.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",
      ...
  3. 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"
      },
      ...
  4. 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."
}

5.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."
  ...
}

6. Tools for developing with ninjs

6.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

6.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.

6.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 both ninjs 1.5 and ninjs 2.1.

The tool can be accessed at https://iptc.org/std/ninjs/generator/.

6.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.

7. 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 2.x property name NewsML-G2 equivalent

uri

nar:newsItem@guid

type

nar:itemClass

title

nar:itemMeta/title

altids

nar:altId

profile

nar:profile

version

nar:newsItem@version

firstcreated

nar:firstCreated

versioncreated

nar:versionCreated

expires

nar:expires

embargoed

nar:embargoed

pubstatus

nar:pubStatus

urgency

nar:urgency

ednote

nar:edNote

language

nar:language

copyrightholder

nar:copyrightHolder

copyrightnotice

nar:copyrightnotice

usageterms

nar:usageTerms

rightsinfo

nar:rightsInfo

headlines

nar:headline with @role

headlines@contenttype

nar:contentType

slugline

nar:slugline

by

nar:by

bodies

nar:data or nar:inlineXML

bodies@charcount

nar:charcount

bodies@wordcount

nar:wordcount

bodies@contenttype

nar:contentType

descriptions

nar:description

descriptions@contenttype

nar:contentType

located

nar:located

genre

nar:genre

person

nar:subject

organisation

nar:subject

place

nar:subject

subject

nar:subject

object

nar:subject

infosource

nar:infoSource

trustindicator

nar:link with @rel

renditions

nar:remoteContent

renditions@href

nar:remoteContent@ref

renditions@contenttype

nar:remoteContent@contenttype

renditions@height

nar:remoteContent@height

renditions@width

nar:remoteContent@width

renditions@format

nar:remoteContent@format

renditions@duration

nar:remoteContent@duration

associations

nar:link

8. ninjs Revision History

8.1. ninjs 1.0

Version 1.0 of the ninjs schema was approved by the IPTC Standards Committee on 23 October 2013.

8.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.

8.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.

8.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.

8.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.

8.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.

8.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 to headlines

  • body_* changed to bodies

  • description_* changed to descriptions

  • altid_* changed to altids

  • byline changed to by to become more consistent with IPTC News Architecture and NewsML-G2

  • person changed to people

  • organisation changed to organisations

  • place changed to places

  • event changed to events

  • object changed to objects

  • infosource changed to infosources

  • trustindicator changed to trustindicators

  • infosource/rel changed to infosource/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 and wordcount moved to properties of bodies elements

  • `$standard" changed to "standard"

  • Added a new rightsinfo property with either linkedrights or embeddedrights as a child property

An errata release of 2.0 in May 2022 fixed a problem with the GeoJSON property in the places object.

8.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. Additional Resources

9.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:

9.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