Categories

Endpoint:GET /api/dtpr/v1/categories/:datachain_type

Overview

The DTPR Category schema defines the structure for categories that organize and group elements within datachains. Categories provide semantic grouping (e.g., "Technology", "Purpose", "Data") and define shared variables that elements within the category can use.

Parameters

Parameter	In	Type	Required	Description
`datachain_type`	path	string	yes	Must be `device` or `ai`
`locales`	query	string	no	Comma-separated locale codes (e.g., `en,fr,es`)

Response structure

The endpoint returns an array of category objects, sorted by the order field (categories without an order value appear at the end). Each object contains:

schema — Metadata about the schema specification
category — The core category definition

Schema section

"schema": {
  "name": "DTPR Category",
  "id": "dtpr_category",
  "version": "0.1",
  "namespace": "https://dtpr.io/schemas/category/v0.1"
}

Property	Type	Required	Description
`name`	string	yes	Schema specification name (`"DTPR Category"`)
`id`	string	yes	Unique schema identifier
`version`	string	yes	DTPR schema version
`namespace`	string	yes	URL identifying this schema version

Category section

Basic identification

"id": "device__tech",
"order": 0,
"required": true,
"version": "2024-06-11T00:00:00Z"

Property	Type	Required	Description
`id`	string	yes	Unique category identifier (format: `{datachain_type}__{category_name}`)
`order`	integer	no	Display order (0-based, lower = first)
`required`	boolean	no	Whether this category must have at least one element
`version`	string	yes	ISO 8601 timestamp of the latest update

Localized content

"name": [{"locale": "en", "value": "Technology"}],
"description": [{"locale": "en", "value": "Describes the data collection technologies being used"}],
"prompt": [{"locale": "en", "value": "What technologies are collecting data?"}]

Property	Type	Required	Description
`name`	locale array	yes	Display name of the category
`description`	locale array	yes	Explanation of what the category represents
`prompt`	locale array	yes	Question helping users understand what elements belong here

Element variables

Categories can define variables available to all elements within the category:

"element_variables": [
  {
    "id": "duration",
    "label": [{"locale": "en", "value": "Retention Duration"}],
    "required": true
  }
]

Property	Type	Required	Description
`id`	string	yes	Unique variable identifier within the category
`required`	boolean	yes	Whether elements must provide a value
`label`	locale array	yes	Localized label for the variable

These variables are inherited by all elements in the category and can be referenced using {{variable_id}} syntax in element descriptions.

Standard categories

Category ID	Description
`tech`	Technologies and sensors used for data collection
`purpose`	Why data is being collected
`data`	What types of data are collected
`process`	How data is processed
`storage`	Where and how data is stored
`access`	Who can access the data
`retention`	How long data is kept
`accountable`	Who is responsible for the data

Locale filtering

When the locales query parameter is provided, the API filters all localized content:

name array is filtered
description array is filtered
prompt array is filtered
element_variables[].label arrays are filtered

Example

Request: GET /api/dtpr/v1/categories/device?locales=en

[
  {
    "schema": {
      "name": "DTPR Category",
      "id": "dtpr_category",
      "version": "0.1",
      "namespace": "https://dtpr.io/schemas/category/v0.1"
    },
    "category": {
      "id": "device__tech",
      "order": 0,
      "required": true,
      "name": [{"locale": "en", "value": "Technology"}],
      "description": [
        {"locale": "en", "value": "Describes the specific technologies, sensors, and devices used to collect data"}
      ],
      "prompt": [{"locale": "en", "value": "What technologies are collecting data?"}],
      "version": "2024-06-11T00:00:00Z",
      "element_variables": [
        {
          "id": "additional_description",
          "label": [{"locale": "en", "value": "Additional Description"}],
          "required": false
        }
      ]
    }
  }
]

Full response example (multiple locales)

[
  {
    "schema": {
      "name": "DTPR Category",
      "id": "dtpr_category",
      "version": "0.1",
      "namespace": "https://dtpr.io/schemas/category/v0.1"
    },
    "category": {
      "id": "device__tech",
      "order": 0,
      "required": true,
      "name": [
        {"locale": "en", "value": "Technology"},
        {"locale": "fr", "value": "Technologie"}
      ],
      "description": [
        {"locale": "en", "value": "Describes the specific technologies, sensors, and devices used to collect data"},
        {"locale": "fr", "value": "D\u00e9crit les technologies, capteurs et appareils sp\u00e9cifiques utilis\u00e9s pour collecter des donn\u00e9es"}
      ],
      "prompt": [
        {"locale": "en", "value": "What technologies are collecting data?"},
        {"locale": "fr", "value": "Quelles technologies collectent des donn\u00e9es?"}
      ],
      "version": "2024-06-11T00:00:00Z",
      "element_variables": [
        {
          "id": "additional_description",
          "label": [
            {"locale": "en", "value": "Additional Description"},
            {"locale": "fr", "value": "Description suppl\u00e9mentaire"}
          ],
          "required": false
        }
      ]
    }
  },
  {
    "schema": {
      "name": "DTPR Category",
      "id": "dtpr_category",
      "version": "0.1",
      "namespace": "https://dtpr.io/schemas/category/v0.1"
    },
    "category": {
      "id": "device__purpose",
      "order": 1,
      "required": true,
      "name": [
        {"locale": "en", "value": "Purpose"},
        {"locale": "fr", "value": "Objectif"}
      ],
      "description": [
        {"locale": "en", "value": "Explains why data is being collected and how it will be used"},
        {"locale": "fr", "value": "Explique pourquoi les donn\u00e9es sont collect\u00e9es et comment elles seront utilis\u00e9es"}
      ],
      "prompt": [
        {"locale": "en", "value": "Why is data being collected?"},
        {"locale": "fr", "value": "Pourquoi les donn\u00e9es sont-elles collect\u00e9es?"}
      ],
      "version": "2024-06-11T00:00:00Z",
      "element_variables": []
    }
  }
]

Elements — Element schema reference
Datachains — Datachain schema reference
Localization concept — How locale arrays work

Edit this pageorReport an issue

Elements

Full schema documentation for DTPR Element API responses.

Datachains

Schema documentation for DTPR Datachains — how elements and categories are composed into transparency disclosures.