API docs by Redocly

ORIF - Open Repertoire Interchange Format (v2)

Download OpenAPI specification:Download

E-mail: datenraum@buehnenverein.de

Overview

The Open Repertoire Interchange Format (ORIF) enables theaters to share comprehensive information about their productions and events in a machine-readable, standardized format. This specification provides a structured approach to exchanging theatrical repertoire data across different institutions and platforms. It is intended as a reference for both, users that want to provide their repertoire data in a machine-readable format (i.e. theaters) and users who want to work with the data from different theaters (e.g. event platforms, archives, researchers, etc.).

For theaters

Implementing the Open Repertoire Interchange Format (ORIF) enables your theater to automatically distribute your performance schedule to multiple platforms through a standardized export interface. I.e. in addition to presenting your schedule in a human-readable fashion on your website, you will also provide it in a machine-readable format through an API endpoint. External platforms, archives, and event aggregators can then call this API endpoint and access your current repertoire in an automated fashion, without the need for human interaction. The data returned through this API endpoint should follow the ORIF specification to ensure it can be properly processed by these external data consumers.

As an implementer, your primary task is to create an endpoint on your website that returns your current performance schedule as JSON data in the ORIF format. This can typically be integrated with your existing Content Management System, ticketing platform, or custom website backend.

Both required and recommended fields are specified in the documentation. While only required fields are necessary for basic compatibility, implementing the recommended fields provides a richer data set that benefits both your theater and downstream consumers. This leads to better presentation of your productions on third-party platforms and more comprehensive data collection for cultural research and archiving purposes.

For reference, we provide an example dataset that includes all recommended fields to help guide your implementation. We also provide two tools to validate and view the data returned from your API endpoint.

API endpoint naming

  • You should provide a single endpoint returning repertoire data in the ORIF specification format
  • the endpoint name can vary from what's mentioned here, but everything else (i.e. field names) should follow the ORIF specification

Required fields are marked by a "required" tag below the field name and MUST be present in the data returned by your API endpoint, to conform to the ORIF data format: Example required field

Recommended fields are marked by a "recommended" tag in their description and SHOULD be present in the data returned by your API endpoint, especially if the information is readily available in your system: Example required field Including these recommended fields in your data will make your repertoire data much more useful for consumers of your API endpoint and will lead to better representation of your events, e.g. in online event calendars.

All other fields are optional, i.e. they can be omitted from your data. However, including them will still provide value, so you should add them, if the information is already available in your system.

Example dataset

To guide your implementation, we provide an example dataset, with one production and one event, that contains all required and recommended fields.

Additional tools

  • Validator: Use this tool to test whether your implementation matches the API specification
  • Data Viewer: Use this tool to display information from the API in a more human-friendly way. This can be helpful to quality control the data that is returned by your API implementation.

Image requirements

For each production, you can provide a list of (promotional) photos in your data. These photos should be provided as links (through the contentUrl field) and should have a maximum width and height of 1500px.

Recommendations for Users

  • When using an ORIF endpoint to import data, you should implement robust change tracking using the identifier and dateModified fields (when available)

Note on multi-language support

Some of the fields (e.g. name and description on a production), can either contain a simple string or an InternationalizedString object. This object can be used to include the same text in different translations.

Background

ORIF emerged from the need to standardize theatrical repertoire data exchange as a precursor to the Datenraum Kultur. By building upon schema.org (in particular, the existing types CreativeWork and Event), the format ensures:

  • Wide compatibility with existing web technologies
  • Flexibility to represent diverse theatrical productions
  • Easy integration with cultural data platforms and event calendars

events

Endpoint providing public information about upcoming events

Provides public information about events

Responses

Response Schema: application/ld+json
@context
required
string
Value: "https://schema.org"
version
required
string
Value: "v2"

The API version that is being used. MUST be the string "v2" for now.

required
object (Organization)
@type
required
string
Value: "Organization"
identifier
string

A unique ID that can be used to identify this organization. This could be an internal database ID, for example.

name
required
string

The organization's name

object (PostalAddress)

The address of e.g. an organization or event location.

@type
required
string
Value: "PostalAddress"
postalCode
required
string

The postal code.

streetAddress
string

[recommended] The street address.

addressLocality
required
string

The locality in which the street address is, i.e. the city.

addressCountry
string

[recommended] The country of this address.

logo
string <uri>

A link to the organization's logo.

required
Array of objects (Production)

A list of all current productions in the repertoire.

