SapienStream

Semantic Tags API

High-level semantic abstractions over raw machine tags. Transform raw industrial data into meaningful, domain-aware representations with standardized units and safety classification.

Overview

Semantic Types

  • • Analog: Continuous measurements (temperature, pressure)
  • • Digital: Binary states (on/off, open/closed)
  • • State: Enumerated states (running/stopped/fault)
  • • Counter: Accumulating values (production count)

Features

  • • Normalized data representation
  • • Safety criticality classification
  • • Operational limits and validation
  • • OPC-UA type mappings
  • • Auto-scaling configuration
  • • Source tag aggregation

Semantic Tag Data Model

Semantic Tag Properties
Normalized representation with domain-aware metadata and safety classification
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "machine_id": "machine_001",
  "canonical_name": "Reactor_Temperature",
  "source_tags": ["HT001_PV", "HT001_CV"],
  "semantic_type": "Analog",
  "unit": "°C",
  "criticality": "high",
  "limits": {
    "min": 0,
    "max": 500,
    "warning_high": 450,
    "alarm_high": 480
  },
  "validation_rules": {
    "rate_of_change_max": 10,
    "deadband": 0.1
  },
  "safety_function": "High Temperature Trip",
  "ua_type": "Double",
  "ua_namespace": "http://example.com/reactor",
  "description": "Primary reactor temperature measurement",
  "notes": "Calibrated 2024-01-15, next cal due 2024-07-15",
  "is_active": true,
  "auto_scaling": {
    "enabled": true,
    "factor": 1.0,
    "offset": 0.0
  },
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "created_by": "engineer1",
  "updated_by": "engineer1"
}

Criticality Levels

LOW

Informational only. No operational impact.

MEDIUM

Operational concern requiring attention.

HIGH

Safety critical requiring immediate response.

CRITICAL

Emergency shutdown level requiring immediate action.

API Endpoints

GET/semantic-tags/{machine_id}Auth Required
List Semantic Tags
Get all semantic tags for a specific machine with filtering and search capabilities.

Parameters

machine_idstringRequired

Unique identifier of the machine

active_onlyboolean

Show only active semantic tags (default: true)

semantic_typestring

Filter by type (Analog, Digital, State, Counter)

criticalitystring

Filter by criticality (low, medium, high, critical)

safety_onlyboolean

Show only safety-related tags (default: false)

searchstring

Search in canonical names and descriptions

limitinteger

Maximum results (max: 100, default: 50)

offsetinteger

Number of results to skip (default: 0)

Response

Responsejson
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "machine_id": "machine_001",
    "canonical_name": "Reactor_Temperature",
    "semantic_type": "Analog",
    "unit": "°C",
    "criticality": "high",
    "is_active": true,
    "source_tag_count": 2,
    "safety_function": "High Temperature Trip"
  },
  {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "machine_id": "machine_001",
    "canonical_name": "Emergency_Stop_State",
    "semantic_type": "Digital",
    "unit": "boolean",
    "criticality": "critical",
    "is_active": true,
    "source_tag_count": 1,
    "safety_function": "Emergency Shutdown System"
  }
]

Try it out

cURLbash
curl -X GET "https://sapienstream.com/api/semantic-tags/{machine_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
GET/semantic-tags/{machine_id}/{semantic_id}Auth Required
Get Semantic Tag Details
Retrieve detailed information about a specific semantic tag including full configuration, source tags, and validation rules.

Parameters

machine_idstringRequired

Unique identifier of the machine

semantic_idstringRequired

UUID of the semantic tag to retrieve

Response

Responsejson
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "machine_id": "machine_001",
  "canonical_name": "Reactor_Temperature",
  "source_tags": ["HT001_PV", "HT001_CV"],
  "semantic_type": "Analog",
  "unit": "°C",
  "criticality": "high",
  "limits": {
    "min": 0,
    "max": 500,
    "warning_high": 450,
    "alarm_high": 480
  },
  "validation_rules": {
    "rate_of_change_max": 10,
    "deadband": 0.1
  },
  "safety_function": "High Temperature Trip",
  "ua_type": "Double",
  "ua_namespace": "http://example.com/reactor",
  "description": "Primary reactor temperature measurement",
  "notes": "Calibrated 2024-01-15, next cal due 2024-07-15",
  "is_active": true,
  "auto_scaling": {
    "enabled": true,
    "factor": 1.0,
    "offset": 0.0
  },
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "created_by": "engineer1",
  "updated_by": "engineer1"
}

Try it out

cURLbash
curl -X GET "https://sapienstream.com/api/semantic-tags/{machine_id}/{semantic_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
POST/semantic-tags/{machine_id}Auth Required
Create Semantic Tag
Create a new semantic abstraction over raw machine tags with domain-aware configuration.

Parameters

machine_idstringRequired

Unique identifier of the machine

created_bystringRequired

Username of the creator (query parameter)

Request Body

Requestjson
{
  "canonical_name": "Reactor_Temperature",
  "source_tags": ["HT001_PV", "HT001_CV"],
  "semantic_type": "Analog",
  "unit": "°C",
  "criticality": "high",
  "limits": {
    "min": 0,
    "max": 500,
    "warning_high": 450,
    "alarm_high": 480
  },
  "validation_rules": {
    "rate_of_change_max": 10,
    "deadband": 0.1
  },
  "safety_function": "High Temperature Trip",
  "ua_type": "Double",
  "ua_namespace": "http://example.com/reactor",
  "description": "Primary reactor temperature measurement",
  "notes": "Temperature sensor with redundancy",
  "auto_scaling": {
    "enabled": true,
    "factor": 1.0,
    "offset": 0.0
  }
}

