Structured Text Feed

Structured text feeds are more complex text structured organized in categories, where each category contains a list of entries, and each entry contains a title and a content. The content of a structured text feed is equivalent to the text property in the simple text feed.

Example JSON

The example above shows a structured text feed with two categories (Wissen and Umwelt), the Wissen category shows three visible entries. The second entry is expanded, so its content is visible. Each entry’s title is shown.

{
  "apiVersion": 1,
  "categories": [
    {
      "id": "umwelt",
      "label": {
        "de": "Umwelt"
      },
      "entries": {
        "en": [
          {
            "id": "category_1_entry_1",
            "title": "category_1 entry_1 title text",
            "content": "category_1 entry_1 rich text content"
          },
          {
            "id": "category_1_entry_2",
            "title": "category_1 entry_2 title text",
            "content": "category_1 entry_1 rich text content"
          }
        ],
        "de": []
      }
    },
    {
      "id": "wissen",
      "label": {
        "de": "Wissen"
      },
      "enableAnchor": true,
      "entries": {
        "de": [
          {
            "id": "category_2_entry_1",
            "title": "Unis bekommen mehr Budget",
            "content": "Dieses Jahr bekommen zahlreiche Unis mehr Budget",
            "attribution_image_url": "https://example.unwired.at/some-image.jpg",
            "tag": "Wissen"
          }
        ]
      }
    }
  ]
}

Validations

apiVersion must be set to 1 (as a number, not a string)
id of a category is a string value and mandatory
- This id needs to be unique within the whole feed
- This id will be used as the html anchor in the URL (e.g. #wissen)
- This needs to be a string ID (e.g. "id": "0") and not numeric (e.g. "id": 0)
- enableAnchor is boolean, optional and defaults to false
  - If true -> the category will be included as an anchor of the widget (similar to simple text widget) and thus be visible in the 2nd menu level using the text from the label property
  - If false -> the category will not be linked/visible in the 2nd menu level
- label is an object and optional, except if enableAnchor is true, then it is mandatory, and must contain at least the default language of the captive portal page (this depends on the customer’s project)
  - The object maps language codes (ISO 639-1) to label strings
    - Each label string is mandatory for each provided language code property
  - This property will be used to render the anchor in the 2nd menu level
  - Allowed html entities:
    - soft hyphen: 
- List of entries:
  - For each language an array of entries must be provided
  - The array of entries for a specific language can be empty
  - The languages must match the languages in the label property if enableAnchor is true
  - For a single entry: content is string and mandatory
  - It is equivalent to the text property of the simple text widget described above
  - It’s recommended to not use the h1 tag, as the title of the entry already uses h1
  - title is string and mandatory
  - This is rendered as an entry’s title text which can be expanded to view the content
  - This entry does not support rich text or html tags
    - Allowed html entities:
    - soft hyphen: 
    - id of an entry is a string value and mandatory
    - This id needs to be unique within the whole feed, not just within the category.

Internationalization Validations

If an entry is present in a certain language, and enableAnchor is true, then labels must be translated in the same languages as the entries and vice versa. At least one language must be present.

The JSON example above shows:

The feed contains two categories
The first category contains two entries for English and zero for German
The second category contains one entry for German
The second category has the enableAnchor property set to true

The interpretation of this feed data is:

Two categories are shown below each other (see screenshot example above) Only the category with the id="wissen" will be shown in the 2nd menu level, because its enableAnchor property is set to true.

Hint

The first entry in one language is mapped to the first entry in other languages within the same category, and this pattern continues sequentially.

For example, en[0] corresponds to the same entry (in a different language) as de[0], and en[1] corresponds to de[1], and so forth.

If one language has more entries than another, the additional entries will be safely added, but they will only be available in that single language.

POI extensions

The POI extensions to the structured text feed allow matching individual entries to POI properties (e.g. stop name, stop id). Entries will be shown if any of the given matchers within the POI_match property matches.

To disable the POI_match feature, the property must not be present in the JSON document. An empty POI_match (e.g. "POI_match": []), will never show the entry.

Currently supported matching properties:

stop.id (arbitrary id that must match the journey feed)
stop.ibnr (if present in journey feed)
stop.ds100 (if present in journey feed)
stop.name

Currently supported matching behavior: Match any … matched string has to exactly match the property value, any matcher within the POI_match property can match to show the POI.

JSON structure:

POI_match contains an array of matchers
- Can be used within the entry object (see above)

Example POI_match:

{
  // ...
  "POI_match": [
    { "stop": { "id": "VIE" } },
    { "stop": { "name": "Naumburg (Saale) Hbf." } }
  ]
  // ...
}

In this example the match contains two matchers, one matching the Stop’s ID property to VIE and another one that matches the stop’s name property to Naumburg (Saale) Hbf.. This POI_match would then show the entry if either condition was fulfilled.

Example JSON of structured text feed with POI_match extension:

{
  "apiVersion": 1,
  "categories": [
    {
      "id": "umwelt",
      "label": {
        "de": "Umwelt",
        "en": "Environment"
      },
      "entries": {
        "en": [
          {
            "id": "category_1_entry_1",
            "title": "category_1 entry_1 title text",
            "content": "category_1 entry_1 rich text content",
            "POI_match": [{ "stop": { "id": "VIE" } }]
          },
          {
            "id": "category_1_entry_2",
            "title": "category_1 entry_2 title text",
            "content": "category_1 entry_1 rich text content",
            "POI_match": [
              { "stop": { "id": "VIE" } },
              { "stop": { "name": "Naumburg (Saale) Hbf." } }
            ]
          }
        ]
      }
    },
    {
      "id": "wissen",
      "label": {
        "de": "Wissen",
        "en": "Education"
      },
      "enableAnchor": true,
      "entries": {
        "de": [
          {
            "id": "category_2_entry_1",
            "title": "Unis bekommen mehr Budget",
            "content": "Dieses Jahr bekommen zahlreiche Unis mehr Budget",
            "POI_match": [{ "stop": { "name": "Naumburg (Saale) Hbf." } }]
          }
        ]
      }
    }
  ]
}

Tag extension

The tag extensions to the structured text feed allows a label to be added to an entry for each language. This can be an alternative to categories, if structuring into categories is not desired.

{
  "entries": {
    "de": [
      {
        "id": "category_2_entry_1",
        "title": "Unis bekommen mehr Budget",
        "content": "Dieses Jahr bekommen zahlreiche Unis mehr Budget",
        "tag": "Wissen"
      }
    ]
  }
}

Attribution Image URL

Some feed providers may want you to add an attribution notice to each entry. This can be done by adding an attribution_image_url to the entry. The image will be shown below the headline of the entry.

{
  "entries": {
    "de": [
      {
        "id": "category_2_entry_1",
        "title": "Unis bekommen mehr Budget",
        "content": "Dieses Jahr bekommen zahlreiche Unis mehr Budget",
        "attribution_image_url": "https://example.unwired.at/some-image.jpg",
      }
    ]
  }
}

Content revisions table

Revision	Published date	Changes
1.0	2018-07-01	initial release
1.1	2018-09-08	added POI information, clarified content
1.4	2019-01-16	added DS100 and IBNR match options for POI
1.5	2019-01-19	clarified on how to disable the POI_match feature added support for soft hyphens added support for video and audio tags
1.6	2020-09-02	added newsarticle__lead content-type header requirement
1.7	2023-08-31	moved to public docs
1.8	2024-05-16	added tag extension, added attribution_image_url, added information about entry indexing