Array
@type
required
string (CommonCreativeWorkType)
Enum: "CreativeWork" "Play"
identifier
required
string

The unique ID of this production. This could be an internal database ID, for example.

dateModified
string <date-time>

Timestamp of when this production entry was last modified

required
StringType (string) or InternationalizedString (object)

The production's title.

StringType (string) or InternationalizedString (object)

The production's optional subtitle.

StringType (string) or InternationalizedString (object)

[recommended] A text describing the production.

StringType (string) or InternationalizedString (object)

A short abstract or teaser text describing the production.

Array of OriginalWork (object) or MusicComposition (object) (Work)

List of original works that this production is based on. E.g. this could describe the original dramatic text that was used as the basis of a theater production.

Array of OriginalWork (object) or MusicComposition (object) (Work)

List of original works that are performed in this production, e.g. the music compositions that are performed in a classical concert.

required
Array of objects (Event)

A list of events at which this production will be performed.

genre
Array of strings
Items Enum: "audiowalk" "ballett" "comedy" "digitaltheater" "figurentheater" "game-theater" "improtheater" "inklusives-theater" "installation" "kabarett" "kammerkonzert" "konzert" "lecture-performance" "lesung" "live-hoerspiel" "musical" "musiktheater" "objekttheater" "oper" "operette" "performance" "physical-theatre" "postmigrantisches-theater" "puppentheater" "sinfoniekonzert" "sprechtheater" "szenische-lesung" "szenisches-konzert" "tanz" "theater-im-oeffentlichen-raum" "workshop" "zeitgenoessischer-tanz"

[recommended] The genre of this production. Must use one of the pre-defined values.

productionType
string
Enum: "WorldPremiere" "FirstPerformance" "LanguagePremiere" "LocalPremiere" "CountryPremiere" "Revival"

A value that indicates special characteristics of this production:

  • WorldPremiere: This is the first time that this creative work is publicly performed anywhere in the world.
  • FirstPerformance: This is the first time that this creative work is publicly performed in a specific context. E.g. it could be a language premiere, country premiere, or local premiere.
  • Revival: A new production (restaging) of an existing play or similar creative work.
  • LanguagePremiere:The first performance of a play or similar creative work in a particular language.
  • LocalPremiere: The first performance of a play or similar creative work in a particular local area.
  • CountryPremiere: The first performance of a play or similar creative work in a particular country.
Array of objects (ImageObject)

[recommended] List of photos of the production. Please provide photos that have a maximum width and height of 1500px.

Array of objects (VideoObject)

List of video (trailers) of the production

accessibilityHazard
Array of strings
Items Enum: "none" "unknown" "flashingHazard" "motionSimulationHazard" "soundHazard" "noFlashingHazard" "noMotionSimulationHazard" "noSoundHazard" "unknownFlashingHazard" "unknownMotionSimulationHazard" "unknownSoundHazard"

A list of characteristics of the production that may be physiologically dangerous to some users.

accessibilitySummary
string

A human-readable summary of specific accessibility features or deficiencies of the production.

Array of StringType (string) or InternationalizedString (object)

A list of content warnings, i.e. warnings about contents of this production that may be distressing or triggering to some people.

inLanguage
Array of strings

Primary language(s) of this production. Should contain BCP 47 Language Tags.

object (Audience)

Object describing the intended target audience of this production.

Array of objects (CreatorRole)

[recommended] List of people and organizations that contributed to the creation of this production, e.g. directors, stage designers, musical directors, etc. If this production is a collaboration with another organization, e.g. another theater or orchestra, this organization should also be included in this field.

If multiple people perform the same role/function (e.g. there is multiple directors), each person should get their own entry in the creator array.

StringType (string) or InternationalizedString (object)

Text that can be used to credit persons and/or organizations that are associated with this production. This field can be used to include a text snippet on, e.g., funding organizations that needs to be included on platforms advertising the production.

Array of Person (object) or Organization (object) (Agent)

A list of organization's that support this production through some kind of financial contribution.

Array of Person (object) or Organization (object) (Agent)

A list of organization's that support this production through a pledge, promise, or financial contribution.

Response samples

Content type
application/ld+json
{
  • "@context": "https://schema.org",
  • "version": "v2",
  • "organization": {
    • "@type": "Organization",
    • "identifier": "836",
    • "name": "Staatstheater Augsburg",
    • "address": {
      },
    • "logo": "http://example.com"
    },
  • "productions": [
    • {
      }
    ]
}