Skip to content

Schema & Semantics

Entries in a 📖StadtKatalog instance are a complex data structures that have been serialized as JSON documents. We use the JSON representation to describe each entry in all of its details. All entries inside an instance validate against the same JSON schema.

In the following sections are valid for the Version 1 schema. This schema is still public beta and might change in minor details. After reaching a stable release, any updates to the semantics will require an update to the schema version number.

Identifiers

An entry's identifier is an unique ID always represented as a string. They are used to link between different entries, e.g. for the insideOf relationship. The identifier is not part of the entry's data object.

Entry data fields

Each entry in a 📖StadtKatalog instance has the following fields:

  • name - The name of the entry, max. 255 characters.
  • description – A description for the entry, max. 600 characters.
  • keywords – An array of 0 to 100 keywords. A keyword can be a synonym name, or an alternative spelling for the name, or an keyword for better search retrieval rates. Each keyword can be 255 characters long.
  • label – A short label of the entry to be used as button text or other UI-like elements, max. 20 characters.
  • tags – An array of string tags to categorize, mark, or add extra semantic information to an entry. Users can only select from the pre-defined tag list. Though, crawlers and automated imports may add additional machine tags on their own.
  • insideOf – The unique ID of an existing entry where this one is contained in, or null otherwise.
  • hours – Opening hours as object with time frames, or an empty object, if unknown.
  • hoursRemark – Additional remarks to the opening hours.
  • latitude – The north-south geographic position.
  • longitude – The east–west geographic position.
  • address – The address line typically including a street name, and a house number, or similar information.
  • postalCode – The postal code of the address, if available.
  • city – The city of the entry, if available.
  • countryCode – The ISO 3166-1 alpha-2 code for the address' country.
  • website – A full URL to the website, must start with http:// or https://.
  • email – An e-mail address as general contact.
  • emailHidden – If true, the provided e-mail should not be visible in exports.
  • phone – Phone contact number.
  • twitter – Twitter handle without the leading @.
  • facebook – Facebook Page ID or name.
  • instagram – Instagram account name.
  • foursquare – The venue id of the location on Foursquare / Swarm.
  • uid – European VAT number, if available.
  • zvr – Austrian Vereinsregister number, if available.
  • promotions – Deprecated. Array of promotions for the given entry.
  • validUntil – A ISO 8601 compliant date or date time string in UTC until which the entry is valid and should be available via the public API. Format must be YYYY-MM-DD'T'HH:mm:ss.sssZ.

Tags

Tags are a powerful feature of 📖StadtKatalog. Due their flat and flexible nature, they require conventions to be used in the most effective way. The complexity introduced by conventions should be hidden from administrators and editors by choosing simple, useable, and understandable UI-elements.

Assigning tags enables users, crawlers, and automatic update scripts to attach additional pieces of information to an entry. Tags can be used to aid classification and categorization, mark ownership, attach external identifiers and links, note boundaries, and encode information used by third-parties. Each tag has a limit of 100 characters and each entry can hold up to 100 tags. Two different types of tags are possible:

  • User tags can be assigned by administrators and editors. They are presented in the user’s interface as dropdown list and are pre-defined for the whole 📖StadtKatalog instance. The Open Data API provides a list of all user tags.
  • Machine tags can be assigned only via direct API calls, or by update scripts. They are never selectable in the admin interface.

Tags are case insensitive.

Categorization using tags

To categorize entries into multi-level categories, by convention the " :: " string is used as separator. Any tag containing " :: " is called categorization tag. This convention allows to create deep hierarchies and is flexible for future extensions to the taxonomie.

Composition of a categorization tag

namespace :: level-1 :: level-2 :: level-3 :: ... :: level-n

Each categorization tag starts with a namespace. This allows multiple categorization systems working in the same set of tags. Then at least one category has to follow as top-level category. The number of subsequent levels is only limited by the maximum length of 100 characters per tag.

Reserved category namespaces

  • 3420 – Categories for aspern Seestadt and their local Stadtteilplan.

Significance of Order

Tags are stored in an array, so they are an ordered collection. The order of tags expresses a prioritization. Earlier tags with a low array-index are more significant than later ones. This can be used to choose the most significant tag from equivalent tags, e.g. the main category of an entry.

Example for aspern Seestadt

In aspern Seestadt 3420-prefixed tags are used to apply categorization to each local entry. An entry might have the following tags:

[
  "vienna :: student dormitory",
  "3420 :: wohnen + unterkünfte",
  "3420 :: nachbarschaft + soziales",
  "3420 :: wohnen + unterkünfte :: temporäres wohnen",
  "osm:id=8755703066",
  "osm:dataType=node",
  "osm:amenity=dormitory",
  "icon :: dormitory"
]

The 3420 :: wohnen + unterkünfte is more relevant than 3420 :: nachbarschaft + soziales. So applications using 3420 ::-prefixed tags may present 3420 :: wohnen + unterkünfte as the main category for an entry, since its prior position to all other 3420 :: tags. Expressed in JavaScript:

function getMainCategory(tags) {
    // step 1: only get top-level categories
    const aspernTopLevelTags = tags.filter(tag => {
        return tag.startsWith("3420 ::") && tag.split(" :: ").length === 2;
    });

    // step 2: return the first top-level entry, or null
    return aspernTopLevelTags.length > 0 ? aspernTopLevelTags[0] : null;
}

Common machine tags

OpenStreetMap (OSM)

osm-prefixed tags are machine tags to link an entry to OpenStreetMap. This can be used for automatic updates and synchronizations by crawlers.

Icon (Deprecated)

icon ::-prefixed tags may be used to choose an expressive icon for a map marker. In the future, OpenStreetMap-based machine tags should be used to determine an icon for entries.

Known issues

  • The uid field should be renamed to vat in future versions.
  • The API should provide a method to retrieve all used tags in the current instance.