Article ۰ Element

Elements are self-contained objects that represent structured data that is usually too complex to fit into our usual workhorse which is the Body.

Elements can appear in multiple places within the Article:

Article.elements

Elements of the article which are not part of the textual body, e.g. author, opener and teaser. Those elements should be used to render the article as a teaser e.g. on section pages.

BodyNode.children:

Is the place where Element are quite commonly used. They come in various types and will be rendered inplace, thus breaking up the textual body.

Elements.children:

Some more sophisticated Elements make use of nesting to make their API representation more concise and help to structure things hierarchically:

video uses nesting to model its optional poster image which itself is a normal image.
galleries have their individual images nested within.

Different types of elements like images or videos share the same message structure distinguished by the ElementType field.

See Sample section.

Field name	Type	Description
`type`	`Type`	`type` of this `Element`, see `Element.Type`
`relations`	`repeated` `Relation`	The usages (relations) of an element. See `Relation`
`assets`	`repeated` `Asset`	`Assets` describing this `Element`, See Samples
`children`	`repeated` `Element`	nested `Elements`, e.g. for `Element` of type `gallery` and `video`


message Element {
Type type = 1;
repeated Relation relations = 2;
repeated Asset assets = 3;
repeated Element children = 4;

[~]

`Element.Type`

Enum value	Description
`TYPE_UNSPECIFIED`	unspecified
`ARTICLE`	unused
`IMAGE`	image, containing further `Assets`. Sample
`VIDEO`	video, containing nested `Asset` and an optional nested image `Element`. Sample
`GALLERY`	gallery, consists of many nested image `Element`s.
`OEMBED`	oEmbed, contains one `metadata` `Asset`. Todo: sample
`AUTHOR`	author, contains one `metadata` `Asset` and an optional image `Element`. Todo: sample
`AGENCY`	author, contains one `metadata` `Asset`
`EDGE_SIDE_INCLUDE`	`<esi:include>` that must be resolved server-side for SEO reasons, otherwise similar to `OEMBED`
`CITATION`	oEmbed, contains one `metadata` `Asset`. Todo: sample
`INTERNAL_WIDGET`	widget or embed that is handled directly by the front end rendering Todo: sample


enum Type {
TYPE_UNSPECIFIED = 0;
ARTICLE = 1;
IMAGE = 2;
VIDEO = 3;
GALLERY = 4;
OEMBED = 5;
AUTHOR = 6;
AGENCY = 7;
EDGE_SIDE_INCLUDE = 8;
CITATION = 9;
INTERNAL_WIDGET = 10;
}

[~]

`Element.Relation`

Enum value	Description
`RELATION_UNSPECIFIED`	unspecified
`OPENER`	As an opener element (within the content)
`TEASER`	As a teaser element (when externally viewed)
`SOCIAL`	Use as social element (mostly images), e.g. `<og:image>` or JSON-LD

enum Relation {
RELATION_UNSPECIFIED = 0;
OPENER = 1;
TEASER = 2;
SOCIAL = 3;
}

[~]

Samples

For details on certain fields or usages of Assets, please follow this link.

`image element`

usually consist of one Asset[@type=METADATA] and several Asset[@type=IMAGE], one for each crop.

{
  "type": "IMAGE"
  "relations": [ "OPENER", "TEASER" ],
  "assets": [{
    "fields": {
      "media_id": "90635672v2",
      "caption": "Annalena Baerbock und Joschka Fischer bei einer Wahlkampfveranstaltung: Die Grünen-Kanzlerkandidatin fordert von der Bundesregierung, mindestens 10.000 Menschen aus Afghanistan aufzunehmen.",
      "alt_text": "Annalena Baerbock und Joschka Fischer bei einer Wahlkampfveranstaltung: Die Grünen-Kanzlerkandidatin fordert von der Bundesregierung, mindestens 10.000 Menschen aus Afghanistan aufzunehmen.",
      "description": "Annalena Baerbock und Joschka Fischer bei einer Wahlkampfveranstaltung: Die Grünen-Kanzlerkandidatin fordert von der Bundesregierung, mindestens 10.000 Menschen aus Afghanistan aufzunehmen.",
      "source": "/Reuters-bilder"
    },
    "type": "METADATA",
    "metadata": {
      "state": "STATE_UNSPECIFIED",
      "start_time": { "seconds": "-62135596800" },
      "end_time": { "seconds": "253402300799" }
    }
  },
  {
    "type": "IMAGE",
    "fields": {
      "crop": "original",
      "url": "https://di7yufqc6mgnl.cloudfront.net/2021/08/90635672v2/fit-in/0x0/annalena-baerbock-und-joschka-fischer-bei-einer-wahlkampfveranstaltung-die-gruenen-kanzlerkandidatin-fordert-von-der-bundesregierung-mindestens-10000-menschen-aus-afghanistan-aufzunehmen.jpg",
      "width": "1920",
      "height": "1280"
    },
  },
  {
    "type": "IMAGE",
    "fields": {
      "crop": "16:9",
      "url": "https://di7yufqc6mgnl.cloudfront.net/2021/08/90635672v2/0x0:1920x1077/fit-in/0x0/annalena-baerbock-und-joschka-fischer-bei-einer-wahlkampfveranstaltung-die-gruenen-kanzlerkandidatin-fordert-von-der-bundesregierung-mindestens-10000-menschen-aus-afghanistan-aufzunehmen.jpg",
      "width": "1920",
      "height": "1077"
    }
  }
  ]}
}

