Datachains

Overview

The DTPR Datachain schema defines the structure for organizing collections of DTPR elements into meaningful, ordered transparency disclosures. A datachain represents a complete disclosure for a specific technology deployment, organizing elements by categories and providing the context needed to render a comprehensive transparency interface.

Datachains come in different types (e.g., device, ai) and define both the template structure and specific instances with real-world data.

Schema structure

A datachain document has three main sections:

• schema — Metadata about the schema specification
• datachain — The template definition (categories and configuration)
• instance — The specific instantiation with actual elements and values

Schema section

"schema": {
  "name": "DTPR",
  "version": "0.1",
  "namespace": "https://dtpr.io/schemas/datachain/v0.1"
}

Datachain section

The template defining the category structure and configuration for a specific datachain type.

Basic properties

"type": "device",
"version": "2024-06-11T00:00:00Z",
"title": [{"locale": "en", "value": "Device datachain"}],
"description": [{"locale": "en", "value": "A datachain for describing data-collecting devices in public space."}]

Categories

Categories define the organizational structure and display order for elements:

"categories": [
  {
    "id": "tech",
    "order": 1,
    "name": [{"locale": "en", "value": "Technology"}],
    "prompt": [{"locale": "en", "value": "How does this technology work?"}],
    "description": [{"locale": "en", "value": "The core technology components that collect or process data"}],
    "context_types": [
      {
        "id": "pii",
        "name": [{"locale": "en", "value": "Personal Information"}],
        "description": [{"locale": "en", "value": "Technologies that collect personally identifiable information"}],
        "color": "#FFCC00"
      }
    ]
  }
]

Context types

Context types provide visual and semantic indicators for elements within a category:

{
  "id": "pii",
  "name": [{"locale": "en", "value": "Personal Information"}],
  "description": [{"locale": "en", "value": "Technologies that collect personally identifiable information"}],
  "color": "#FFCC00"
}

Instance section

The specific instantiation of the datachain template with real-world data.

Basic properties

"title": [{"locale": "en", "value": "Intersection 5th & Main"}],
"created_at": "2024-06-11T14:32:00Z"

Elements

Elements selected for this datachain instance:

"elements": [
  {
    "element_id": "identifiable_video",
    "category_id": "tech",
    "priority": 0,
    "context_type_id": "pii",
    "variables": [
      {"id": "resolution", "value": "1080p"}
    ]
  }
]

Datachain types

Different datachain types have different category structures:

Each type defines its own set of relevant categories and context types appropriate to its domain.

Display logic

Ordering

1. Categories are displayed in ascending order
2. Elements within a category are displayed in ascending priority

Context visualization

Elements with a context_type_id should be visually styled using the corresponding color and may display additional context information.

Variable interpolation

When displaying elements, variable values from the instance should replace {{variable_name}} placeholders in the element's description text. See Variables for details.

Rendering workflow

1. Load the complete datachain document
2. Sort categories by order
3. Group elements by category_id
4. Sort elements within categories by priority
5. Resolve context types for colors and labels
6. Interpolate variable values into element descriptions
7. Render in the determined order

Validation

Implementations should validate:

• All required fields are present
• Category IDs in elements match defined categories
• Context type IDs exist in the appropriate category
• Variable IDs match those defined in referenced elements
• Locale codes follow standard formats
• Timestamps are valid ISO 8601
• Color codes are valid hex format
• Priority and order values are non-negative integers

Related

• Elements — Element schema reference
• Categories — Category schema reference
• Taxonomy concept — How elements, categories, and datachains relate