Basic Fields¶

Every resource MUST have the following fields:

type: a string that identifies the resource’s type within an enumeration of possible values. Non-nullable. Enumeration.
Its possible values are "agents", "events", "eventSeries", "lifts", "mediaObjects", "mountainAreas", "snowparks", "skiSlopes", and "venues".
id: a string that uniquely and persistently identifies the resource within a SERVER. Non-nullable. Non-empty. Unique.
attributes: an object containing the resource’s data that does not refer to other resources (e.g. the name of an event, the length of a slope).
relationships: an object containing the resource’s data referring to other resources (e.g. the organizers of an event, the slopes within a mountain area).

In addition, resources MAY have the following fields in certain contexts (see ???):

meta: an object containing metadata of the resource (e.g., the URL representing the resource’s data provider or a ??? string of the instant of the resource’s last update). Non-empty.

The meta object MAY NOT be present in the resource of creation and update requests when the data provider is not required by the server.
links: an object containing the links related to access related resources. Examples include, a link to the agent resources representing organizers and sponsors of an event, a link to the media object resources representing multimedia descriptions of a mountain area resource, or a link to the resource itself, also referred to as self (see ??? and ???). Non-empty.

The meta object SHALL NOT be present in the resource of creation and update requests.

In the following example, we present an event resource (i.e. a resource of type events) might be represented as follows:

{
  "type": "events",
  "id": "1",
  "meta": {
    "lastUpdate": "2019-11-05T08:15:30-05:00",
    ...
  },
  "attributes": {
    "name": {
      "eng": "My event",
      "ita": "Il mio evento"
    },
    "startDate": "2020-04-01T09:30:00+00:00",
    ...
  },
  "relationships": {
    "organizers": {
      "data": [
        {
          "type": "agents",
          "id": "1"
        }
      ],
      "links": {
        "related": "\https://example.com/2022-04/events/1/organizer"
      }
    },
    ...
  },
  "links": {
    "self": "\https://example.com/2022-04/events/1"
  }
}

Note that each reference to another resource within the data in the relationships object consists only of a type and an id. The relationships object SHALL NOT contain the actual data of these resources, but only their references. We refer to the section Relationships Object for the mechanisms on how to access the actual referenced resource.

Each resource type defines a set of fields that must be present in each of these objects. However, a specific SERVER, when implementing the AlpineBits®, MAY include additional fields, but it MUST comply to the link:https://jsonapi.org/format/1.0/JSON:API v1.0 standard (e.g., additional metadata fields within the meta object, or additional resource’s attributes within the attributes object). It is also RECOMMENDED that the SERVER follow the style of the AlpineBits® standard when including additional fields.

Meta Object¶

A meta object MUST contain the following fields:

lastUpdate: a ??? that identifies when a resource was last modified in the SERVER. If no modifications were made after the resource’s creation, the value in this field will be the creation date. Nullable.
dataProvider: a ??? that identifies the organization responsible for provide the resource’s data to the SERVER. The data provider field is intended to offer basic data traceability, for example, allowing users to contact providers regarding questions or issues with a resource’s data. The data provider field should not be interpreted as the data author, as these two may differ. The data provider may be the the organization providing the SERVER itself. Non-nullable.

For example, the URL "http://tourism.opendatahub.bz.it/" would be used to represent that a resource has been modified by the OpenDataHub platform.

An example of meta object is presented below:

{
  "dataProvider": "\http://tourism.opendatahub.bz.it/",
  "lastUpdate": "2019-05-01T08:15:30-05:00"
}

Attributes Object¶

The attributes object of every resource in this specification MUST contain the following fields:

abstract: a ??? object containing a short textual description of the resource. The size of an abstract in any given language SHOULD be at most 200 characters long. This field SHOULD NOT contain the same data as in the description field. Nullable.
description: a ??? object containing the complete textual description of the resource. If abstract is not null, this field MUST NOT be null.
name: a ??? object containing the complete name of the resource. This field MUST NOT be null if shortName is not null or if otherwise specified for by a particular resource type.
shortName: a ??? object containing a short name of the resource. The size of a short name in any given language SHOULD be at most 36 characters long. This field SHOULD NOT contain the same data as in the name field. Nullable.
url: a ??? string or a multilingual url object containing language-specific ??? strings. Nullable if not otherwise specified.

An example of a URL string:

"\https://www.alpinebits.org/events/1"

An example of a multilingual URL object:

{
  "deu": "\https://www.alpinebits.org/de/events/1",
  "eng": "\https://www.alpinebits.org/en/events/1",
  "ita": "\https://www.alpinebits.org/it/events/1"
}

The following object exemplifies the use of the basic attributes defined above for an event resource:

{
  "type": "events",
  "id": "1",
  "meta": { ... },
  "attributes": {
    "abstract": {
      "eng": "An event for those who want to implement AlpineBits at their companies.",
      "ita": "Un evento per coloro che vogliono implementare AlpineBits nelle loro aziende."
    },
    "description": {
      "eng": "A 1-day workshop in which we present and explain the standard, give implementation suggestions...",
      "ita": "Un workshop da 1 giorno in cui presentiamo e spieghiamo lo standard, facciamo suggerimenti di implementazione..."
    },
    "name": {
      "eng": "AlpineBits DestinationData workshop for newcomers",
      "ita": "AlpineBits DestinationData workshop per i nuovi membri"
    },
    "shortName": {
      "eng": "DestinationData Workshop",
      "ita": "DestinationData Workshop"
    },
    "url": "\https://www.alpinebits.org/events/1"
    ...
  },
  "relationships": { ... },
  "links": { ... }
}

