Document relations and types

IMNML format is to a great extent based on relations and types in order to convey the meaning and how to interpret the data in the document. Here we aim to list and describe the relations and types used in IMNML.

Note that there might be other relations and types used in the format as a result of customers own systems, applications and/or plugins and concepts make update/modifies the documents. The usage of these customer specific values will not break IMNML documents but are handled as extensions of the format.

Namespaces

Namespaces in IMNML are used to specify ownership and type of data in the document. Typically namespaces are used for @type and @uri but also in combination with @qcode (NewsML attribute).

Types

Infomaker types are prefixed as described below. These types indicates that the data belongs to Infomaker applications such as Writer, Dashboard, Concept Admin, Newspilot and/or Newsroom Planner and, obviously, what type the data is.

The actual types used and their values that are owned by Infomaker are defined in a catalog file (wip). Compare with how IPTC are using catalogs and controlled vocabularies.

Below are the types used by different, Infomaker owned, systems described. For examples, see "Examples of usage of type and relations" below.

Note that depending on customers own applications and plugins that use and manipulate the IMNML documents there might be other types in use, e.g. x-cmbr (example of type belonging to Sydsvenskan).

Writer types

• x-im - prefix is typically used when type is used in combination with <link>and <object> elements (Infomaker extensions)

• imext - prefix used when extending NewsML standard types. Prefix applies to a number of different types used.

When the belonging of data cannot be determined, IMNML uses a pattern of giving the type a suffix - local, e.g. x-im/author/local. For more examples, see ”Examples of usage of type and relations” below.

Newspilot types

• x-np - prefix used when referencing data belonging to Infomaker Newspilot.

Newsroom Planner types

• nrpdesc - type of description

• nrprole - role of assigned entity in Newsroom Planner

• nrplinrol - role of address line

IMID types

• x-imid - prefix used to indicate that referenced value belongs to Infomaker ID.

• imid - prefix used when extending NewsML standard types where referenced value belongs to Infomaker ID. Usually used in combination with uri:s.

URI:s

In the case where a certain data cannot be identified with an uuid, URI:s can be used. The ”scheme” part of the URI should represent ownership of the data that the URI is used for. Different system will make use of different prefixes much as in the case of types (see above).

The remaining part of the URI, after scheme, is used to identify the actual data, normally using type and some sort of id, see examples below.

Note that a customers application/system and plugins might use there own URI:s in which case the URI should follow the same pattern, e.g. an URI used for data belonging to Sydsvenskan should use cmbr:// scheme.

Writer uri:s

• im:// - data belongs to Infomaker Writer and Infomaker plugins

Newspilot uri:s

• np:// - data belongs to Newspilot

Newsroom Planner uri:s

• nrp:// - data belongs to Newsroom Planner

IMID uri:s

• imid:// - data belongs to Infomaker ID

Examples of usage of URI:s

URI for a IPTC mediatopic:

iptc://medtopic/20000003

URI for a Writer article:

im://article/1d02738f-7c99-42ba-a6da-3d1b97261523"

URI for a Newspilot user:

np://user/58456

URI for a link to a IMID sub:

imid://user/sub/znY7U3CO134n26zv9gb44_jCzSp

Link relations

The <link> element is an extension used in the IMNML format. In order to describe how to use and interpret the link, typically the rel attribute is used (often in combination with the type attribute). Below is a list of values of the rel attribute supported in IMNML. Please note that, as in the case of types and URI:s, values of rel might differ from this list depending on customers own applications/systems and plugins using the documents.

• subject - document is tagged with a subject

• author - author of the document

