Features¶

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

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

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

Feature id strings MUST be valid against the regular expression below.
```
"^([a-z]|[A-Z]|[0-9])+:([a-z]|[A-Z]|[0-9])+$"
```
attributes: an object containing the attributes of the feature.
relationships: an object containing the relationships of the features to other resources.
links: an object containing the links related to the feature.

Feature resources are structured in the following way:

{
  "type": "features",
  "id": "example:snowparkRamp",
  "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 feature. Nullable. See the definition in ???.
description: a ??? object containing a description of the feature. Nullable. Conditional Assignment. See the definition in ???.
name: a ??? object containing the complete name of the feature. Differently from the feature’s id, its name serves no identification purpose, but only description. Therefore, the 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 feature’s id. The namespace identifies the context where a feature is defined. For instance, a SERVER may define the features "example:snowparkRamp" and "example:snowparkRail" under the namespace "example". Non-nullable. Non-empty.

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

A SERVER SHOULD adopt a single namespace for all features it defines.
resourceTypes: an array of strings containing the resource types that can present the feature. For example, the value of resourceTypes for the feature "example:snowparkRamp" is [ "snowpark" ]. At the moment, the standard only accounts for features of snowparks. Non-nullable. Non-empty.
shortName: a ??? object containing a short name of the feature. Nullable. See the definition in ???.
url: a ??? object or string describing the feature, 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 ??? feature resources that specialize the feature. Every resource presenting a child feature also must also present the referring feature. Every feature listed as child MUST refer back to the referring feature as its parent feature (i.e., inverse relations). Conditional assignment. Nullable. Non-empty.

For example, if the feature "example:snowparkRamp" refers to the feature "example:snowboardingRamp" as its child, every resource that presents "example:snowboardingRamp" also presents the feature "example:snowparkRamp".
multimediaDescriptions: a ??? media object resources (see ???) that are related to the feature. See Section ???. Nullable. Non-empty.
parents: a ??? feature resources that are specialized by the feature. Every resource presenting the referring feature must also present the parent feature. Every feature listed as parent MUST refer back to the referring feature as its child feature (i.e., inverse relations). Conditional assignment. Nullable. Non-empty.

For example, if the feature "example:snowboardingJib" refers to the feature "example:snowparkRail" as its parent, every resource that presents "example:snowboardingJib" also presents the feature "example:snowparkRail".

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

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

Links¶

The links object of feature 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 present the feature. 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 feature MUST be included (see example below). Non-nullable.

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

{
  "type": "features",
  "id": "example:snowparkRail",
  "attributes": {
    "resourceTypes": [ "snowparks" ],
    ...
  },
  "relationships": { ... },
  "links": {
    "self": "\https://example.com/2022-04/features/example:snowparkRail",
    "resources": {
      "snowparks": "\https://example.com/2022-04/snowparks?filter[features][any]=example:snowparkRail"
    }
  }
}

Examples¶

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

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

asciidoc/examples/feature.min.json

The following example presents an object representing a feature resource:

{
  "type": "features",
  "id": "example:snowparkRamp",
  "meta": {
    "dataProvider": "https://example.com",
    "lastUpdate": "2022-04-01T08:00:00+02:00"
  },
  "attributes": {
    "abstract": {
      "ita": "Una rampa di snowpark è una struttura per la pratica di manovre aeree negli sport invernali radicali.",
      "deu": "Eine Snowpark-Rampe ist eine Struktur zum Üben von Flugmanövern im radikalen Wintersport.",
      "eng": "A snowpark ramp is a structure for the practice of aerial maneuvers in radical winter sports."
    },
    "description": {
      "ita": "Una rampa da snowpark è una struttura presente negli snowpark progettata per supportare l'esecuzione di manovre aeree negli sport invernali radicali.",
      "deu": "Eine Snowpark-Rampe ist eine Einrichtung in Snowparks, die dazu dient, die Ausführung von Flugmanövern bei radikalen Wintersportarten zu unterstützen.",
      "eng": "A snowpark ramp is a feature present in snowparks designed to support the execution of aerial maneuvers in radical winter sports."
    },
    "name": {
      "ita": "Snowpark Ramp",
      "deu": "Snowpark Rampe",
      "eng": "Snowpark Ramp"
    },
    "namespace": "example",
    "resourceTypes": [ "snowparks" ],
    "shortName": {
      "eng": "Snowpark Ramp"
    },
    "url": "https://en.wikipedia.org/wiki/Terrain_park"
  },
  "relationships": {
    "children": {
      "data": [
        {
          "type": "features",
          "id": "example:snowboardRamp"
        }
      ],
      "links": {
        "related": "https://example.com/2022-04/features/example:snowparkRamp/children"
      }
    },
    "multimediaDescriptions": {
      "data": [
        {
          "type": "mediaObjects",
          "id": "1"
        }
      ],
      "links": {
        "related": "https://example.com/2022-04/features/example:snowparkRamp/multimediaDescriptions"
      }
    },
    "parents": {
      "data": [
        {
          "type": "features",
          "id": "example:radicalSportsRamp"
        }
      ],
      "links": {
        "related": "https://example.com/2022-04/features/example:snowparkRamp/parents"
      }
    }
  },
  "links": {
    "self": "https://example.com/2022-04/features/example:snowparkRamp",
    "resources": {
      "snowparks": "https://example.com/2022-04/snowparks?filter[features][any]=example:snowparkRamp"
    }
  }
}

asciidoc/examples/feature.full.json