Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

RE Indicators Calculation Service

This site documents the CE-RISE RE indicators calculation service.

The service is a dedicated HTTP application that computes RE indicator results from the re-indicators-specification model family. It is intentionally domain-specific: the model family is fixed, the only user-selectable model dimension is the version tag, and validation is expected to run against the published SHACL artifacts for that selected version.

What This Service Does

  • accepts a validated RE indicators payload together with a selected specification version
  • delegates validation to hex-core-service against the RE indicators model during computation
  • computes structured RE indicator results based on the model-defined scoring logic
  • returns a detailed result object that preserves payload, validation details, and computed scores for downstream use

Relationship With hex-core-service

This service complements hex-core-service rather than replacing it.

  • hex-core-service remains the generic model-aware service for validation, persistence, and record operations
  • this service is the RE-specific computation layer
  • the preferred interaction pattern for this service is submission of a validated payload

Documentation Structure

Current Status

The repository currently contains the initial Rust service implementation and the first HTTP endpoints:

  • GET /health
  • GET /openapi.json
  • POST /compute

Artifact loading, SHACL-backed validation, and scoring logic are the next implementation steps.

Funded by the European Union under Grant Agreement No. 101092281 — CE-RISE.
Views and opinions expressed are those of the author(s) only and do not necessarily reflect those of the European Union or the granting authority (HADEA). Neither the European Union nor the granting authority can be held responsible for them.

CE-RISE logo

© 2026 CE-RISE consortium.
Licensed under the European Union Public Licence v1.2 (EUPL-1.2).
Attribution: CE-RISE project (Grant Agreement No. 101092281) and the individual authors/partners as indicated.

NILU logo

Developed by NILU (Riccardo Boero — ribo@nilu.no) within the CE-RISE project.

Architecture

Overview

The RE indicators calculation service is a dedicated, containerized HTTP service implemented in Rust.

Its responsibility is narrow:

  • accept RE indicators computation requests
  • resolve the selected RE indicators specification version
  • validate against SHACL artifacts
  • compute and return structured scoring results

Core Service Boundary

The service is intentionally not model-generic.

  • fixed model family: re-indicators-specification
  • variable model dimension: version tag only
  • validation basis: published SHACL artifacts

Internal Layers

The implementation should evolve around these layers:

  • HTTP API layer: request parsing, response formatting, status codes
  • artifact resolution layer: load published artifacts for a selected version
  • validation layer: execute SHACL validation against the selected artifact set
  • computation layer: derive parameter and total scores from the model-driven logic
  • mapping layer: produce a structured response suitable for downstream digital passport use

Deployment Shape

The intended deployment unit is a single service container.

No CLI or SDK is a primary deliverable for this repository.

API Overview

Design Goals

The API is designed around a simple synchronous service interaction:

  • callers submit a validated payload
  • callers choose the RE indicators specification version
  • the service returns structured validation and computation output

The API should stay explicit and domain-specific rather than mirroring the generic {model} pattern used by hex-core-service.

Core Principles

  • fixed model family: re-indicators-specification
  • version is required input
  • if version is omitted during current testing, the service defaults to 0.0.4
  • payload submission is the primary compute input pattern
  • validation is delegated to hex-core-service during computation
  • computation details are returned in a form that can be reused in downstream records or other models

Artifact Source

The service is hardwired to the RE indicators generated publication lineage:

https://codeberg.org/CE-RISE-models/re-indicators-specification/raw/tag/pages-v{version}/generated/

The only variable is {version}.

Current Endpoints

  • GET /health
  • GET /openapi.json
  • POST /compute

Request Shape

Current compute requests include:

{
  "model_version": "0.0.4",
  "payload": {
    "indicator_specification_id": "REcycle_PV",
    "parameter_assessments": [
      {
        "parameter_id": "P1_product_diagnosis",
        "question_answers": [
          {
            "question_id": "Q1.1",
            "selected_answer_id": "product_id_all_key_info"
          }
        ]
      }
    ]
  }
}

Response Shape

Current compute responses include:

  • fixed model family
  • selected model version
  • resolved artifact base URL
  • resolved artifact URLs for calculation, SHACL, schema, and OWL files
  • original payload
  • normalized validation summary from the hex-core-service validation interaction
  • computation result

API Reference

Base URL

http://<host>:8081/

GET /health

Service health and fixed service identity.

Example response:

