Events
A resource that implements the concept of Event defined in the AlpineBits® DestinationData Ontology.
A JSON object representing such a resource MUST contain the following fields:
-
type: the constant"events"that identifies the resource as being of the type event. -
id: a string that uniquely and persistently identifies the event within a SERVER. See the definition in basic-resource-schema.adoc#anchor-attributes. -
attributes: an object containing the attributes of the event. -
relationships: an object containing the relationships of the event to other resources. -
links: an object containing the links related to the event.
An event resource is structured as follows:
{
"type": "events",
"id": "1",
"meta": { ... },
"attributes": { ... },
"relationships": { ... },
"links": { ... }
}1. Meta
See definition of the meta object in basic-resource-schema.adoc#anchor-metadata.
2. Attributes
The attributes object of an event resource MUST contain the following fields:
-
abstract: a datatypes.adoc#anchor-text object containing a brief description for the event. Nullable. See definition in basic-resource-schema.adoc#anchor-attributes. -
capacity: an integer representing the total number of individuals that can attend the event. Nullable. Positive integer. -
categories: an array of datatypes.adoc#anchor-type strings identifying the types instantiated by the event. Nullable. The standard recommends the use of event types defined in Schema.org, which are identified by theschemanamespace:"schema/BusinessEvent","schema/ChildrensEvent","schema/ComedyEvent","schema/CourseInstance","schema/DanceEvent","schema/DeliveryEvent","schema/EducationEvent","schema/EventSeries","schema/ExhibitionEvent","schema/Festival","schema/FoodEvent","schema/Hackathon","schema/LiteraryEvent","schema/MusicEvent","schema/PublicationEvent","schema/SaleEvent","schema/ScreeningEvent","schema/SocialEvent","schema/SportsEvent","schema/TheaterEvent","schema/VisualArtsEvent" -
description: a datatypes.adoc#anchor-text object containing a description of the event. Nullable. Conditional Assignment. See definition in basic-resource-schema.adoc#anchor-attributes. -
endDate: a string, formatted as datatypes.adoc#anchor-date or datatypes.adoc#anchor-datetime, representing when the event is supposed to end. This field can only benullifstartDateis defined. -
name: a datatypes.adoc#anchor-text object containing the complete name of the event. Non-nullable. Conditional Assignment. See definition in basic-resource-schema.adoc#anchor-attributes. -
shortName: a datatypes.adoc#anchor-text object containing a short name of the event. Nullable. See definition in basic-resource-schema.adoc#anchor-attributes. -
startDate: a string, formatted as datatypes.adoc#anchor-date or datatypes.adoc#anchor-datetime, representing when the event is supposed to start. This field can only benullifendDateis defined. -
status: a string representing the current status of the event. Nullable. The possible values for this field are the following enumerated values:-
published: the event has been published. It may or may not have happened. -
canceled: the event has been canceled. Events can only be canceled before they have started.
-
-
url: a datatypes.adoc#anchor-url describing the event, such as a website or a Wikipedia page. Nullable.
A summary of the attributes is presented in the table below:
| Field | Type | Constraints |
|---|---|---|
abstract |
Nullable |
|
capacity |
integer |
Nullable, Greater than Zero |
categories |
Array of datatypes.adoc#anchor-type |
Nullable, Non-empty |
description |
Nullable |
|
endDate |
datatypes.adoc#anchor-date or datatypes.adoc#anchor-datetime |
Nullable, Conditional Assignment |
name |
Non-Nullable |
|
shortName |
Nullable |
|
startDate |
datatypes.adoc#anchor-date or datatypes.adoc#anchor-datetime |
Nullable, Conditional Assignment |
status |
string |
Nullable, Enumeration |
url |
Nullable |
3. Relationships
The relationships object of an event resource MUST contain the following fields:
-
contributors: an basic-resource-schema.adoc#anchor-referencetomany agent resources (see Agents), which identifies the agents expected to participate in the event, such as a speaker who will give a talk or a musician who will perform at a concert. Contributors do not include those attending the event. Nullable. -
multimediaDescriptions: an basic-resource-schema.adoc#anchor-referencetomany media object resources (see Media Objects) that illustrate the trail. See Section basic-resource-schema.adoc#anchor-multimediadescriptions. Nullable. Non-empty. -
organizers: an basic-resource-schema.adoc#anchor-referencetomany agent resources (see Agents) identifying the persons or organizations responsible for organizing the event. Non-nullable. -
publisher: the Agents who originally provided the data about the event. The publisher is not the organization who manages the system where the data was originally inserted, but the organization actually provided the data. Non-nullable. -
series: basic-resource-schema.adoc#anchor-referencetoone object to an Event Series of which the event is an edition of. For instance, the Südtirol Jazz Festival 2020 is an edition of the Südtirol Jazz Festival. Nullable. -
sponsors: an basic-resource-schema.adoc#anchor-referencetomany agent resources (see Agents) identifying the persons or organizations who are sponsoring the event. Nullable. -
subEvents: an basic-resource-schema.adoc#anchor-referencetomany event resources (see Events) identifying the parts of the event. For instance, a festival may consist of several concerts and a conference may consist of several presentations and a keynote. Nullable.There SHALL NOT be a circular composition of events. For instance, if A is a sub-event of B, and B is a sub-event of C, C SHALL NOT be a sub-event of A.
Note that sub-events are not restricted to the temporal boundaries of their parent events. For instance, a conference that starts on 15/03/2020 and ends on 20/03/2020 may have, as a sub-event, a pre-conference meeting that is scheduled for the 14/03/2020.
-
venues: an basic-resource-schema.adoc#anchor-referencetomany venue resources (see Venues) identifying where the event will happen. Non-nullable.
A summary of the relationships is presented in the table below:
| Field | Type | Constraints |
|---|---|---|
contributors |
basic-resource-schema.adoc#anchor-referencetomany object to Agents |
Nullable, Non-empty |
multimediaDescriptions |
basic-resource-schema.adoc#anchor-referencetomany object to Media Objects |
Nullable, Non-empty |
organizers |
basic-resource-schema.adoc#anchor-referencetomany object to Agents |
Non-Nullable, Non-empty |
publisher |
basic-resource-schema.adoc#anchor-referencetoone object to an Agents |
Non-Nullable |
series |
basic-resource-schema.adoc#anchor-referencetoone object to an Event Series |
Nullable |
sponsors |
basic-resource-schema.adoc#anchor-referencetomany object to Agents |
Nullable, Non-empty |
subEvents |
basic-resource-schema.adoc#anchor-referencetomany object to Events |
Nullable, Non-empty |
venues |
basic-resource-schema.adoc#anchor-referencetomany object to Venues |
Non-Nullable, Non-empty |
4. Links
See definition of the links object in basic-resource-schema.adoc#anchor-links.
5. Endpoints
The following endpoints in this API specification return event resources:
-
https://example.com /1.0/events: returns a collection of events. -
https://example.com /1.0/events/:id: returns the event identified by the:idparameter. -
https://example.com /1.0/events/:id/subEvents: returns a collection of events that are part of the event. -
https://example.com /1.0/eventSeries/:id/editions: returns a collection of events that are editions of the event series.
6. Examples
The following example contains the minimal information required for an event resource:
{
"type": "events",
"id": "1",
"meta": {
"dataProvider": null,
"lastUpdate": null
},
"attributes": {
"name": {
"eng": "Südtirol Jazz Festival 2018"
},
"shortName": null,
"description": null,
"abstract": null,
"startDate": "2018-06-29T00:00:00+00:00",
"endDate": null,
"url": null,
"categories": null,
"status": null,
"capacity": null
},
"relationships": {
"series": null,
"publisher": {
"data": {
"type": "agents",
"id": "1"
},
"links": {
"related": "http://example.com/1.0/events/1/publisher"
}
},
"organizers": {
"data": [
{
"type": "agents",
"id": "2"
}
],
"links": {
"related": "http://example.com/1.0/events/1/organizers"
}
},
"sponsors": null,
"contributors": null,
"multimediaDescriptions": null,
"venues": {
"data": [
{
"type": "venues",
"id": "1"
}
],
"links": {
"related": "http://example.com/1.0/events/1/venues"
}
},
"subEvents": null
},
"links": {
"self": "http://example.com/1.0/events/1"
}
}
|
The following example illustrates the fields defined for event resources:
{
"type": "events",
"id": "1",
"meta": {
"dataProvider": "http://example.com",
"lastUpdate": "2020-04-01T08:00:00+02:00"
},
"attributes": {
"name": {
"eng": "Südtirol Jazz Festival 2020",
"deu": "Südtirol Jazz Festival 2020",
"ita": "Südtirol Jazz Festival 2020"
},
"shortName": {
"eng": "Südtirol Jazz Festival 2020"
},
"description": {
"deu": "Beim Südtirol Jazzfestival Alto Adige wagen sich Solisten und Ensembles nicht nur in schwindelerregende musikalische „Höhen“ vor, sondern besteigen, mit ihren Instrumenten im Gepäck, sogar „echte“ Berge und bespielen dabei eine atemberaubende alpine Landschaft. Das Festival selbst beschreitet oft ganz neue Wege: selbstbewusst und sich mitunter über zerklüftete Spalten herantastend, versucht es in neue Klanglandschaften vorzudringen. Mainstream und Konzertsäle sind beim Südtirol Jazzfestival Alto Adige vom Aussterben bedroht...."
},
"abstract": {
"deu": "Das Südtirol Jazzfestival Alto Adige ist ein in Südtirol stattfindendes Musikfestival für Jazz und experimentelle Musik."
},
"startDate": "2020-06-26T21:00:00+00:00",
"endDate": "2020-07-07T23:30:00+00:00",
"url": "https://www.suedtiroljazzfestival.com/",
"categories": [
"schema/MusicEvent"
],
"status": "published",
"capacity": 1000
},
"relationships": {
"series": {
"data": {
"type": "eventSeries",
"id": "1"
},
"links": {
"related": "http://example.com/1.0/events/1/eventSeries"
}
},
"publisher": {
"data": {
"type": "agents",
"id": "1"
},
"links": {
"related": "http://example.com/1.0/events/1/publisher"
}
},
"organizers": {
"data": [
{
"type": "agents",
"id": "2"
}
],
"links": {
"related": "http://example.com/1.0/events/1/organizers"
}
},
"sponsors": {
"data": [
{
"type": "agents",
"id": "3"
},
{
"type": "agents",
"id": "4"
}
],
"links": {
"related": "http://example.com/1.0/events/1/sponsors"
}
},
"contributors": {
"data": [
{
"type": "agents",
"id": "5"
}
],
"links": {
"related": "http://example.com/1.0/events/1/contributors"
}
},
"multimediaDescriptions": {
"data": [
{
"type": "mediaObjects",
"id": "1"
},
{
"type": "mediaObjects",
"id": "2"
}
],
"links": {
"related": "http://example.com/1.0/events/1/multimediaDescriptions"
}
},
"venues": {
"data": [
{
"type": "venues",
"id": "1"
}
],
"links": {
"related": "http://example.com/1.0/events/1/venues"
}
},
"subEvents": {
"data": [
{
"type": "events",
"id": "2"
},
{
"type": "events",
"id": "3"
}
],
"links": {
"related": "http://example.com/1.0/events/1/subEvents"
}
}
},
"links": {
"self": "http://example.com/1.0/events/1"
}
}
|