Extension Library API Reference

The Extension Library provides extensible components and utilities for enhancing the core Tractus-X SDK functionality. This reference documentation covers semantic processing tools, schema transformations, and custom use-case implementations available in the Extension Library.

Overview

The Extension Library enables:

Semantic Data Processing - Transform SAMM schemas to JSON-LD contexts for linked data
Schema Transformations - Convert aspect models between formats
Use-Case Extensions - Domain-specific implementations (PCF, certificates, etc.)
JSON-LD Context Generation - Create standardized contexts for semantic interoperability

API Components

Semantic Extensions

Tools for processing SAMM (Semantic Aspect Meta Model) schemas and generating JSON-LD contexts.

SAMM Schema Context Translator

Semantics API - Complete API reference
Schema to JSON-LD conversion (flattened and nested)
Automatic schema fetching from semantic repositories
Circular reference handling
Schema validation and transformation
Custom prefix support

Quick Start Examples

Converting SAMM Schema to JSON-LD

Python

from tractusx_sdk.extensions.semantics import SammSchemaContextTranslator

# Initialize translator
translator = SammSchemaContextTranslator(verbose=True)

# Convert SAMM schema to flattened JSON-LD context
context = translator.schema_to_jsonld(
    semantic_id="urn:samm:io.catenax.pcf:7.0.0#Pcf",
    aspect_prefix="cx"
)

# Use the generated context
print(context["@context"])

Using Nested JSON-LD Format

Python

# Generate nested JSON-LD context with hierarchical structure
nested_context = translator.schema_to_jsonld_nested(
    semantic_id="urn:samm:io.catenax.part_type_information:1.0.0#PartTypeInformation",
    aspect_prefix="cx"
)

# Access nested properties
for key, value in nested_context.items():
    if isinstance(value, dict) and "@context" in value:
        print(f"Aspect: {key}")
        print(f"Context: {value['@context']}")

Providing Custom Schema

Python

import json

# Load schema from local file
with open("my-aspect-schema.json", "r") as f:
    custom_schema = json.load(f)

# Convert custom schema
context = translator.schema_to_jsonld(
    semantic_id="urn:samm:com.example.myaspect:1.0.0#MyAspect",
    schema=custom_schema,
    aspect_prefix="example"
)

Documentation Structure

Text Only

extension-library/
├── index.md                    # This file - API overview
└── semantics/
    └── semantics.md           # SAMM Schema Context Translator API

Use Cases

The Extension Library supports various domain-specific use cases:

Product Carbon Footprint (PCF)

Python

# Convert PCF aspect model to JSON-LD
pcf_context = translator.schema_to_jsonld(
    semantic_id="urn:samm:io.catenax.pcf:7.0.0#Pcf",
    aspect_prefix="pcf"
)

# Use context for PCF data validation and processing
pcf_data = {
    "@context": pcf_context["@context"],
    "productId": "MPN-12345",
    "carbonFootprint": {
        "value": 123.45,
        "unit": "kgCO2e"
    }
}

Part Type Information

Python

# Convert Part Type Information aspect
part_context = translator.schema_to_jsonld(
    semantic_id="urn:samm:io.catenax.part_type_information:1.0.0#PartTypeInformation",
    aspect_prefix="part"
)

Serial Part Typization

Python

# Convert Serial Part aspect with nested structure
serial_context = translator.schema_to_jsonld_nested(
    semantic_id="urn:samm:io.catenax.serial_part:3.0.0#SerialPart",
    aspect_prefix="serial"
)

Integration Patterns

Complete Semantic Processing Workflow

Python

from tractusx_sdk.extensions.semantics import SammSchemaContextTranslator
from tractusx_sdk.industry.services import AasService
from tractusx_sdk.dataspace.managers import OAuth2Manager
import json

# 1. Initialize services
auth_manager = OAuth2Manager(
    token_url="https://auth.example.com/token",
    client_id="your-client-id",
    client_secret="your-client-secret"
)

aas_service = AasService(
    base_url="https://dtr.example.com",
    base_lookup_url="https://dtr-lookup.example.com",
    api_path="/api/v3.0",
    auth_service=auth_manager
)

translator = SammSchemaContextTranslator(verbose=True)

# 2. Get submodel semantic ID from DTR
shell = aas_service.get_asset_administration_shell_descriptor_by_id(
    aas_identifier="urn:uuid:12345"
)

for submodel in shell.submodel_descriptors:
    # Extract semantic ID
    semantic_id = submodel.semantic_id["keys"][0]["value"]

    # 3. Generate JSON-LD context for this aspect
    context = translator.schema_to_jsonld(
        semantic_id=semantic_id,
        aspect_prefix="cx"
    )

    # 4. Fetch submodel data and add context
    # (Assuming data fetched from endpoint)
    submodel_data = {
        "@context": context["@context"],
        # ... actual submodel data
    }

    # 5. Validate and process with semantic context
    print(f"Processed {submodel.id_short} with context")

API Conventions

Semantic IDs

All semantic IDs must follow the URN format:

Text Only

urn:samm:<namespace>:<aspect-name>:<version>#<AspectName>

Example:

Text Only

urn:samm:io.catenax.pcf:7.0.0#Pcf

Context Prefixes