The object below exemplifies an event which only has a name in English and no short name:

{
  "type": "events",
  "id": "1",
  "meta": { ... },
  "attributes": {
    "name": {
      "eng": "AlpineBits DestinationData workshop for newcomers."
    },
    "shortName": null,
    ...
  },
  "relationships": { ... },
  "links": { ... }
}

Relationships Object¶

The relationships object contains reference objects to one or many resources in every field allowing for resources to be connected through domain relationship in a modular way (see link:https://jsonapi.org/format/1.0/#document-resource-object-relationshipsRelationship in JSON:API v1.0). Every relationship (i.e., relationship field) within the relationships object MUST contain either a reference object or null. Every resource type MUST define the relationships within the relationships object as either Reference to One objects or Reference to Many objects depending on the semantic of the relationship.

Reference to One¶

A reference object to one resource MUST contain the following fields:

data: an object containing the type string and the id string of the referred resource.
links: an object containing the related field with a string representing the endpoint on which the referred resource is available.
In case the resource does not support the endpoint of the related resource, the presence of the field relates is OPTIONAL.

For example, the ??? resource type defines a relationship licenseHolder (see ???) to the agent resource representing the media object’s owner:

{
  "type": "mediaObjects",
  "id": "1",
  "meta": { ... },
  "attributes": { ... },
  "relationships": {
    "licenseHolder": {
      "data": {
        "type": "agents",
        "id": "1"
      },
      "links": {
        "related": "\https://example.com/2022-04/mediaObjects/1/licenseHolder"
      }
    }
  },
  "links": { ... }
}

In case a resource has no related resource, the reference can be set to null according to the requirements defined in its resource type. For example, a media object resource that does not refer to an agent resource as its license holder can be presented as follows:

{
  "type": "mediaObjects",
  "id": "1",
  "meta": { ... },
  "attributes": { ... },
  "relationships": {
    "licenseHolder": null
  },
  "links": { ... }
}

Reference to Many¶

A reference object to many resources MUST contain the following fields:

"data": an array of objects containing the type string and the id string of each referred resource.
"links": an object containing the related field with a string representing the endpoint on which the referred resources are available.
In case the resource does not support the endpoint of the related resource, the presence of the field relates is OPTIONAL.

For example, the event resource type defines a relationship organizers (see ???) to the agent resources representing the event’s owner:

{
  "type": "events",
  "id": "1",
  "meta": { ... },
  "attributes": { ... },
  "relationships": {
    "organizers": {
      "data": [
        {
          "type": "agents",
          "id": "4"
        },
        {
          "type": "agents",
          "id": "1"
        },
        {
          "type": "agents",
          "id": "9"
        }
      ],
      "links": {
        "related": "\https://example.com/2022-04/mediaObjects/1/licenseHolder"
      }
    },
    ...
  },
  "links": { ... }
}

In case a resource has no related resource, the reference can be set to null according to the requirements defined in its resource type. For example, a media object resource that does not refer to an agent resource as its license holder can be presented as follows:

{
  "type": "events",
  "id": "1",
  "meta": { ... },
  "attributes": { ... },
  "relationships": {
    "organizers": null,
    ...
  },
  "links": { ... }
}

Every resource, with the exception of instances of categories, features, and media objects, MUST contain the Reference to Many bellow within the relationships object. Of these, categories and features MUST contain the Reference to Many multimediaDescriptions, and media objects MUST contain the Reference to Many categories

categories: a Reference to Many category resources identifying the categories instantiated by the resource. The values proposed by the standard for each resource type are listed in each resource section. Non-nullable. Non-empty.

multimediaDescriptions: a Reference to Many media object resources that illustrates a resource. Media objects be images, videos, audio, data documents (e.g. csv, json), textual documents (e.g. doc, pdf), html documents, and so on.

Here is an example of how to use the multimediaDescriptions relationship:

{
  "type": "events",
  "id": "1",
  "attributes": { ... },
  "relationships": {
    "categories": {
      "data": [
        {
          "type": "categories",
          "id": "alpinebits:inPersonEvent"
        }
      ],
      "links": {
        "related": "\https://example.com/2022-04/events/1/categories"
      }
    },
    "multimediaDescriptions": {
      "data": [
        {
          "type": "mediaObjects",
          "id": "1"
        },
        {
          "type": "mediaObjects",
          "id": "2"
        },
        {
          "type": "mediaObjects",
          "id": "3"
        },
      ],
      "links": {
        "related": "\https://example.com/2022-04/events/1/multimediaDescriptions"
      }
    }
    ...
  },
  "links": { ... }
}

Links Object¶

The links object of instances of every resource type MUST contain the following fields:

self: a string representing the endpoint on which the container resource is available.
For example, an event resource may be presented as follows:

{
  "type": "events",
  "id": "1",
  "attributes": { ... },
  "relationships": { ... },
  "links": {
    "self": "\https://example.com/2022-04/events/1"
  }
}