Elements
Elements
GET /api/dtpr/v1/elements— All elementsGET /api/dtpr/v1/elements/:datachain_type— Elements by datachain type (device,ai)
Overview
The DTPR Element schema defines the structure for individual transparency elements that describe technologies, data practices, and other aspects of digital systems in public spaces. Elements are reusable components that can be instantiated within datachains to create comprehensive transparency disclosures.
Response structure
Each element object in the response array contains:
schema— Metadata about the schema specificationelement— The core element definition
When deployed in datachains, elements also include:
instance— The specific instantiation with values and configuration
Schema section
"schema": {
"name": "DTPR Element",
"id": "dtpr_element",
"version": "0.1",
"namespace": "https://dtpr.io/schemas/element/v0.1"
}
| Property | Type | Required | Description |
|---|---|---|---|
name | string | yes | Schema specification name ("DTPR Element") |
id | string | yes | Unique schema identifier |
version | string | yes | DTPR schema version |
namespace | string | yes | URL identifying this schema version |
Element section
Basic identification
"id": "identifiable_video",
"category_ids": ["tech"],
"version": "2024-06-11T00:00:00Z"
| Property | Type | Required | Description |
|---|---|---|---|
id | string | yes | Unique element identifier |
category_ids | array | yes | Categories this element belongs to (e.g., "tech", "purpose", "data") |
version | string | yes | ISO 8601 timestamp of when this element version was created |
Localized content
All user-facing text supports internationalization through locale arrays:
"title": [{"locale": "en", "value": "Identifiable Video"}],
"description": [
{"locale": "en", "value": "Generates video footage of a sufficient resolution..."}
],
"citation": [
{"locale": "en", "value": "Find out more about [computer vision](https://en.wikipedia.org/wiki/Computer_vision)."}
]
| Property | Type | Required | Description |
|---|---|---|---|
title | locale array | yes | Display name of the element |
description | locale array | yes | Detailed explanation. Supports {{variable}} interpolation and Markdown |
citation | locale array | no | Reference information with external links |
Each locale array entry contains:
locale(string) — Language/region code (e.g.,"en","fr-CA")value(string) — The localized text
Icon
"icon": {
"url": "https://dtpr-io-static.onrender.com/dtpr-icons/identifiable_video.svg",
"alt_text": [{"locale": "en", "value": "Identifiable video icon"}],
"format": "svg"
}
| Property | Type | Required | Description |
|---|---|---|---|
url | string | yes | Full URL to the icon file |
alt_text | locale array | yes | Localized alternative text for accessibility |
format | string | yes | File format (e.g., "svg", "png") |
Variables
Variables allow elements to be customized when instantiated in a datachain:
"variables": [
{
"id": "additional_description",
"required": false,
"label": [{"locale": "en", "value": "Additional Description"}]
}
]
| Property | Type | Required | Description |
|---|---|---|---|
id | string | yes | Unique variable identifier within the element |
required | boolean | yes | Whether the variable must be provided when instantiating |
label | locale array | yes | Localized label for the variable |
Variables can be referenced in description text using double curly braces:
"description": [
{"locale": "en", "value": "This system stores data for {{duration}} and {{additional_description}}"}
]
Instance section (deployment only)
The instance section contains the specific instantiation of the element for use in a datachain. This section is not returned by the API but is used when elements are deployed in actual datachains.
"instance": {
"priority": 0,
"variables": {
"additional_description": [
{"locale": "en", "value": "This technology can also capture audio data."}
]
}
}
| Property | Type | Required | Description |
|---|---|---|---|
priority | integer | yes | Display order within the category (0-based, lower = first) |
variables | object | no | Variable values keyed by variable ID |
Full response example
[
{
"schema": {
"name": "DTPR Element",
"id": "dtpr_element",
"version": "0.1",
"namespace": "https://dtpr.io/schemas/element/v0.1"
},
"element": {
"id": "identifiable_video",
"category_ids": ["tech"],
"version": "2024-06-11T00:00:00Z",
"icon": {
"url": "https://dtpr-io-static.onrender.com/dtpr-icons/identifiable_video.svg",
"alt_text": [{"locale": "en", "value": "Identifiable video icon"}],
"format": "svg"
},
"title": [{"locale": "en", "value": "Identifiable Video"}],
"description": [
{"locale": "en", "value": "Generates video footage of a sufficient resolution where individuals can be identified, for example by capturing images of faces or unique numbers such as vehicle license plates."}
],
"citation": [
{"locale": "en", "value": "Find out more about [computer vision](https://en.wikipedia.org/wiki/Computer_vision)."}
],
"variables": [
{
"id": "additional_description",
"required": false,
"label": [{"locale": "en", "value": "Additional Description"}]
}
]
}
}
]
Usage notes
Element reusability
Elements are designed to be reusable across multiple datachains. The element definition provides the template, while instances provide the specific variable values and context for a particular deployment.
Element vs instance separation
The element definition provides the reusable template with structure, constraints, and default content. The instance provides specific values, configuration, and localized content for a particular use case. This allows:
- Elements to be maintained in a central library
- Instances to be customized for specific deployments
- Multiple instances of the same element with different configurations
Validation
Implementations should validate:
- Required fields are present
- Locale codes follow standard formats
- Variable references in descriptions match defined variables
- URLs are properly formatted
Related
- Categories — Category schema reference
- Datachains — Datachain schema reference
- Variables concept — How variable interpolation works