• self - specifying link to actual entity (used in the case where there are multiple alternate links to same entity

• broader - parent of document

• same-as - duplicate of or different aspect/version of entity

• avatar - avatar image linked to document

• article - related article to document

• image - the linked document represents an image representation of the context

• replaced-by - document is replaced by other document

• creator - user created the document (Writer core will set this to authorized IMID user)

• updater - user updated the document (Writer core will set this to authorized IMID user)

• irel:seeAlso - resource for more information about the document

• associated-with - document is associated or grouped with other document

• mainchannel - the ”main” channel for the document

• channel - channel for the document

• articlesource - the original source of the document, e.g. ”TT”

• crop - the soft crop of an image

• alternate - alternative to the document

• type - link type (used when links represents values in a list for example)

• member - the linked document is a member of the context

• presentation - the linked to document represents the presentation that is to be used for the context. Used by eg. the deck system

• assigned-to - person is assigned to planned assignment

• organiser - organiser of an event

• participant - participant of an event

• location - a geographic location

• source - link represents the source for the entity being referenced (see "Source relations" below)

Source relations

In order to specify source information for a linked (referenced) entity, a link with rel attribute set to source should be used. Below is an example of how to specify source link for an image where "xyz" represent the provider (source) for the image.

<object id="dc1" type="x-im/image" uuid="f845d7b8-40cb-545a-8069-36e21ff00908">
    <links>
        <link rel="self" type="x-im/image" uri="im://image/znX8U1C123JLDjlksdfgb40_jIka.jpeg" uuid="f845d7b8-40cb-545a-8069-36e21ff00908">
            <data>
                <text>Vivamus luctus eros.</text>
                <width>3560</width>
                <height>2695</height>
            </data>
        </link>
        <link rel="source" type="x-xyz/image" uri="xyz://image/2345836363"/>
    </links>
</object>

For the corresponding image newsItem, this information would be put in the itemMeta > links element:

<link rel="source" type="x-xyz/image" uri="xyz://image/2345836363"/>

Source is also used in the "copy article" functionality in Writer, i.e. the copied version of the article will include a link pointing to the original article in the itemMeta > links element:

<link rel="source" type="x-im/article" uuid="95c0ddd3-d16f-49f5-bc28-9ddfada22e6c"/>

IMID relations

Below are nodes used in format to represent IMID relations.

Affiliations

In order to specify IMID affiliations, the link elements for "creator" and "updater" are used. Below is an example of affiliation connected to the "creator" but the same format applies for "updater".

<link rel="creator" type="x-imid/user" uri="imid://user/sub/znY7U3CO134n26zv9gb44_jCzSp">
    <links>
        <link rel="affiliation" type="x-imid/organisation" uri="imid://organisation/company-x" title="Company X">
            <links>
                <link rel="affiliation" type="x-imid/unit" uri="imid://unit/newspaper-z" title="Newspaper Z"/>
            </links>                    
        </link>                
    </links>    
</link>

Shared with

If the document is supposed to be shared with another IMID entity, the format below should be used (in addition to the "affiliation" format described above).

<itemMeta>
    <links xmlns="http://www.infomaker.se/newsml/1.0">
        <link rel="shared-with" type="x-imid/organisation" uri="imid://organisation/company-x" title="Company X">
            <links>
                <link rel="shared-with" type="x-imid/unit" uri="imid://unit/newspaper-v" title="Newspaper V" />
                <link rel="shared-with" type="x-imid/unit" uri="imid://unit/newspaper-q" title="Newspaper Q" />
            </links>
        </link>
    </links>    
</itemMeta>

NB: If the document is supposed to be shared with an organisation as a whole, the following structure should be used.

<itemMeta>
    <links xmlns="http://www.infomaker.se/newsml/1.0">
        <link rel="shared-with" type="x-imid/organisation" uri="imid://organisation/company-x" title="Company X">
            <links>
                <link rel="shared-with" type="x-imid/organisation" uri="imid://organisation/company-x" title="Company X"/>
            </links>
        </link>
    </links>    
</itemMeta>

By using this format there is no need to add anything to existing documents when a unit is added (or deleted) from an organisation. The convention of duplicating the "shared-with" link is to keep all "shared-with" links in the same position in the document, regardless if it is a unit or an organisation that the document is shared with.

The title and base component of the uri must abide to the below regex.

regex(/^[a-z0-9_\-]+$/i, {name: ‘a-z, 0-9, -, _‘})

Examples of usage of type and relations

Link to an author represented as a concept in Open Content:

<link rel="author" title="John Doe" type="x-im/author" uuid="49b895d6-2e92-11e8-b467-0ed5f89f718b"/>

Link to a ”custom” author, i.e. an author not belonging to a particular system or application:

<link rel="author" title="Karl-Erik Nilsson" type="x-im/author/local" uri="im://author/local/karl-erik_nilsson">

Link to an author belonging to Newspilot but not a concept:

<link rel="author" title="John Doe" type="x-np/author" uri="np://author/12345"/>

Link to an organiser belonging to Infomaker as a concept in Open Content:

<link rel="organiser" title="Svenska Fotbollsförbundet" type="x-im/organisation" uuid="12e0b2c8-a0b2-4b9f-9e89-bde13b827b3e"/>

Link to a ”custom” organiser, i.e. an organiser not belonging to a particular system or application:

<link rel="organiser" title="Svenska Fotbollsförbundet" type="x-im/organisation/local" uri="im://organisation/local/svenska_fotbollsforbundet"/>

Link to geo point represented as a concept in Open Content:

<link title="Alvesta" rel="subject" type="x-im/place" uuid="bce38dda-555b-11e5-885d-feff819cdc9f">
  <data>
    <geometry>POINT(14.55600 56.89921)</geometry>
  </data>
</link>

Link to a ”custom”, i.e. a geo point not belonging to a particular system or application:

<link title="Alvesta" rel="subject" type="x-im/place/local" uri="im://place/local/alvesta">
  <data>
    <geometry>POINT(14.55600 56.89921)</geometry>
  </data>
</link>

Link to external subject belonging to IPTC:

<link rel="subject" title="animation" type="cpnat:abstract" uri="iptc://medtopic/20000003"/>

Link to an IMID sub that is specified as a creator of an object:

<link rel="creator" type="x-imid/user" uri="imid://user/sub/znY7U3CO134n26zv9gb44_jCzSp"/>

Link to an alternate version of the article:

<link rel="alternate" type="x-im/article" uuid="a0836ecc-1d4a-4ce0-b5dc-7d06ba853759"/>

Link indicating that document is "grouped" under a certain concept (of type "x-im/group"):

<link rel="associated-with" type="x-im/group" uuid="7998ec7a-9fd0-4a6f-aee0-168e71f8ba83" title="Florida Publications"/>