Skip to content

Feed v2

Availability

As XML Schema: http://openmensa.org/open-mensa-v2.xsd

Changelog

Version 2.1 (2015-04-05, beta release)

  • New version tag to specify parser version
  • Meta data attributes like canteen name, address, contact info and information about different feeds for this canteen with its schedule information

Warning: The feed 2.1 is currently in implementation. Although we assume the schema remains unchanged, we may change details during the implementation.

Version 2.0 (2012-09-02)

Example

<?xml version="1.0" encoding="UTF-8"?>
<openmensa version="2.1"
           xmlns="http://openmensa.org/open-mensa-v2"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://openmensa.org/open-mensa-v2 http://openmensa.org/open-mensa-v2.xsd">
  <version>5.04-4</version>
  <canteen>
    <day date="2012-05-29">
      <category name="Hauptgericht">
        <meal>
          <name>Rührei mit Rahmspinat und Salzkartoffeln</name>
          <note>ovo-lacto-vegetabil</note>
          <price role="student">1.20</price>
          <price role="employee">2.60</price>
          <price role="other">3.00</price>
        </meal>
        <meal>
          <name>Hähnchengeschnetzeltes mit exotischen Früchten, dazu Bio-Reis und Mischsalat</name>
          <note>mit Geflügelfleisch</note>
          <price role="student">2.00</price>
          <price role="employee">3.35</price>
          <price role="other">4.00</price>
        </meal>
      </category>
      <category name="Sonstiges">
        <meal>
          <name>Spargelcremsuppe</name>
          <price role="other">2.00</price>
        </meal>
      </category>
    </day>

    <day date="2012-05-28">
      <closed/>
    </day>
  </canteen>
</openmensa>

Validation

If you build your feed’s xml carefully (simply copy the first 5 lines from our example, all the XML and schema foo will be done automatically for you), you may upload it to a XML validator (alternative validator) that recognizes XML schemas to check for validity.

If your feed is invalid with respect to our XML schema all contained data will be ignored! So keep your feed valid under all circumstances!

Elements

<openmensa>

The root element is openmensa. It encapsulate all other attributes. This element will be preserved across future feed versions. The version attribute must equal 2.0 or 2.1.

Which version you choose is not technically difference. OpenMensa supports all v2 features independent of the chosen version. We distinguish between the versions to raise errors on to old server schemas and to know which feature set is probably known/implemented.

<version> (since version 2.1)

The top version tag is optional. It can be inserted to define the version of the parser. It has nothing to do with the canteen or its menu.

Alternative the parser version can be return as X-OpenMensa-ParserVersion HTTP-Header. If both are provided, the value from the XML has precedence.

The version itself is a normal string that must not exceed 63 characters. OpenMensa does only check whether two versions are the same. There is relation derived from the versions. You are free to choose your matching version format.

<canteen>

This tag groups all data for one canteen. Currently only one canteen per feed is supported. Your feed must contain exactly one canteen tag. So to serve multiple canteens you need multiple feeds.

<day>

Main part for the canteen are the day element. They need to have a date attribute formatting the date of this day in the YYYY-MM-DD format.

There must only one day element per date. It is not required to provide tags for every day of a range. But be aware that OpenMensa does not process tags with past dates.

Closed days

It is possible to explicit express that the canteen is (completely) closed on a given day. Add a empty closed tag as child.

<category>

For each day the meals needs to be grouped by category. Each category tag needs to have a name attribute. The name is (only) displayed to the user and should be descriptive. But the categories only group the individual meals.

Again a name can only used once a day, but is is normal to use the same or at least similar category names for each day.

Common grouping is based on some product line or desk.

A category is only allowed if no closed tag was provided - but then it is required to have at least one category. Each category needs to have at least on meal.

<meal>

The meal element describes a meal or an individual purchasable entity that is available that the given day. A individual purchasable entry may be a side order.

<name>

The important and the only required subelement is the name part. It should be a complete description of the meal. The name must not exceed 250 characters.The name of a meal, e.g. “Rinderhacksteak mit Kartoffeln”, shouldn’t be more than a couple of words or a sentence in maximum.

<notes>

Additional text may go into several notes: A note often resembles a properties of the associated meal like the ingredients used or some important annotations.

There is (currently) not restrictions on how the notes should look like or what are common notes. If you have a good proposal talk to us.

<price>

For the meal the price can be expressed via (optional) price elements

