Item Schema

Superdesk uses internally item schema that is an extension of ninjs, so on ingest everything is converted to this schema, and on publishing it’s converted to different formats.

Basic Schema as defined in metadata_schema dict:


guid string

Globally unique id. Using external id for ingested content.

unique_id integer

Internally unique id.

unique_name string

Internally unique name. By default same as unique_id.

family_id string

Id for all items derived from single item via fetch or copy actions. For ingested items equals to ingest_id.

related_to string

Original item id when doing associate metadata action.

Content metadata

headline string

Item headline.

slugline string

Item slugline.

byline string

Item byline.

abstract string

Perex or lead.

keywords list

List of keywords.

word_count integer

Word count in body_html field.

priority integer

Item priority.

urgency integer

Item urgency.

description_text string

Text description of the item. Used for media types.

body_html string

Main content field for text items.

body_text string

Text content of the item. Used for preformatted text.

body_footer string

Content footer, used for additional information.

dateline dict

Info about when/where story was written.

groups dict

Package contents in NewsML like format.

media string

Binary file reference for media type items.

mimetype string

Binary file mime type.

poi dict

Point of Interest on a picture.

param x:horizontal offset
param y:vertical offset

renditions dict

Renditions of a media type item:

'renditions': {
    'original': {
        'href': '...',
        'width': 1280,
        'height': 800,

filemeta dict

Extracted file metadata. Mimetype specific.

Deprecated since version 1.2.

filemeta_json string

JSON encoded filemeta. Avoids storage issues.

New in version 1.2.

associations dict

Embedded items within body text or predefined relations:

'associations': {
    'featured_image': {
        'type': 'picture',
        'guid': 'urn:localhost:123',

alt_text string

Alternate text for picture type items.

sms_message string

Short summary of an item, can be used for sms/twitter subscribers.

Item metadata

type string

Item type. One of text|composite|picture|audio|video.

language string

Item language code.

anpa_take_key string

Take id.

profile string

Content profile id.

state string

Workflow state.

superdesk.metadata.item.content_state = ['draft', 'ingested', 'routed', 'fetched', 'submitted', 'in_progress', 'spiked', 'published', 'killed', 'corrected', 'scheduled']

item internal states

revert_state string

Previous item state, is updated on every state change.

pubstatus string

Publication state.

superdesk.metadata.item.pub_status = ['usable', 'withheld', 'canceled']

item public states

signal string

Signal information sent to subscriber.

ednote string

Editorial comment.

flags dict

Various flags.

expiry datetime

When this item will expire. It updates on every save/send action.


These attributes are populated using values from controlled vocabularies.

anpa_category list

Values from category cv.

subject list

Values from IPTC subjectcodes plus from custom cvs.

genre list

Values from genre cv.

company_codes list

Values from company codes cv.

place list

Place where story happened.


Set/updated by system mostly.

_current_version integer

Version of an item, gets incremented on save or publish.

version integer

Set by client - used to create items with version 0 which are used as drafts.

firstcreated datetime

When the item was created.

versioncreated datetime

When current version was created.

original_creator id

User who created/fetched item.

version_creator id

User who created current version.

lock_user id

User who has lock.

lock_time datetime

When item was locked.

lock_session id

Session id where item was locked. This way it can detect items locked by same user but in different sessions.

template id

Template id if item was created using a template.


Set on ingest, might be empty for items created in house.

ingest_id string

Ingest item id from which item was fetched. For ingested items same as family_id.

ingest_provider id

Ingest provider id.

source string

Ingest provider source value. Using DEFAULT_SOURCE_VALUE_FOR_MANUAL_ARTICLES config for items created locally.

original_source string

Source value from ingested item.

ingest_provider_sequence integer

Counter for ingest items.