Custom prefixes can be specified for aspect properties:

Python

context = translator.schema_to_jsonld(
    semantic_id="urn:samm:io.catenax.pcf:7.0.0#Pcf",
    aspect_prefix="custom"  # Use 'custom' instead of default 'cx'
)

Schema Sources

Schemas can be provided in three ways:

Auto-fetch from repository (default):

Python

context = translator.schema_to_jsonld(semantic_id="urn:samm:...")

Custom repository URL:

Python

context = translator.schema_to_jsonld(
    semantic_id="urn:samm:...",
    link_core="https://my-repo.example.com/schemas/"
)

Explicit schema dictionary:

Python

context = translator.schema_to_jsonld(
    semantic_id="urn:samm:...",
    schema=my_schema_dict
)

Output Formats

Flattened JSON-LD

Use schema_to_jsonld() for flat context structure:

JSON

{
  "@context": {
    "@version": 1.1,
    "id": "@id",
    "type": "@type",
    "cx": "aspect-specific-uri",
    "property1": "cx:property1",
    "property2": "cx:property2"
  },
  "@definition": "Aspect description"
}

Nested JSON-LD

Use schema_to_jsonld_nested() for hierarchical structure:

JSON

{
  "AspectName": {
    "@context": {
      "@version": 1.1,
      "id": "@id",
      "type": "@type",
      "property1": {
        "@context": {
          "nestedProp1": "...",
          "nestedProp2": "..."
        }
      }
    }
  }
}

Error Handling

Python

try:
    context = translator.schema_to_jsonld(
        semantic_id="urn:samm:invalid:id"
    )
except Exception as e:
    if "Could not fetch schema" in str(e):
        print("Schema not found in repository")
    elif "Invalid semantic id" in str(e):
        print("Malformed semantic ID format")
    else:
        print(f"Error: {e}")

Best Practices

Enable verbose logging for debugging schema transformations
Cache generated contexts to avoid repeated API calls
Validate semantic IDs before calling translation methods
Use nested format for complex hierarchical data structures
Specify custom prefixes to avoid naming conflicts
Handle circular references - translator automatically limits recursion depth
Validate output against JSON-LD specifications

Performance Considerations

Schema Caching

Python

# Cache schemas for repeated use
schema_cache = {}

def get_or_fetch_schema(semantic_id):
    if semantic_id not in schema_cache:
        schema_cache[semantic_id] = translator.fetch_schema_from_semantic_id(semantic_id)
    return schema_cache[semantic_id]

# Use cached schema
context = translator.schema_to_jsonld(
    semantic_id=semantic_id,
    schema=get_or_fetch_schema(semantic_id)
)

Batch Processing

Python

# Process multiple aspects efficiently
semantic_ids = [
    "urn:samm:io.catenax.pcf:7.0.0#Pcf",
    "urn:samm:io.catenax.part_type_information:1.0.0#PartTypeInformation",
    "urn:samm:io.catenax.serial_part:3.0.0#SerialPart"
]

contexts = {}
for semantic_id in semantic_ids:
    try:
        contexts[semantic_id] = translator.schema_to_jsonld(
            semantic_id=semantic_id,
            aspect_prefix="cx"
        )
    except Exception as e:
        print(f"Failed to process {semantic_id}: {e}")

Advanced Features

Circular Reference Handling

The translator automatically detects and handles circular references in schemas:

Python

# Translator has built-in recursion depth limit
translator = SammSchemaContextTranslator()
translator.recursionDepth = 3  # Adjust if needed (default: 2)

context = translator.schema_to_jsonld(semantic_id="urn:samm:...")

Custom Logging

Python

import logging

# Configure custom logger
logger = logging.getLogger("SammTranslator")
logger.setLevel(logging.DEBUG)

translator = SammSchemaContextTranslator(
    logger=logger,
    verbose=True
)

context = translator.schema_to_jsonld(semantic_id="urn:samm:...")

NOTICE

This work is licensed under the CC-BY-4.0.

SPDX-License-Identifier: CC-BY-4.0
SPDX-FileCopyrightText: 2025, 2026 Contributors to the Eclipse Foundation
SPDX-FileCopyrightText: 2025, 2026 Catena-X Automotive Network e.V.
SPDX-FileCopyrightText: 2025, 2026 LKS Next
SPDX-FileCopyrightText: 2025, 2026 Mondragon Unibertsitatea
Source URL: https://github.com/eclipse-tractusx/tractusx-sdk

Extension Library API Reference

Overview

API Components

Semantic Extensions

SAMM Schema Context Translator

Quick Start Examples

Converting SAMM Schema to JSON-LD

Using Nested JSON-LD Format

Providing Custom Schema

Documentation Structure

Use Cases

Product Carbon Footprint (PCF)

Part Type Information

Serial Part Typization

Integration Patterns

Complete Semantic Processing Workflow

API Conventions

Semantic IDs

Context Prefixes

Schema Sources

Output Formats

Flattened JSON-LD

Nested JSON-LD

Error Handling

Best Practices

Performance Considerations

Schema Caching

Batch Processing

Advanced Features

Circular Reference Handling

Custom Logging

Further Reading

NOTICE

Eclipse Foundation

Eclipse Tractus-X

More