Response

Responsejson
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "machine_id": "machine_001",
  "canonical_name": "Reactor_Temperature",
  "source_tags": ["HT001_PV", "HT001_CV"],
  "semantic_type": "Analog",
  "unit": "°C",
  "criticality": "high",
  "limits": {
    "min": 0,
    "max": 500,
    "warning_high": 450,
    "alarm_high": 480
  },
  "validation_rules": {
    "rate_of_change_max": 10,
    "deadband": 0.1
  },
  "safety_function": "High Temperature Trip",
  "ua_type": "Double",
  "ua_namespace": "http://example.com/reactor",
  "description": "Primary reactor temperature measurement",
  "notes": "Temperature sensor with redundancy",
  "auto_scaling": {
    "enabled": true,
    "factor": 1.0,
    "offset": 0.0
  },
  "is_active": true,
  "created_at": "2024-08-26T12:00:00Z",
  "updated_at": "2024-08-26T12:00:00Z",
  "created_by": "engineer1",
  "updated_by": "engineer1"
}

Try it out

cURLbash
curl -X POST "https://sapienstream.com/api/semantic-tags/{machine_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
PUT/semantic-tags/{machine_id}/{semantic_id}Auth Required
Update Semantic Tag
Modify semantic tag configuration including limits, validation rules, and metadata.

Parameters

machine_idstringRequired

Unique identifier of the machine

semantic_idstringRequired

UUID of the semantic tag to update

updated_bystringRequired

Username of the updater (query parameter)

Request Body

Requestjson
{
  "description": "Updated reactor temperature with new calibration",
  "limits": {
    "min": 0,
    "max": 520,
    "warning_high": 470,
    "alarm_high": 500
  },
  "validation_rules": {
    "rate_of_change_max": 15,
    "deadband": 0.2
  },
  "notes": "Recalibrated 2024-08-26, next due 2025-02-26",
  "is_active": true
}

Response

Responsejson
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "machine_id": "machine_001",
  "canonical_name": "Reactor_Temperature",
  "source_tags": ["HT001_PV", "HT001_CV"],
  "semantic_type": "Analog",
  "unit": "°C",
  "criticality": "high",
  "limits": {
    "min": 0,
    "max": 520,
    "warning_high": 470,
    "alarm_high": 500
  },
  "validation_rules": {
    "rate_of_change_max": 15,
    "deadband": 0.2
  },
  "safety_function": "High Temperature Trip",
  "ua_type": "Double",
  "ua_namespace": "http://example.com/reactor",
  "description": "Updated reactor temperature with new calibration",
  "notes": "Recalibrated 2024-08-26, next due 2025-02-26",
  "is_active": true,
  "auto_scaling": {
    "enabled": true,
    "factor": 1.0,
    "offset": 0.0
  },
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-08-26T12:30:00Z",
  "created_by": "engineer1",
  "updated_by": "engineer1"
}

Try it out

cURLbash
curl -X PUT "https://sapienstream.com/api/semantic-tags/{machine_id}/{semantic_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
GET/semantic-tags/{machine_id}/statsAuth Required
Semantic Tag Statistics
Get aggregated statistics about semantic tags for a specific machine.

Parameters

machine_idstringRequired

Unique identifier of the machine

Response

Responsejson
{
  "machine_id": "machine_001",
  "total_semantic_tags": 45,
  "active_semantic_tags": 42,
  "inactive_semantic_tags": 3,
  "by_semantic_type": {
    "Analog": 25,
    "Digital": 15,
    "State": 3,
    "Counter": 2
  },
  "by_criticality": {
    "low": 20,
    "medium": 15,
    "high": 8,
    "critical": 2
  },
  "safety_related": 10,
  "with_limits": 28,
  "with_validation_rules": 35,
  "total_source_tags": 89,
  "avg_source_tags_per_semantic": 1.98
}

Try it out

cURLbash
curl -X GET "https://sapienstream.com/api/semantic-tags/{machine_id}/stats" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Common Use Cases

Real-world Applications
Examples of semantic tag implementations in industrial environments

Temperature Normalization

Combine multiple temperature sensors into a single "Reactor_Temperature" semantic tag with standardized units and safety limits.

Source: ["HT001_PV", "HT002_PV"] → "Reactor_Temperature"

Motor State Abstraction

Abstract raw motor control signals into meaningful states like "Running", "Stopped", "Fault".

Source: ["M001_RUN", "M001_STOP", "M001_FAULT"] → "Motor_State"

Production Counter

Track production counts with validation rules and accumulation logic.

Source: ["PROD_COUNT"] → "Daily_Production"

Safety Interlock

Combine multiple safety signals into critical safety function monitoring.

Source: ["E_STOP_1", "E_STOP_2"] → "Emergency_Stop_State"

Error Responses

Common Error Codes

400 Bad Request

{
  "detail": "Invalid semantic_type: 'INVALID' not in ['Analog', 'Digital', 'State', 'Counter']"
}

404 Not Found

{
  "detail": "Machine 'machine_999' not found"
}

409 Conflict

{
  "detail": "Semantic tag 'Reactor_Temperature' already exists on machine 'machine_001'"
}

422 Validation Error

{
  "detail": "Source tag 'INVALID_TAG' not found on machine 'machine_001'"
}