{
  "status": "ok",
  "model_family": "re-indicators-specification",
  "validation_basis": "shacl",
  "default_testing_version": "0.0.4",
  "artifact_base_url_template": "https://codeberg.org/CE-RISE-models/re-indicators-specification/raw/tag/pages-v{version}/generated/",
  "hex_core_base_url": "http://127.0.0.1:8080",
  "http_timeout_secs": 15,
  "bind_address": "0.0.0.0",
  "port": 8081,
  "calculation_artifact_url_template": "https://codeberg.org/CE-RISE-models/re-indicators-specification/raw/tag/pages-v{version}/generated/calculation.json"
}

GET /openapi.json

Machine-readable OpenAPI document for the current service API.

This endpoint returns the generated OpenAPI description for:

  • GET /health
  • GET /openapi.json
  • POST /compute

Example usage:

curl -sS http://127.0.0.1:8081/openapi.json

POST /compute

Accept a validated RE indicators payload and compute a structured result for a selected model version.

If present, the incoming bearer token is forwarded to hex-core-service for delegated validation.

Request Schema

Top-level fields:

  • model_version
    • type: string | null
    • required: no
    • meaning: RE indicators model version to use
    • current default when omitted: 0.0.4
  • payload
    • type: object
    • required: yes
    • meaning: assessment payload used for delegated validation and computation

Payload fields currently used by computation:

  • payload.indicator_specification_id
    • type: string
    • required: yes
  • payload.parameter_assessments
    • type: array
    • required: no
    • default: []
  • payload.parameter_assessments[].parameter_id
    • type: string
    • required: yes
  • payload.parameter_assessments[].question_answers
    • type: array
    • required: no
    • default: []
  • payload.parameter_assessments[].question_answers[].question_id
    • type: string
    • required: yes
  • payload.parameter_assessments[].question_answers[].selected_answer_id
    • type: string | null
    • required: yes

Request

{
  "model_version": "0.0.4",
  "payload": {
    "indicator_specification_id": "REcycle_PV",
    "parameter_assessments": [
      {
        "parameter_id": "P1_product_diagnosis",
        "question_answers": [
          {
            "question_id": "Q1.1",
            "selected_answer_id": "product_id_all_key_info"
          }
        ]
      }
    ]
  }
}

Response Schema

Top-level fields:

  • model_family
    • type: string
    • fixed value: re-indicators-specification
  • model_version
    • type: string
  • artifact_base_url
    • type: string
    • meaning: resolved artifact publication base for the selected version
  • artifacts
    • type: object
    • meaning: resolved URLs for released RE indicators artifacts
  • payload
    • type: object
    • meaning: echoed assessment payload used for validation and computation
  • validation
    • type: object
    • meaning: normalized delegated validation result
  • result
    • type: object
    • meaning: computed score output

Artifact fields:

  • artifacts.model_version
  • artifacts.base_url
  • artifacts.calculation_url
  • artifacts.shacl_url
  • artifacts.schema_url
  • artifacts.owl_url

Validation fields:

  • validation.basis
    • type: string
    • current value: shacl
  • validation.source
    • type: string
    • current value: hex-core-service
  • validation.validation_url
    • type: string
  • validation.status
    • type: string
    • current values:
      • validated_by_hex_core
      • validation_skipped
  • validation.passed
    • type: boolean | null
  • validation.finding_count
    • type: integer | null
  • validation.findings_present
    • type: boolean | null
  • validation.raw_report
    • type: object | null
    • meaning: raw upstream validation report from hex-core-service
  • validation.details
    • type: string[]

Computation fields:

  • result.status
    • type: string
    • current value on success: computed
  • result.total_score
    • type: number | null
  • result.parameter_scores
    • type: array
  • result.parameter_scores[].parameter_id
    • type: string
  • result.parameter_scores[].computed_score
    • type: number | null
  • result.parameter_scores[].question_scores
    • type: array
  • result.parameter_scores[].question_scores[].question_id
    • type: string
  • result.parameter_scores[].question_scores[].selected_answer_id
    • type: string | null
  • result.parameter_scores[].question_scores[].answer_score
    • type: number | null
  • result.notes
    • type: string[]

Current Response

