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", "trails", and "venues".

  • id: a string that uniquely and persistently identifies the resource within a SERVER. Non-nullable. Non-empty. Unique.

  • meta: an object containing metadata of the resource (e.g., the URL representing the resource’s data provider or a datatypes.adoc#anchor-datetime string of the instant of the resource’s last update).

  • 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 trail).

  • relationships: an object containing the resource’s data referring to other resources (e.g. the organizers of an event, the trails within a mountain area).

  • links: an object containing the links related to access related resources (e.g., 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).

For example, 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": "/api/1.0/events/1/organizer"
      }
    },
    ...
  },
  "links": {

  }
}

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® DestinationData, MAY include additional fields, but it MUST comply to the 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® DestinationData standard when including additional fields.

1. Meta Object

A meta object MUST contain the following fields:

  • lastUpdate: a datatypes.adoc#anchor-datetime 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 datatypes.adoc#anchor-url that identifies the organization responsible for the data about a resource and who can be contacted in case of questions or issues regarding it. 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"
}

2. Attributes Object

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

  • abstract: a datatypes.adoc#anchor-text 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.

  • categories: an array of datatypes.adoc#anchor-type strings identifying the types instantiated by the resource. The values proposed by the standard for each resource type are listed in each resource section.

  • description: a datatypes.adoc#anchor-text object containing the complete textual description of the resource. If abstract is not null, this field CANNOT be null.

  • shortName: a datatypes.adoc#anchor-text 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.

  • name: a datatypes.adoc#anchor-text object containing the complete name of the resource. This field CANNOT be null if shortName is not null or if otherwise specified for by a particular resource type.

  • url: a datatypes.adoc#anchor-url string or a multilingual url object containing language-specific datatypes.adoc#anchor-url 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",
    "categories": [ "schema/BusinessEvent" ]
    ...
  },
  "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": { ... }
}

3. 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 Relationship 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.

4. 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 Media Objects resource type defines a relationship copyrightOwner (see mediaobjects.adoc#anchor-mediaobjects-relationships) to the agent resource representing the media object’s owner:

{
  "type": "mediaObjects",
  "id": "1",
  "meta": { ... },
  "attributes": { ... },
  "relationships": {
    "copyrightOwner": {
      "data": {
        "type": "agents",
        "id": "1"
      },
      "links": {
        "related": "https://example.com/1.0/mediaObjects/1/copyrightOwner"
      }
    }
  },
  "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 copyright owner can be presented as follows:

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

5. 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 Events resource type defines a relationship organizers (see events.adoc#anchor-events-relationships) 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/1.0/mediaObjects/1/copyrightOwner"
      }
    },
    ...
  },
  "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 copyright owner can be presented as follows:

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

Every resource, with the exception of instances of media objects resource type, MUST contain the following Reference to Many within the relationships object:

  • multimediaDescriptions: a non-empty array of references to media objects that describe or illustrate a resource. Media objects may represent 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": {
    "multimediaDescriptions": {
      "data": [
        {
          "type": "mediaObjects",
          "id": "1"
        },
        {
          "type": "mediaObjects",
          "id": "2"
        },
        {
          "type": "mediaObjects",
          "id": "3"
        },
      ],
      "links": {
        "related": "https://example.com/1.0/events/1/multimediaDescriptions"
      }
    }
    ...
  },
  "links": { ... }
}

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/1.0/events/1"
  }
}