`video element`

usually consist of one Asset[@type=METADATA] and one Asset[@type=VIDEO].
If the video has a poster image, it can be found as a nested child Element[type=IMAGE] within children[]

{
  "relations": [ "OPENER" ],
  "type": "VIDEO"
  "assets": [
    {
      "type": "METADATA",
      "fields": {
        "media_id": "0DgeZjJtJ8EC",
        "caption": "Eine Statue der Justitia mit einer Waage und einem Schwert in ihren Händen.",
        "frame_capture:url": "https://d1q9f0uk9ts7gc.cloudfront.net/2021/08/0DgeZjJtJ8EC/thumbnails/maas-haben-500-menschen-aus-kabul-ausgeflogen_thumb.0000031.jpg",
        "frame_capture:numerator": "1",
        "frame_capture:denominator": "5"
      },
      "metadata": {
        "state": "STATE_UNSPECIFIED",
        "start_time": { "seconds": "-62135596800" },
        "end_time": { "seconds": "253402300799" }
      }
    },
    {
      "type": "VIDEO"
      "fields": {
        "duration_seconds": "157.576",
        "mime_type": "application/vnd.apple.mpegurl",
        "url": "https://d1q9f0uk9ts7gc.cloudfront.net/2021/08/0DgeZjJtJ8EC/hls/maas-haben-500-menschen-aus-kabul-ausgeflogen.m3u8",
        "height": "1080",
        "width": "1920"
      },
    }
  ],
  "children": [
    {
      "type": "IMAGE"
      "assets": [
        {
          "fields": {
            "media_id": "amOyEe-u5llZ"
          },
          "type": "METADATA",
          "metadata": {
            "start_time": { "seconds": "-62135596800" },
            "end_time": { "seconds": "253402300799" }
          }
        },
        {
          "type": "IMAGE",
          "fields": {
            "crop": "original",
            "url": "https://di7yufqc6mgnl.cloudfront.net/2021/08/amOyEe-u5llZ/fit-in/0x0/image.png",
            "width": "1500",
            "height": "844"
          }
        }
      ]
    }
  ]
}

`gallery element`

usually consist of one Asset[@type=METADATA] describing the gallery itself
several nested Element[@type=IMAGE] within children[], one for each image of this gallery

{
  "relations": [ "OPENER" ],
  "type": "GALLERY",
  "assets": [
    {
      "type": "METADATA",
      "fields": {
        "headline": "Gallery ipsum dolor",
        "ref_path": "/test-playground/id_100000067/gallery-ipsum-dolor.html",
        "ref_canonical": "https://www.t-online.de/test-playground/id_100000067/gallery-ipsum-dolor.html",
        "url": "/test-playground/id_100000067/gallery-ipsum-dolor.html"
      }
    }
  ],
  "children": [
    {
      "type": "IMAGE",
      "assets": [
        {
          "type": "METADATA",
          "fields": {
            "media_id": "82333994v1",
            "caption": "Wer unterwegs Äpfel pflückt, kann sich strafbar machen.",
            "alt_text": "Wer unterwegs Äpfel pflückt, kann sich strafbar machen.",
            "description": "Wer unterwegs Äpfel pflückt, kann sich strafbar machen.",
            "source": "Patrick Seeger/dpa-tmn/dpa"
          },
          "metadata": {
            "start_time": { "seconds": "-62135596800" },
            "end_time": { "seconds": "253402300799" }
          }
        },
        {
          "type": "IMAGE",
          "fields": {
            "crop": "original",
            "url": "https://di7yufqc6mgnl.cloudfront.net/2021/05/82333994v1/fit-in/0x0/wer-unterwegs-aepfel-pflueckt-kann-sich-strafbar-machen.jpg",
            "width": "640",
            "height": "360"
          }
        }
      ]
    }
  ]
}

[~]

tapir

Article ۰ Element

Element.Type

Element.Relation

Samples

image element

video element

gallery element

`Element.Type`

`Element.Relation`

`image element`

`video element`

`gallery element`