{
  "model_family": "re-indicators-specification",
  "model_version": "0.0.4",
  "artifact_base_url": "https://codeberg.org/CE-RISE-models/re-indicators-specification/raw/tag/pages-v0.0.4/generated/",
  "artifacts": {
    "model_version": "0.0.4",
    "base_url": "https://codeberg.org/CE-RISE-models/re-indicators-specification/raw/tag/pages-v0.0.4/generated/",
    "calculation_url": "https://codeberg.org/CE-RISE-models/re-indicators-specification/raw/tag/pages-v0.0.4/generated/calculation.json",
    "shacl_url": "https://codeberg.org/CE-RISE-models/re-indicators-specification/raw/tag/pages-v0.0.4/generated/shacl.ttl",
    "schema_url": "https://codeberg.org/CE-RISE-models/re-indicators-specification/raw/tag/pages-v0.0.4/generated/schema.json",
    "owl_url": "https://codeberg.org/CE-RISE-models/re-indicators-specification/raw/tag/pages-v0.0.4/generated/owl.ttl"
  },
  "payload": {
    "indicator_specification_id": "REcycle_PV",
    "parameter_assessments": [
      {
        "parameter_id": "P1_product_diagnosis",
        "question_answers": [
          {
            "question_id": "Q1.1",
            "selected_answer_id": "product_id_all_key_info"
          }
        ]
      }
    ]
  },
  "validation": {
    "basis": "shacl",
    "source": "hex-core-service",
    "validation_url": "http://127.0.0.1:8080/models/re-indicators-specification/versions/0.0.4:validate",
    "status": "validated_by_hex_core",
    "passed": true,
    "finding_count": 0,
    "findings_present": false,
    "raw_report": {
      "passed": true,
      "results": []
    },
    "details": [
      "Payload validation was delegated to hex-core-service."
    ]
  },
  "result": {
    "status": "computed",
    "total_score": 0.8,
    "parameter_scores": [
      {
        "parameter_id": "P1_product_diagnosis",
        "computed_score": 3.0,
        "question_scores": [
          {
            "question_id": "Q1.1",
            "selected_answer_id": "product_id_all_key_info",
            "answer_score": 3.0
          }
        ]
      }
    ],
    "notes": [
      "Scores are computed from calculation.json question scores and parameter weights."
    ]
  }
}

Notes

  • the model family is fixed internally and is not a request parameter
  • the service resolves artifacts from the configured ARTIFACT_BASE_URL_TEMPLATE
  • model_version is the only version selector
  • when omitted in the current implementation, model_version defaults to 0.0.4 for testing
  • the current implementation delegates validation to hex-core-service using POST /models/re-indicators-specification/versions/{version}:validate
  • computation uses the published calculation.json artifact for the same version
  • the payload is returned so downstream systems can place computation output where needed
  • the effective artifact base template, hex-core-service base URL, and HTTP timeout are runtime-configurable and exposed by GET /health
  • the machine-readable OpenAPI document is exposed at GET /openapi.json
  • the validation section is normalized by this service and only keeps the upstream report as raw_report

Error Responses

The service returns structured error responses with HTTP status codes.

Example shape:

{
  "code": "VALIDATION_FAILED",
  "message": "Delegated validation through hex-core-service did not pass.",
  "details": {}
}

Error fields:

  • code
    • type: string
    • meaning: machine-readable error identifier
  • message
    • type: string
    • meaning: human-readable summary
  • details
    • type: object | null
    • meaning: extra structured context when available

Current error categories include:

  • 400 invalid request body shape for the compute contract
  • 401 delegated validation unauthorized in hex-core-service
  • 404 requested model version or calculation.json artifact not found
  • 422 delegated validation failed or unknown indicator_specification_id
  • 502 delegated validation upstream error or calculation artifact fetch error
  • 500 internal service configuration/runtime error

Deployment

Service Form

This project is intended to be deployed as a containerized HTTP service.

Container Files

The repository includes:

  • Dockerfile
  • .dockerignore

Default Port

The current service listens on:

8081

Build Example

docker build -t re-indicators-calculation-service .

Run Example

docker run --rm -p 8081:8081 re-indicators-calculation-service

Runtime Configuration

The service supports these environment variables:

  • HEX_CORE_BASE_URL
  • ARTIFACT_BASE_URL_TEMPLATE
  • HTTP_TIMEOUT_SECS
  • BIND_ADDRESS
  • PORT

Defaults:

HEX_CORE_BASE_URL=http://127.0.0.1:8080
ARTIFACT_BASE_URL_TEMPLATE=https://codeberg.org/CE-RISE-models/re-indicators-specification/raw/tag/pages-v{version}/generated/
HTTP_TIMEOUT_SECS=15
BIND_ADDRESS=0.0.0.0
PORT=8081

Container example:

docker run --rm \
  -p 8081:8081 \
  -e HEX_CORE_BASE_URL=http://hex-core-service:8080 \
  -e ARTIFACT_BASE_URL_TEMPLATE=https://codeberg.org/CE-RISE-models/re-indicators-specification/raw/tag/pages-v{version}/generated/ \
  -e HTTP_TIMEOUT_SECS=15 \
  -e BIND_ADDRESS=0.0.0.0 \
  -e PORT=8081 \
  re-indicators-calculation-service

ARTIFACT_BASE_URL_TEMPLATE must contain {version} so the service can resolve the released artifact set for the selected model version.

Local-Only Demonstrator

This repository also includes a local-only integration path documented in Local Testing.

That path is intended for manual checks on a developer machine and is not part of CI.

Next Deployment Concerns

As the implementation grows, deployment documentation should be expanded to cover:

  • runtime configuration for artifact resolution
  • outbound connectivity to published model artifacts
  • integration settings for hex-core-service
  • health and readiness behavior

Local Testing

This repository includes a local-only demonstrator path for manual integration testing.

It is intended to verify the full local flow:

  • run hex-core-service locally in memory mode
  • run re-indicators-calculation-service locally
  • validate an RE indicators payload through hex-core-service
  • compute the RE indicators result through this service

This path is not part of CI.

Files

The local testing setup is defined by:

  • demo.sh
  • scripts/validate-local-compose.sh
  • compose/docker-compose.yml
  • compose/.env.example
  • payloads/recycle_battery_compute_request.json

What It Uses

The local stack starts:

  • hex-core-service
  • re-indicators-calculation-service

Notes:

  • hex-core-service runs with IO_ADAPTER_ID=memory
  • hex-core-service runs with AUTH_MODE=none
  • hex-core-service is pulled as a container image
  • the registry catalog points directly to the published schema.json, shacl.ttl, and model.ttl artifact URLs on the published Pages site
  • this service resolves calculation.json directly from the published Pages artifact URL
  • no database is required
  • this setup is only for local development and manual validation

Commands

Run the local validation flow:

./demo.sh validate

Run the local demonstration flow:

./demo.sh demo

Stop the stack:

./demo.sh down

Remove the stack and local synced artifacts:

./demo.sh clean

Expected Result

./demo.sh validate should complete with:

  • local hex-core-service readiness confirmed
  • local calculation service readiness confirmed
  • delegated validation passing
  • compute request returning 200

The current sample payload is:

  • model version 0.0.4
  • indicator REcycle_Battery

The current expected computed score is approximately:

0.138572436192

Integration With Hex Core Service

Intended Relationship

The RE indicators calculation service is not a replacement for hex-core-service.

The current intended split is:

  • hex-core-service: generic validation, registry access, and record persistence
  • RE indicators calculation service: RE-specific scoring and structured computation output

Preferred Flow

  1. A client or user-facing application obtains or assembles the relevant digital passport payload.
  2. This calculation service calls hex-core-service to validate the payload against the RE indicators model version being used.
  3. After delegated validation, this service computes the RE indicators result.
  4. The calculation response is then reused wherever needed in downstream records or models.

Supported Direction

The primary interaction pattern for this service is payload submission.

Record lookup through hex-core-service may be added as a secondary integration mode, but it is not the main API entry pattern.

Registry Constraint

Even when integrating with hex-core-service, this service should resolve only:

  • model family: re-indicators-specification
  • version: caller-selected tag

Validation Delegation

Validation is not intended to be reimplemented independently here.

Instead, this service calls:

POST /models/re-indicators-specification/versions/{version}:validate

on hex-core-service during computation.

Authentication Forwarding

When the incoming request carries:

Authorization: Bearer <token>

the service forwards that bearer token to hex-core-service for the delegated validation call.

Project Scope

Fixed Constraints

The following constraints currently define the scope of this service:

  • only the re-indicators-specification model family is in scope
  • the only user-selectable model dimension is the version tag
  • artifact resolution is hardwired to https://codeberg.org/CE-RISE-models/re-indicators-specification/raw/tag/pages-v{version}/generated/
  • SHACL artifacts remain the validation basis, but validation is delegated through hex-core-service
  • payload submission is the main compute input pattern
  • the primary deliverable is a containerized HTTP service
  • the API must be documented on this published pages site

Deliberate Non-Goals For Now

  • a generic multi-model calculation platform
  • a dedicated CLI-first workflow
  • project-local SDK generation