Because different prices may apply to different groups of people and we want to show, for which group we introduced several roles:

  • pupils
  • students
  • employees (of your organization
  • others (people that do not belong to your organization or to any other group listed here).

Please omit price for roles that are not applicable or the some as others.

Meta data (since version 2.1)

It is possible to provide a special meta data feed. This meta data are used to check whether the canteen meta data are still to-up-date (in case these data can be parsed/automatically received).

The meta data are optional, they can be embedded within normal (menu) feeds, but they will be ignored on feed URLs. On the other hand any returned day/menu data for a meta data URL will also skipped.

You must ensure that the elements within the canteen are order like: name, address, city, phone, email, location, availability, times, feed, day!

If a meta data URL is provided, it is only required at at least on feed attribute is provided.

Example

Before any further discussion, this is a (complete) example:

<?xml version="1.0" encoding="UTF-8"?>
<openmensa version="2.1"
           xmlns="http://openmensa.org/open-mensa-v2"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://openmensa.org/open-mensa-v2 http://openmensa.org/open-mensa-v2.xsd">
  <version>5.04-4</version>
  <canteen>
    <name>Mensa Griebnitzsee</name>
    <address>August-Bebel-Str. 89, 14482 Potsdam</address>
    <city>Potsdam</city>
    <phone>(0331) 977 3749/3748</phone>
    <location latitude="52.3935353446923" longitude="13.1278145313263" />
    <availability>public</availability>
    <times type="opening">
      <monday open="11:00-14:00" />
      <tuesday open="11:00-14:00" />
      <wednesday open="11:00-14:00" />
      <thursday open="11:00-14:00" />
      <friday open="11:00-14:00" />
      <saturday open="11:00-13:30" />
      <sunday closed="true" />
    </times>
    <feed name="today" priority="0">
      <!-- cron like schedule information -->
      <schedule dayOfMonth="*" dayOfWeek="*" hour="8-14" retry="30 1" />
      <url>http://kaifabian.de/om/potsdam/griebnitzsee.xml?today</url>
      <source>http://www.studentenwerk-potsdam.de/mensa-griebnitzsee.html</source>
    </feed>
    <feed name="full" priority="1">
      <schedule dayOfMonth="*" dayOfWeek="1" hour="8" retry="60 5 1440" />
      <url>http://kaifabian.de/om/potsdam/griebnitzsee.xml</url>
      <source>http://www.studentenwerk-potsdam.de/speiseplan/</source>
    </feed>
  </canteen>
</openmensa>

<feed>

A feed is basically only a URL. It is expected that OpenMensa gets a valid feed when requesting this URL.

It is possible to define multiple feeds, because there may be menus that change often (e.g. the menu for the current day) and other that not. In additional if it parsing of one aspect fails, the other data should be served normally.

It is required that each feed element contains one unique name attribute. This name is only used by OpenMensa to match the given feed to previously saved feed data. But we recommend to choose descriptive names.

The optional priority attribute defines override rules between different feeds for a canteen. All feeds have per default the priority 0. A feed can update/remove a meal if the priority is same or greater than the priority of the feed that created the menu. A example usage: use priority 0 for the full feed, but use 10 for the today feed - today data have priority and can not be overridden by the normal feed.

<url>

The url element defines which page OpenMensa should request.

<schedule>

The feed has a schedule element, that specify when this URL should be fetched.

The attributes dayOfMonth, dayOfWeek, month, hour and minute describes each a patter for the given unit. The feed is accessed if the current time matches ALL these patterns. It may take some minutes until the feed is fetched depending on the work load.

The schedule behaviour and format is equal to crontab.

Each pattern may be a comma separated list of individual numbers or ranges like 1,3-5. Range are inclusive.

The special range * means all possible values. A range can be followed by a /<number> to specify to only match the nth value within the range. 0-23/2 matches 0,2,4,6,8,10,12,14,16,18,20,22.

Only the hour attribute is required, dayOfMonth, dayOfWeek and month default to *, minute to 0.

dayOfMonth starts with 1, dayOfWeek with 0 meaning Sunday (1 Monday …).

The optional retry attribute defines how to handle errors. Without this attribute OpenMensa does not retry to fetch the feed on errors.

The value must be a white-space separated list of positive numbers.

The odd positioned one define an interval in minutes, the even positioned the maximal number of retried for this interval. If the last retry limit is omitted, OpenMensa retries until the next regular time.

An example: 30 3 means retry maximal 3 time every half hour. 45 5 1440 means repeat first maximal 5 time every 45 minutes, if the feed fails still retry only once a day.

If the schedule element is omitted, the feed can only be used for manual fetching. OpenMensa has no implicit scheduling for feeds.

<source>

You can provide a single URL, from that the data are (mostly) received. So in case of an error or a question, the user can be redirected to this page.

Canteen meta data

Each canteen attribute that can be edited on OpenMensa can also be provided via the feed. Changes via the feed are NOT used directly, but must be confirmed by one canteen administration. The author is informed about the changes via an email.

The supported meta data have each its one tag, the following tags are supported:

  • name: the canteen name
  • address: the (postal) address. We do not require any special format. But the form street nr, zip city is common. If no geo coordinate for the canteen is provided the address is mapped to a point.
  • city: the user relevant city of this canteen. This does not need to be the postal city. The value is e.g. used to search canteens or group them.
  • email / phone: an email address respectively the phone number to contact the canteen. We do not ensure a specific format: the main purpose is that is understandable for humans, but we highly recommend following the E.123 standard.
  • location: the geo coordinates can be passed an latitude and a longitude attribute. Each attribute needs to be a float value. The tag must not contain any content.
  • availability: indicate whether the canteen can be used by everyone (public) or not (restricted)
  • opening times: see next section

Opening times

Opening types are defined via a times tag. It must have a type attribute with the value opening. We may later support other time ranges like meal serving times.

The times tag should have 7 open child elements (one per week day). If tags are omitted OpenMensa assumes that is was not possible to get a information for this particular day. The elements name are the English weekday name: monday, tuesday, wednesday, thursday, friday, saturday, sunday. You must ensure a correct ordering.

Set the closed attribute to true indicate that the canteen has not open at all. Use a open attribute of HH:mm-HH:mm to specify that the canteen has open within the given time interval. Please contact OpenMensa if you need to specify due intervals / express a pause. closed and open attribute must not used both!

Remember special closed days can be expressed via the closed tag of days. Support of special opening times is currently not planed. Please contact OpenMensa if you have such a use case.