Categories¶

A resource that implements the concept of Category defined in the AlpineBits® Ontology.

A JSON object representing such a resource MUST contain the following fields:

type: the constant "categories" that identifies the resource as being of the type category.
id: a string that uniquely and persistently identifies the category within a SERVER. This id MUST be a human-readable string composed of a namespace, identifying the context defining the category (e.g., the data provider or the standard), and the category name, these two separated by a colon (i.e., "<namespace>:<categoryname>").

Category id strings MUST be valid against the regular expression below. Examples of categories listed in this standard include "alpinebits:person" and "alpinebits:organization", as categories of agents, and "schema:BusinessEvent" as a category of events.
```
"^([a-z]|[A-Z]|[0-9])+:([a-z]|[A-Z]|[0-9])+$"
```
attributes: an object containing the attributes of the category.
relationships: an object containing the relationships of the category to other resources.
links: an object containing the links related to the category.

Category resources are structured in the following way:

{
  "type": "categories",
  "id": "example:soccerEvent",
  "meta": { ... },
  "attributes": { ... },
  "relationships": { ... },
  "links": { ... }
}

Meta¶

See the definition of the meta object in ???.

Attributes¶

The attributes object of the agent resource MUST contain the following fields:

abstract: a ??? object containing a brief description for the category. Nullable. See the definition in ???.
description: a ??? object containing a description of the category. Nullable. Conditional Assignment. See the definition in ???.
name: a ??? object containing the complete name of the category. Different to the category’s id, the category’s name serves no identification purpose, but only as a description. Therefore, the category’s name SHOULD be a human-readable text friendly to end users. Non-nullable. Conditional Assignment. See the definition in ???.
namespace: a string containing the namespace that prefixes the category’s id. The namespace identifies the context where a category is defined. For instance, the namespace for the category "alpinebits:person", which is defined in this standard, is "alpinebits". Non-nullable. Non-empty.

A SERVER SHALL NOT use alpinebits as the namespace of a category it defines.

A SERVER SHOULD adopt a single namespace for all categories it defines.

An example of a non-standardized category is "unibz:academic", which could represent a category defined by the Free University of Bozen-Bolzano (acting as a SERVER) that classifies events that its students can attend.
resourceTypes: an array of strings containing the resource types that the category is applicable to. For example, the value of resourceTypes for the category "alpinebits:person" is [ "agents" ], since this category exclusively applies to resources with the type "agents". Non-nullable. Non-empty.
shortName: a ??? object containing a short name of the category. Nullable. See the definition in ???.
url: a ??? object or string describing the category, such as a website or a Wikipedia page. Nullable. See the definition in ???.

A summary of the attributes is presented in the table below:

Field	Type	Constraints
abstract	???	Nullable
description	???	Nullable, Conditional Assignment
name	???	Non-nullable, Conditional Assignment
namespace	???	Non-nullable, Conditional Assignment
resourceTypes	Array of string	Non-nullable, Non-empty
shortName	???	Nullable
url	???	Nullable

Relationships¶

The relationships object of the agent resource MUST contain the following fields:

children: a ??? category resources that specialize the category. Every instance of a child category is also an instance of the referring category. Every category listed as child MUST refer back to the referring category as its parent category (i.e., inverse relations). Conditional assignment. Nullable. Non-empty.

For example, if the category "example:sportsEvent" refers to the category "example:soccerEvent" as its child, every resource that instantiates "example:soccerEvent" also instantiates the category "example:sportsEvent".
multimediaDescriptions: a ??? media object resources (see ???) that are related to the category. See Section ???. Nullable. Non-empty.
parents: a ??? category resources that are specialized by the category. Every instance of the referring category is also an instance of the parent category. Every category listed as parent MUST refer back to the referring category as its child category (i.e., inverse relations). Conditional assignment. Nullable. Non-empty.

For example, if the category "example:modernArtEvent" refers to the category "example:artEvent" as its parent, every resource that instantiates "example:modernArtEvent" also instantiates the category "example:artEvent".

A summary of the relationships is presented in the table below:

Field	Type	Constraints
children	??? object to Categories	Nullable, Non-empty
multimediaDescriptions	??? object to ???	Nullable, Non-empty
parents	??? object to Categories	Nullable, Non-empty

Links¶

The links object of category resources MUST contain the following fields:

self: a string representing the endpoint on which the container resource is available. Non-nullable.
resources: a object where the key-value pairs contains URLs for retrieving resources that instantiate the category. The object MUST include key for each string in the resourceTypes attribute array, and the corresponding value in the pair is the endpoint for that resource type. Whenever supported, a filter for the category MUST be included (see example below). Non-nullable.

For example, the links object of a category resource may be presented as follows:

{
  "type": "categories",
  "id": "alpinebits:person",
  "attributes": {
    "resourceTypes": [ "agents" ],
    ...
  },
  "relationships": { ... },
  "links": {
    "self": "\https://example.com/2022-04/categories/alpinebits:person",
    "resources": {
      "agents": "\https://example.com/2022-04/agents?filter[category][any]=alpinebits:person"
    }
  }
}

Examples¶

The following example presents an object containing the minimal information required of a category resource:

{
  "type": "categories",
  "id": "example:temporarilyRestricted",
  "meta": {
    "dataProvider": null,
    "lastUpdate": null
  },
  "attributes": {
    "abstract": null,
    "description": null,
    "name": {
      "eng": "Temporarily Restricted"
    },
    "namespace": "example",
    "resourceTypes": [ "venues" ],
    "shortName": null,
    "url": null
  },
  "relationships": {
    "children": null,
    "multimediaDescriptions": null,
    "parents": null
  },
  "links": {
    "self": "https://example.com/2022-04/categories/example:temporarilyRestricted",
    "resources": {
      "venues": "https://example.com/2022-04/venues?filter[categories][any]=example:temporarilyRestricted"
    }
  }
}

asciidoc/examples/category.min.json

The following example presents an object representing a category resource:

{
  "type": "categories",
  "id": "example:soccerEvent",
  "meta": {
    "dataProvider": "https://example.com",
    "lastUpdate": "2022-04-01T08:00:00+02:00"
  },
  "attributes": {
    "abstract": {
      "ita": "Un evento sportivo legato al calcio.",
      "deu": "Ein Sportereignis, das mit Fußball zu tun hat.",
      "eng": "A sports event related to soccer."
    },
    "description": {
      "ita": "Un evento sportivo legato al calcio, per esempio una partita di calcio o un incontro con i giocatori.",
      "deu": "Ein Sportereignis mit Bezug zum Fußball, z. B. ein Fußballspiel oder ein Meet-and-Greet mit Spielern.",
      "eng": "A sports event related to soccer, for example a soccer match or a meet-and-greet with players."
    },
    "name": {
      "ita": "Evento di Calcio",
      "deu": "Fußball-Event",
      "eng": "Soccer Event"
    },
    "namespace": "example",
    "resourceTypes": [ "events" ],
    "shortName": {
      "eng": "Soccer Event"
    },
    "url": "https://en.wikipedia.org/wiki/Association_football"
  },
  "relationships": {
    "children": {
      "data": [
        {
          "type": "categories",
          "id": "example:sub19SoccerMatch"
        }
      ],
      "links": {
        "related": "https://example.com/2022-04/categories/example:soccerEvent/children"
      }
    },
    "multimediaDescriptions": {
      "data": [
        {
          "type": "mediaObjects",
          "id": "1"
        }
      ],
      "links": {
        "related": "https://example.com/2022-04/categories/example:soccerEvent/multimediaDescriptions"
      }
    },
    "parents": {
      "data": [
        {
          "type": "categories",
          "id": "schema:SportsEvent"
        }
      ],
      "links": {
        "related": "https://example.com/2022-04/categories/example:soccerEvent/parents"
      }
    }
  },
  "links": {
    "self": "https://example.com/2022-04/categories/example:soccerEvent",
    "resources": {
      "events": "https://example.com/2022-04/events?filter[categories][any]=example:soccerEvent"
    }
  }
}

asciidoc/examples/category.full.json