Aggregator Specification

Living Document,

Previous Versions:
Editors:
(Ghent University - imec)
(Ghent University - imec)
(Ghent University - imec)
(Ghent University - imec)
(KU Leuven Campus Kulak)
(Ghent University - imec)

CC0 To the extent possible under law, the editors have waived all copyright and related or neighboring rights to this work. In addition, as of 10 August 2026, the editors have made this specification available under the Open Web Foundation Agreement Version 1.0, which is available at https://www.openwebfoundation.org/the-agreements/the-owf-1-0-agreements-granted-claims/owfa-1-0. Parts of this work may be from another specification document. If so, those parts are instead covered by the license of that specification document.

Abstract

The Aggregator Protocol defines an HTTP interface for discovering aggregator deployments, registering aggregator instances, and managing services that execute data transformations. The protocol leverages OIDC and User-Managed Access (UMA) for authentication and authorization, enabling secure access to protected derived resources.

1. Introduction

This specification defines the Aggregator Protocol, an HTTP-based interface that lets a client create and manage Aggregator Instances and deploy Aggregator Services. Deployment interfaces are described using the Function Ontology (FnO) [FNO]; a service is deployed by referencing a deployment function and providing its input parameters. A deployed Service is a dcat:DataService that exposes datasets.

Clients start from the Aggregator Server Description at the server base URL to discover the management endpoint, supported management flows, and the server’s service catalog (§ 5 Aggregator Server Metadata). Using the management endpoint, a client creates (or manages) an Aggregator Instance (§ 6 Aggregator Management) and then follows the instance’s Aggregator Description to find the instance’s service collection and service catalog (§ 8.1 Aggregator Description and § 9 Aggregator Service Management).

Management operations are authenticated and authorized unless a specific management flow explicitly allows unauthenticated requests. This protocol integrates with OpenID Connect [OIDC-Core] for identity and uses UMA-style authorization [UMA] for protected resources, scopes, and tickets as described in § 7 Aggregator Security Model (Authentication & Authorization).

Servers MUST support JSON (application/json) where specified and MAY additionally provide semantically annotated RDF representations (e.g., JSON-LD or Turtle) via HTTP content negotiation. The Aggregator vocabulary (§ 10 Vocabulary) provides stable IRIs for classes and predicates used throughout the specification.

2. Definitions

This section defines terminology used throughout this specification. Where applicable, terms are aligned with external specifications such as WebID Profiles [WEBID-PROFILE], OpenID Connect (OIDC) [OIDC-Core], OAuth 2.0 [RFC6749], and User-Managed Access (UMA) [UMA].

2.1. Core Roles and Components

2.2. Identity, Authorization, and Tokens

2.3. Namespaces

The following namespace prefixes are used throughout this specification and SHOULD appear in RDF serializations (e.g., Turtle, JSON-LD contexts):

3. Architecture & Resource Model

This section describes the high-level architecture of an Aggregator deployment and the resource model exposed by this specification. It connects the terminology in § 2 Definitions to the endpoint definitions in later sections.

3.1. Resource Types

This specification defines HTTP resources at three levels:

To facilitate discovery, all resources MUST expose a hierarchy of HTTP Link headers ([Web-Linking]), referencing the base URL of each level they belong to:

Each level therefore includes all Link relations required of the levels above it, in addition to its own.

3.2. Addressing and URL Discovery

An implementation MAY use either of the following instance addressing patterns:

Clients SHOULD treat URLs advertised by Aggregator Server and Aggregator Instance metadata as authoritative and SHOULD NOT construct resource URLs by string concatenation unless this specification explicitly fixes the path. Unless a path is explicitly fixed, the concrete URLs shown in this document serve as illustrative defaults; deployments MAY use different locations as long as the relevant metadata resources advertise the authoritative links.

3.3. Security Boundaries

All security requirements are defined in § 7 Aggregator Security Model (Authentication & Authorization). At a high level:

The aggregator and its clients SHOULD use secure transport (HTTPS) for all communication, and SHOULD use DPoP wherever possible to sender-constrain access tokens to the client. Aggregator endpoints intended for browser-based clients MUST support CORS. Unless the client and Aggregator are tightly coupled and deployed under the same origin, the server MUST answer OPTIONS preflight requests and include appropriate Access-Control-Allow-* headers for the methods and headers used by this specification. Implementations MAY restrict allowed origins to trusted client origins.

3.4. Example URL Layout (Non-normative)

This non-normative example illustrates one possible URL layout for the Aggregator Server, an Aggregator Instance, and a Service in a path-based deployment:

4. Aggregator Data Model

This section specifies the data model used to describe deployment functions, running Aggregator Services, and the datasets those services expose. By describing them as linked data, the model enables interoperable publication, discovery, and deployment of Aggregator Services.

This specification publishes a predefined JSON-LD context at https://w3id.org/aggregator/contexts/aggregator.jsonld that maps the terms used throughout this data model (including the aggr: vocabulary defined in § 10 Vocabulary and the external vocabularies it reuses, such as [FNO], [Data-Catalog], and [PROV-O]). JSON-LD representations of the resources defined in this section MAY reference this context using @context. Two additional contexts are published for the JSON documents that use specialized member names: https://w3id.org/aggregator/contexts/aggregator-server-description.jsonld for the § 5.1 Aggregator Server Description and https://w3id.org/aggregator/contexts/aggregator-description.jsonld for the § 8.1 Aggregator Description.

4.1. Deployment Function

A deployment function defines the interface for deploying an Aggregator Service using the Function Ontology [FNO]. It describes the information a client supplies in an aggr:ServiceRequest; it does not describe the functionality performed by the resulting service.

Each deployment function:

Each parameter:

The output:

The use of dct:conformsTo to describe the profile of a Service is under active development and may be formalized in a separate specification in the future.

Additional FnO metadata MAY be linked to a deployment function, such as an fno:Implementation using an fno:Mapping, or the algorithm it implements using fno:Algorithm as specified by [FNO].

@base <http://aggregator.example.org/service-catalog#> .
@prefix aggr: <https://w3id.org/aggregator#> .
@prefix fno: <https://w3id.org/function/ontology#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix dct: <http://purl.org/dc/terms/> .

<QueryViewDeployment>
  a                   fno:Function ;
  fno:name            "The SPARQL QueryView function"^^xsd:string ;
  dct:description     "Deploys a service that exposes a materialized SPARQL query view"^^xsd:string ;
  fno:expects         ( <QuerySource> <QueryString> ) ;
  fno:returns         ( <ServiceOutput> ) .

<QuerySource>
  a                   fno:Parameter ;
  fno:predicate       <source> ;
  fno:type            xsd:anyURI ;
  fno:required        "true"^^xsd:boolean .

<QueryString>
  a               fno:Parameter ;
  fno:predicate   <query> ;
  fno:type        xsd:string ;
  dct:conformsTo  <https://www.w3.org/TR/2013/REC-sparql11-query-20130321/> ;
  fno:required    "true"^^xsd:boolean .

<ServiceOutput>
  a               fno:Output ;
  fno:type        aggr:Service ;
  fno:predicate   <service> ;
  dct:conformsTo  <https://example.org/profiles/sparql-query-service> .

4.2. Service Catalog

A Service Catalog references all deployment functions made available on an Aggregator Server.

The Service Catalog:

@base <http://aggregator.example.org/deployments#> .
@prefix aggr: <https://w3id.org/aggregator#> .
@prefix dcat: <http://www.w3.org/ns/dcat#> .
@prefix dct: <http://purl.org/dc/terms/> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix fno: <https://w3id.org/function/ontology#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix foaf: <http://xmlns.com/foaf/0.1/>

<> a aggr:ServiceCatalog ;
    aggr:hasDeploymentFunction
      <QueryViewDeployment> ,
      <http://example.org/external/ExternalFunction> ;
    rdfs:seeAlso <http://example.org/external/ExternalFunction> .

4.3. Service

A deployed aggregator service is the running resource created from a service request and MUST be modelled as:

Furthermore, the service:

Each corresponding dataset:

A dataset that is exposed for consumption MUST reference at least one dcat:Distribution. A dataset that is not exposed for consumption is not required to have a distribution.

The corresponding distribution MUST be described as a dcat:Distribution, where each distribution:

This ensures that consumers can reliably discover and access the latest available aggregated results. Furthermore, Service descriptions MAY be semantically enriched to provide more detailed information about their outputs and capabilities. For example, use dct:accrualPeriodicity on the dataset to indicate the frequency of updates, or describe the service API using the Hydra Core Ontology ([Hydra]).

@base <https://aggregator.example.org/agg1/services/sparql-query-view-service#> .
@prefix server-deploy: <https://aggregator.example.org/deployments#> .
@prefix aggr: <https://w3id.org/aggregator#> .
@prefix dcat: <http://www.w3.org/ns/dcat#> .
@prefix prov: <http://www.w3.org/ns/prov#> .
@prefix dct: <http://purl.org/dc/terms/> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

<>
    a aggr:Service ;
    a dcat:DataService ;
    a prov:SoftwareAgent ;
    aggr:status "running" ;
    aggr:createdAt "2024-01-01T12:00:00Z"^^xsd:dateTime ;
    aggr:deploymentFunction server-deploy:QueryViewDeployment ;
    dct:conformsTo <https://w3id.org/aggregator#> ;
    dcat:servesDataset <#dataset> .

<#dataset>
    a dcat:Dataset ;
    dcat:distribution <#distribution-xml> ,
     <#distribution-json> .

<#distribution-xml>
    a dcat:Distribution ;
    dcat:mediaType <http://www.iana.org/assignments/media-types/application/sparql-results+xml> ;
    dcat:accessURL <https://aggregator.example.org/agg1/services/sparql-query-view-service/output> ;
    dcat:accessService <> .

<#distribution-json>
    a dcat:Distribution ;
    dcat:mediaType <http://www.iana.org/assignments/media-types/application/sparql-results+json> ;
    dcat:accessURL <https://aggregator.example.org/agg1/services/sparql-query-view-service/output> ;
    dcat:accessService <> .

4.4. Service Collection

A Service Collection describes the set of services currently exposed by an Aggregator Instance.

The Service Collection:

@base <http://aggregator.example.org/agg1/services> .
@prefix aggr: <https://w3id.org/aggregator#> .

<> a aggr:ServiceCollection ;
  aggr:hasService
    <http://aggregator.example.org/agg1/services/sparql-query-view-service> ,
    <http://aggregator.example.org/agg1/services/rml-mapper-service> .

4.5. Provenance Log

An Aggregator Service MAY link to an aggr:ProvenanceLog using aggr:provenanceLog. A Provenance Log MUST be described as an aggr:ProvenanceLog and MAY reference prov:Activity resources using aggr:hasActivity. The prov:Activity MUST link back to the service that it is associated with using prov:wasAssociatedWith.

5. Aggregator Server Metadata

This section describes the endpoints exposed by the Aggregator Server for discovery and metadata retrieval. Except for the Aggregator Server Description at the server base URL, implementations MUST expose the remaining endpoints at deployment-specific URLs; the server description document MUST include absolute URLs for each resource so that clients can discover them.

5.1. Aggregator Server Description

The Aggregator Server Description allows clients to discover the Aggregator Server’s endpoints and capabilities. This document MUST be available at the server base URL (i.e., {aggregator-server-url}/), MAY be accessible without authentication or MAY require an OpenID Connect (OIDC) ID Token depending on deployment policy, and MUST provide at least the following information. Each JSON member is paired with an RDF predicate from § 10 Vocabulary so the document can also be served as JSON-LD or other RDF formats using content negotiation based on [RFC9110]:

In semantically annotated representations, the Aggregator Server Description MUST state that the described resource has RDF type aggr:AggregatorServer (§ 10.1.3 aggr:AggregatorServer) (e.g., via @type in JSON-LD or a aggr:AggregatorServer in Turtle). Clients MAY rely on this type statement when consuming semantic representations.

management_endpoint (REQUIRED):

The value is a string containing the absolute URL of the Aggregator Management Endpoint (§ 6.1 Aggregator Management Endpoint); in the RDF representations, this member maps to the predicate aggr:managementEndpoint (§ 10.2.18 aggr:managementEndpoint).

supported_management_flows (REQUIRED):

The value is a JSON array of strings identifying the supported management flow tokens at management_endpoint; in the RDF representations, each entry maps to an aggr:supportedManagementFlow triple (§ 10.2.19 aggr:supportedManagementFlow) whose object is the corresponding flow class IRI.

Each member MUST be one of the management flow tokens defined in § 6.1 Aggregator Management Endpoint:

supported_management_request_formats (REQUIRED):

The value is a JSON array of strings identifying the supported request formats for the management_endpoint. Each entry MUST be a media type; in RDF representations, each entry maps to an aggr:managementRequestFormatSupported triple (§ 10.2.20 aggr:managementRequestFormatSupported). Servers MUST include either application/json or application/x-www-form-urlencoded or both.

version (REQUIRED):

The value is a string containing the semantic version ([SEMVER]) of the Aggregator specification that the server adheres to; in the RDF representations, this member maps to the predicate aggr:specVersion (§ 10.2.21 aggr:specVersion).

client_identifier (REQUIRED):

The value is a string containing the absolute URL of the Client ID Document (§ 5.2 Client ID Document); in the RDF representations, this member maps to the predicate aggr:clientIdentifier (§ 10.2.22 aggr:clientIdentifier).

service_catalog (REQUIRED):

The value is a string containing the absolute URL of the server-level Service Catalog (§ 5.3 Server-level Service Catalog); in the RDF representations, this member maps to the predicate aggr:serviceCatalog (§ 10.2.23 aggr:serviceCatalog).

{
  "@context": "https://w3id.org/aggregator/contexts/aggregator-server-description.jsonld",
  "aggregator_server_base_url": "https://aggregator.example/",
  "type": "AggregatorServer",
  "management_endpoint": "https://aggregator.example/registration",
  "supported_management_flows": [
    "provision",
    "authorization_code"
  ],
  "supported_management_request_formats": [
    "application/json",
    "application/x-www-form-urlencoded"
  ],
  "version": "1.0.0",
  "client_identifier": "https://aggregator.example/client.jsonld",
  "service_catalog": "https://aggregator.example/service-catalog"
}

5.2. Client ID Document

Endpoint that exposes the Client ID Document of the aggregator used for authorization. Servers MAY host this document at any URL; the client_identifier property in the Aggregator Server Description MUST contain the authoritative absolute URL. The Client ID Document MUST conform to the OAuth Client ID Metadata Document specification [Client-ID]. In the case for the aggregator, the redirect_uris property is OPTIONAL instead of REQUIRED, as multiple clients MAY create an Aggregator on the same Aggregator Server (depending on the implementation). Adding this property allows an Aggregator Server implementation to restrict which clients may create aggregators on the server.

5.3. Server-level Service Catalog

The Service Catalog is an RDF document whose base resource, identified by the document’s own retrieval URL, MUST be described as an aggr:ServiceCatalog (§ 4.2 Service Catalog). Resources referenced by the Service Catalog MAY either be included directly in the RDF document or hosted by the Aggregator Server in separate documents.

Aggregator servers MUST publish this catalog, at any deployment-specific URL of their choosing using the GET method. The URL MUST be advertised in the § 5.1 Aggregator Server Description via the service_catalog field. The catalog SHOULD support HTTP content negotiation, allowing clients to request different RDF serializations (e.g., Turtle, JSON-LD).

6. Aggregator Management

This section describes how Aggregator Instances are managed at the Aggregator Server level. Deployments define their own authorization policy for these endpoints, but they MUST require authenticated requests so the Aggregator provider can authorize a user to manage their aggregators. The tokens used in these requests (IDP_client_token) prove the identity of the user and the client (Client ID Document) used to access the Aggregator Server. Deployments MAY expose the same functionality at different paths, provided that the Aggregator Server Description advertises the authoritative URLs.

6.1. Aggregator Management Endpoint

This section specifies the behavior of the management_endpoint advertised by the Aggregator Server Description (§ 5.1 Aggregator Server Description). The endpoint supports creating Aggregator Instances, replacing the stored token set for an existing instance, and deleting an instance. If the management_flow isn’t none the endpoint SHOULD reject unauthenticated requests with 401 Unauthorized.

For error conditions, the server MUST respond with:

6.1.1. POST

Creates an Aggregator Instance or replaces the stored token set for an existing instance. The request body MUST use a content type listed in supported_management_request_formats. When using application/json, the body MUST be a JSON object. When using application/x-www-form-urlencoded, the body parameters MUST be encoded as form fields with the same member names. The request body MUST include the following members:

Depending on management_flow, additional members are defined:

6.1.2. GET

This method returns the list of Aggregator Instances created by the authenticated user. The server MUST respond with 200 OK and a JSON array containing zero or more Aggregator Description URLs (§ 8.1 Aggregator Description).

6.1.3. DELETE

Deletes an existing Aggregator Instance. The request body MUST use a content type listed in supported_management_request_formats. When using application/json, the body MUST be a JSON object. When using application/x-www-form-urlencoded, the body parameters MUST be encoded as form fields with the same member names. The request body MUST include the term aggregator whose value is the absolute URL of the Aggregator Instance base URL that dereferences to the Aggregator Description (§ 8.1 Aggregator Description). If deletion succeeds the server MUST respond with 204 No Content.

6.2. Aggregator Management Flows (Non-normative)

This section gives non-normative examples of how a client can use the management_endpoint to create, delete, and re-authenticate an Aggregator Instance.

6.2.1. Creation provision Flow

The provision flow allows clients to create an Aggregator with its own identity. This lets resource owners target access-control policies at the aggregator’s dedicated WebID instead of having the aggregator impersonate another user’s WebID.

1. Client starts flow with Aggregator Server

The client calls the management endpoint authenticated with its IDP_client_token.

POST /registration HTTP/1.1
Authorization: Bearer <IDP_client_token>
Content-Type: application/json

{
  "management_flow": "provision"
}

2. Aggregator Server provisions an account at an IDP

The Aggregator Server provisions an account at an IDP. This might be linked to a WebID document that conforms to the WebID Profile specification [WEBID-PROFILE]. Using the credentials of this account the Aggregator Server can perform a client credentials grant to obtain the IDP_aggregator_token (and accompanying refresh token) to authorize the aggregator acting under its own WebID.

3. Aggregator Server creates an aggregator

Using the obtained tokens, the Aggregator Server creates an aggregator linked to the user, and returns the aggregator description (§ 8.1 Aggregator Description). The aggregator SHOULD NOT give these tokens or credentials to the client.

HTTP/1.1 201 Created
Content-Type: application/json

{
  "aggregator": "https://aggregator.example/aggregators/agg-7890/",
  "subject": "https://aggregator.example/webid#me"
}

Or with a non-WebID subject:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "aggregator": "https://aggregator.example/aggregators/agg-7890/",
  "subject": "aggregator@example.org",
  "idp": "https://idp.example/"
}

6.2.2. Creation authorization_code Flow

The authorization_code flow allows clients to create an aggregator that acts on behalf of the end-user, but with a token that is scoped specifically for the aggregator. This flow follows the OAuth 2.0 Authorization Code grant [RFC6749] (https://datatracker.ietf.org/doc/html/rfc6749).

PlantUML Diagram

1. Client starts flow with Aggregator Server

The client begins by asking the Aggregator to bootstrap an authorization_code management flow and indicate which authorization server SHOULD be used. The Aggregator identifies the client application from the IDP_client_token and responds with the public parameters required for the OIDC authorization request.

POST /registration HTTP/1.1
Authorization: Bearer <IDP_client_token>
Content-Type: application/json

{
  "management_flow": "authorization_code",
  "authorization_server": "https://as.example"
}

1.2 Aggregator responds with public parameters

The Aggregator generates the PKCE verifier/challenge pair plus a random state, persists them together with the pending management flow, and returns only the public portions (aggregator_client_id, code_challenge, code_challenge_method, state) to the client application. The authorization_server value identifies the UMA Authorization Server (AS) that governs access to resources exposed by the Aggregator. The aggregator uses the IDP_client_token to identify the user’s IdP and Application Client ID Document for the subsequent OIDC exchange.

HTTP/1.1 201 Created
Content-Type: application/json

{
  "aggregator_client_id": "https://aggregator.example/client.jsonld",
  "code_challenge": "1uLSZp2...",
  "code_challenge_method": "S256",
  "state": "1eb7c8f5..."
}

2. Client sends the end-user through the IDP authorization endpoint

Using the information supplied by the Aggregator, the client constructs an authorization request against the IdP.

GET https://idp.example/authorize?
    response_type=code&
    client_id=https%3A%2F%2Faggregator.example%2Fclient.jsonld&
    redirect_uri=https%3A%2F%2Fapp.example%2Fcallback&
    scope=openid%20webid%20offline_access&
    code_challenge=1uLSZp2...&
    code_challenge_method=S256&
    state=1eb7c8f5...

2.1 IDP dereferences the Aggregator Client ID Document

If the IDP does not already have the aggregator_client_id registered, it dereferences the Aggregator’s Client ID Document to retrieve the client metadata (for example redirect URIs and other policy-required fields).

3. User authenticates and consents at the IDP

The IDP performs its usual login and consent screens, after which it issues an authorization_code tied to the Aggregator’s client.

4. IDP redirects the user agent back to the client’s redirect_uri

The IDP redirects the user agent back to the client application with the authorization code and the original state.

HTTP/1.1 302 Found
Location: https://app.example/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=1eb7c8f5...

5. Client posts the authorization code back to the Aggregator

The client sends the code, redirect URI, and echoed state to the management endpoint so the Aggregator can finish the flow.

POST /registration HTTP/1.1
Authorization: Bearer <IDP_client_token>
Content-Type: application/json

{
  "management_flow": "authorization_code",
  "code": "SplxlOBeZQQYbYS6WxSbIA",
  "redirect_uri": "https://app.example/callback",
  "state": "1eb7c8f5..."
}

5.1 Aggregator dereferences the client application’s Client ID Document

If no specific redirect URIs were given in the Client ID Document, the Aggregator dereferences the https://app.example/client.jsonld JSON-LD document to confirm the registered redirect URIs. The aggregator then verifies that the supplied redirect_uri belongs to that set and that the returned state matches the stored state.

5.2 Aggregator redeems the authorization code at the IDP token endpoint

POST /token HTTP/1.1
Host: idp.example
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <aggregator-client-auth>

grant_type=authorization_code&
code=SplxlOBeZQQYbYS6WxSbIA&
redirect_uri=https%3A%2F%2Fapp.example%2Fcallback&
client_id=https%3A%2F%2Faggregator.example%2Fclient.jsonld&
code_verifier=Hjs8...stored...

The IDP verifies the authorization_code, ensures the redirect_uri matches the original authorization request, and recomputes the PKCE challenge from the supplied code_verifier. If everything matches, it returns:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": "<IDP_aggregator_token>",
  "refresh_token": "<refresh_token>",
  "token_type": "Bearer",
  "expires_in": 3600
}

5.3 Aggregator finalizes the account and responds

Using the issued tokens, the Aggregator creates the aggregator account linked to the user and returns the aggregator description (§ 8.1 Aggregator Description).

HTTP/1.1 201 Created
Content-Type: application/json

{
  "aggregator": "https://aggregator.example/aggregators/agg-6780/"
}

6.2.3. Creation device_code Flow

The device_code flow allows headless components (for example CLI tools) to authenticate an Aggregator Instance by using the OAuth 2.0 Device Authorization Grant [RFC8628].

PlantUML Diagram

1. Client starts flow with Aggregator Server

The client calls the management endpoint authenticated with its IDP_client_token, indicating the authorization server that governs access to resources exposed by the Aggregator.

POST /registration HTTP/1.1
Authorization: Bearer <IDP_client_token>
Content-Type: application/json

{
  "management_flow": "device_code",
  "authorization_server": "https://as.example"
}

1.1 Aggregator Server requests device authorization from the IdP

The Aggregator determines the IdP from the IDP_client_token in the authorization header, and sends a device authorization request to the IdP’s device authorization endpoint.

POST /device_authorization HTTP/1.1
Host: idp.example
Content-Type: application/x-www-form-urlencoded
client_id=<aggregator-client-id>&
scope=openid%20webid%20offline_access

1.2 IdP responds with device authorization parameters

The IdP responds with the device authorization parameters, including the device_code, user_code, verification_uri, expires_in, and other optional parameters.

HTTP/1.1 200 OK
Content-Type: application/json
{
  "device_code": "device-code-xyz",
  "user_code": "WDJB-MJHT",
  "verification_uri": "https://idp.example/activate",
  "verification_uri_complete": "https://idp.example/activate?user_code=WDJB-MJHT",
  "expires_in": 600,
  "interval": 5
}

1.3 Aggregator Server returns device authorization parameters

The Aggregator securely stores the device_code and generates a random state value to track the pending management flow. It responds to the client with the state, user_code, verification_uri, expires_in, and the optional other parameters. The device_code is confidential and MUST NOT be returned to the client.

HTTP/1.1 201 Created
Content-Type: application/json

{
  "state": "state-abc",
  "user_code": "WDJB-MJHT",
  "verification_uri": "https://idp.example/activate",
  "verification_uri_complete": "https://idp.example/activate?user_code=WDJB-MJHT",
  "expires_in": 600,
  "interval": 5
}

2. User authorizes at the IdP

The client prompts the user to visit the verification URI and enter the user code to authorize access.

3. Client polls Aggregator Server

The client polls the management endpoint using the state value, waiting at least the returned interval (if provided) between polls. The Aggregator polls the IdP token endpoint using the stored device code until the user authorizes or the device code expires.

POST /registration HTTP/1.1
Authorization: Bearer <IDP_client_token>
Content-Type: application/json

{
  "management_flow": "device_code",
  "state": "state-abc"
}

If authorization is not yet complete, the Aggregator responds with 202 Accepted:

HTTP/1.1 202 Accepted

Once authorization succeeds, the Aggregator creates the Aggregator Instance and responds as for other successful create operations:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "aggregator": "https://aggregator.example/aggregators/agg-5670/"
}

Example server-side token polling (Non-normative)

While polling, the IdP can return an authorization-pending error:

POST /token HTTP/1.1
Host: idp.example
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:device_code&
device_code=GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "authorization_pending"
}

Once the user completes authorization, the IdP returns the token set:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": "<IDP_aggregator_token>",
  "refresh_token": "<refresh_token>",
  "token_type": "Bearer",
  "expires_in": 7200
}

6.2.4. Token Update Flow

This flow allows users to replace the stored access token and refresh token for an existing Aggregator Instance. This is not a refresh-token grant: even refresh tokens can expire, so the client repeats the original management flow to obtain a new set of tokens (and refresh tokens) for the Aggregator Instance.

The flow is the same as creating an Aggregator Instance but an aggregator member is provided in the start request. The exact steps depend on the management_flow used when creating the Aggregator Instance. For example, for the authorization_code flow:

POST /registration HTTP/1.1
Authorization: Bearer <IDP_client_token>
Content-Type: application/json
{
    "management_flow": "authorization_code",
    "aggregator": "https://aggregator.example/aggregators/agg-7890/"
}

6.2.5. Aggregator Listing Flow

This flow allows users to list Aggregator Instances by sending a GET request to the management_endpoint.

GET /registration HTTP/1.1
Authorization: Bearer <IDP_client_token>

HTTP/1.1 200 OK
Content-Type: application/json

[
  "https://aggregator.example/aggregators/agg-7890/",
  "https://aggregator.example/aggregators/agg-9012/"
]

6.2.6. Aggregator Deletion Flow

This flow allows users to delete an existing Aggregator Instance by sending a DELETE request to the management_endpoint with the aggregator member.

DELETE /registration HTTP/1.1
Authorization: Bearer <IDP_client_token>
Content-Type: application/json
{
    "aggregator": "https://aggregator.example/aggregators/agg-7890/"
}

7. Aggregator Security Model (Authentication & Authorization)

This section describes how the Aggregator handles authentication and authorization for:

The Aggregator relies on the Authorization for Data Spaces (A4DS) specification [A4DS] to authenticate participants and authorize access to resources. For streaming or non-HTTP interfaces, the Aggregator MAY additionally use the Service Authorization for Data Spaces (SA4DS) specification [SA4DS]. All Aggregator instance endpoints are protected using User-Managed Access (UMA) [UMA].

The following terms are used throughout this section:

NOTE: The behavior described in this section extends the [A4DS] specification.

7.1. Upstream Access

The Aggregator MUST obtain upstream access tokens following the UMA grant flow defined in [A4DS]. When the UAS requests proof of identity, the Aggregator MUST present the ID token (IDP_aggregator_token) obtained during aggregator creation (§ 6 Aggregator Management) as its identity claim, with claim_token_format http://openid.net/specs/openid-connect-core-1_0.html#IDToken.

PlantUML Diagram

7.2. Client Access

All instance-level resources of an Aggregator MUST be registered at the AAS, following the model defined in [A4DS], with the scopes necessary for their protection determined by the implementation.

Each implementation SHOULD document:

When the Aggregator receives a request without a valid Requesting Party Token (RPT), or with an RPT that does not grant sufficient permissions, it MUST request a UMA ticket from the AAS and return a 401 Unauthorized response containing that ticket. The Client MUST present the ticket to the AAS and satisfy the applicable claims-based policies to obtain an RPT, following the UMA grant flow defined in [A4DS]. The Aggregator MUST validate or introspect the RPT before serving the derived resource. The Aggregator MAY implement SA4DS for streaming or non-HTTP interfaces.

PlantUML Diagram

7.3. Advanced Features

The features in this section extend the baseline flows above. They MAY be implemented by conforming Aggregator Services and their associated Authorization Servers.

7.3.1. Transformation Claims

When the UAS requires details about the intended data transformation before granting access, the Aggregator MAY include a transformation description as a claim token in the UMA grant request. The claim_type for a transformation description MUST be https://w3id.org/aggregator#transformation-description. The claim_token_format MUST identify the RDF serialization of the description as a URI (e.g., http://www.w3.org/ns/formats/Turtle). If the UAS requires this claim and the Aggregator has not provided one, the UAS MUST respond with a UMA need_info error and a required_claims entry as defined in [A4DS]. If the transformation description or its associated catalog entry is dereferenceable by the UAS, the Aggregator MAY provide a URI reference rather than embedding the description inline.

This extends the upstream access flow between steps 2 and 3:

PlantUML Diagram

2.1 UAS requests transformation claim

{
  "error": "need_info",
  "ticket": "tkt2-URS-xyz",
  "required_claims": [
    {
      "claim_type": "https://w3id.org/aggregator#transformation-description",
      "friendly_name": "Intended data transformation",
      "claim_token_format": [
        "http://www.w3.org/ns/formats/Turtle",
        "http://www.w3.org/ns/formats/JSON-LD"
      ],
      "claim_description": "Describe the transformation that will be executed on the requested data (e.g. query, mapping, model, or workflow reference)."
    }
  ]
}

2.2 Aggregator resubmits with transformation claim

POST /token HTTP/1.1
Host: upstream.as.example.org
Content-Type: application/json

{
    "grant_type": "urn:ietf:params:oauth:grant-type:uma-ticket",
    "ticket": "tkt2-URS-xyz",
    "claim_token": "<transformation_description>",
    "claim_token_format": "http://www.w3.org/ns/formats/Turtle"
}

7.3.2. Access Delegation via Derivation Resource Identifiers

Access delegation allows upstream data owners to retain policy control over who MAY access derived resources after those resources have been transformed and republished by an Aggregator Service. It operates through a derivation_resource_id issued by the UAS that binds the upstream resource, the intended transformation, and the resulting derived resource. Clients wishing to access a derived resource MUST demonstrate to the AAS that they also hold access to the upstream resources it was derived from.

7.3.2.1. Upstream: Requesting Derivation Creation Access

When the Aggregator intends to create a derived resource, it MUST include the scope urn:knows:uma:scopes:derivation-creation in the UMA token request to the UAS. If the URS is itself an Aggregator Service, the same scope MUST be included in that nested request as well.

If the UAS grants access for derivation creation, it MUST include a derivation_resource_id and a management_access_token as top-level members in the token response alongside the standard OAuth 2.0 parameters. The derivation_resource_id is a stable identifier string that binds the upstream resource and transformation to the derived resource the Aggregator will create. If the Aggregator does not receive a derivation_resource_id, it MUST NOT use the upstream resource to create derived resources.

If the Aggregator previously obtained a derivation_resource_id for the same upstream resource and transformation, it SHOULD include it as a hint in the token request. The UAS SHOULD reuse it if the hint is still valid and bound to the authenticated Aggregator and resource; otherwise it SHOULD ignore the hint and issue a new identifier.

The management_access_token is an object with access_token and token_type fields that allows the Aggregator Service to manage the lifecycle of the derivation_resource_id at the UAS through the resource registration endpoint defined in [A4DS]. Authorization Servers MUST only permit a management_access_token to be used for inspecting or modifying the derivation_resource_id resource linked to it, and MUST NOT permit it to create new resources. If the management_access_token is no longer valid, the Aggregator MAY obtain a new one by repeating the token request including the same derivation_resource_id.

After obtaining the derivation_resource_id, the Aggregator SHOULD update the corresponding resource entry on the UAS to include at minimum the resource_scopes of the derived resource, and SHOULD also include its name, description, and icon_uri. This allows the UAS to validate scope requests from Clients and apply policies accordingly.

The Aggregator MUST update the resource registration of the derived resource at the AAS to include a derived_from entry containing the issuer (the UAS) and derivation_resource_id. The AAS MUST expire any previously issued access tokens for that derived resource upon this update. The Aggregator SHOULD only begin serving the derived resource after this AAS registration update has succeeded.

If access to the upstream resource is revoked for the Aggregator, the UAS MUST also revoke all associated derivation_resource_id identifiers and their related tokens. When a derived resource is no longer in use, the Aggregator SHOULD remove the derived_from entry at the AAS, MAY expire previous access tokens, and SHOULD delete the derivation_resource_id at the UAS using the management_access_token.

This extends the upstream access flow after step 2:

PlantUML Diagram

2.1 UAS returns access token with derivation resource identifier

{
    "access_token": "<upstream_access_token>",
    "token_type": "Bearer",
    "derivation_resource_id": "handle-id-1",
    "management_access_token": {
        "access_token": "<management_access_token>",
        "token_type": "Bearer"
    }
}

3. Aggregator updates derivation_resource_id metadata on UAS

PUT /derivation-resources/handle-id-1 HTTP/1.1
Host: upstream.as.example.org
Authorization: Bearer <management_access_token>
Content-Type: application/json

{
  "type": "https://agg.example.org/derivation-result",
  "name": "Derived Resource 123",
  "description": "<transformation_description>",
  "icon_uri": "https://agg.example.org/icons/derived-resource-123.png",
  "resource_scopes": [
    "urn:knows:uma:scopes:read"
  ]
}

4. Aggregator updates resource registration at AAS with derived_from entry

{
  "name": "Derived Resource 123",
  "derived_from": [
    {
      "issuer": "https://upstream.as.example.org",
      "derivation_resource_id": "handle-id-1"
    }
  ],
  "resource_scopes": [
    "urn:knows:uma:scopes:read"
  ]
}
7.3.2.2. Client Access to Delegated Derived Resources

When a derived resource has a derived_from entry in its AAS registration, the AAS MUST enforce that Clients demonstrate access to each listed upstream resource before issuing an RPT.

If the Client presents a ticket for such a resource without the required upstream claim tokens, the AAS MUST respond with a need_info error. The required_claims array MUST contain one entry per upstream dependency, each with:

The Client MUST request an access token from each issuer listed in required_claims, using a UMA permissions request with resource_id set to derivation_resource_id and resource_scopes as specified. The Client MUST then present each obtained upstream access token as a claim token to the AAS with claim_token_format urn:ietf:params:oauth:token-type:access_token. The AAS MUST validate each presented upstream access token with its corresponding UAS before issuing an RPT. The Aggregator SHOULD verify that the derivation_resource_id associated with the derived resource remains valid at the UAS before serving it, using the management_access_token on the resource registration endpoint defined in [A4DS].

This extends the client access flow between steps 2 and 3:

PlantUML Diagram

2.1 AAS responds with need_info requesting upstream access token

{
  "error": "need_info",
  "ticket": "tkt-2",
  "required_claims": [
    {
      "claim_type": "https://w3id.org/aggregator#derivation-access",
      "claim_token_format": "urn:ietf:params:oauth:token-type:access_token",
      "issuer": "https://upstream.as.example.org",
      "derivation_resource_id": "handle-id-1",
      "resource_scopes": [ "urn:knows:uma:scopes:read" ]
    }
  ]
}

2.2 Client requests upstream access token from UAS

{
  "grant_type": "urn:ietf:params:oauth:grant-type:uma-ticket",
  "permissions": [
    {
      "resource_id": "handle-id-1",
      "resource_scopes": [ "urn:knows:uma:scopes:read" ]
    }
  ],
  "claim_token": "<IDP_client_token>",
  "claim_token_format": "http://openid.net/specs/openid-connect-core-1_0.html#IDToken"
}

2.3 UAS returns upstream access token

{
  "access_token": "RPT-uas-xyz"
}

2.4 Client resubmits with upstream access token as claim

{
  "grant_type": "urn:ietf:params:oauth:grant-type:uma-ticket",
  "ticket": "tkt-2",
  "claim_token_format": "urn:ietf:params:oauth:token-type:access_token",
  "claim_token": "RPT-uas-xyz"
}

2.5 AAS validates upstream token and issues RPT

The AAS validates the upstream access token with the UAS. If all policy checks succeed, it issues an RPT. The Client then proceeds as in the baseline client access flow from step 3.

8. Aggregator Metadata

This endpoint provides metadata about the Aggregator Instance. Deployments MAY choose arbitrary paths for instance-level endpoints. The Aggregator Metadata representation MUST include absolute URLs for those resources (e.g., the service_catalog and service_collection_endpoint fields) so clients can discover the deployment-specific layout.

8.1. Aggregator Description

The Aggregator Metadata resource (aggregator-url) allows clients to retrieve the current status of their aggregator. This endpoint MUST be guarded by the authentication and authorization mechanisms described in the § 7 Aggregator Security Model (Authentication & Authorization). It MUST be accessible as JSON using application/json and MAY additionally expose semantically annotated RDF representations (for example JSON-LD or Turtle) using HTTP content negotiation based on [RFC9110].

The endpoint MUST return at least the following information about the aggregator, but additional fields MAY be included as needed. Each field SHOULD be expressed using the RDF properties defined in § 10 Vocabulary so the document MAY be served as JSON-LD or other RDF formats. In semantically annotated representations, the Aggregator Description MUST state that the described resource has RDF type aggr:Aggregator (§ 10.1.1 aggr:Aggregator) (e.g., via @type in JSON-LD or a aggr:Aggregator in Turtle). Clients MAY rely on this type statement when consuming semantic representations.

id (OPTIONAL):

The value is a string containing the absolute URL that identifies the Aggregator Instance (typically the instance base URL itself); in the RDF representations, this is the RDF subject (i.e., @id) of the aggr:Aggregator resource (§ 10.1.1 aggr:Aggregator).

created_at (REQUIRED):

The value is a string timestamp (recommended: xsd:dateTime lexical form, e.g., RFC 3339 [RFC3339]); in the RDF representations, this member maps to the predicate aggr:createdAt (§ 10.2.1 aggr:createdAt).

login_status (REQUIRED):

The value is a boolean that indicates whether the stored token set for the aggregator is currently valid; in the RDF representations, this member maps to the predicate aggr:loginStatus (§ 10.2.2 aggr:loginStatus).

token_expiry (OPTIONAL):

The value is a string timestamp indicating when the aggregator’s access token will expire (recommended: xsd:dateTime lexical form, e.g., RFC 3339 [RFC3339]); in the RDF representations, this member maps to the predicate aggr:tokenExpiry (§ 10.2.3 aggr:tokenExpiry).

service_catalog (REQUIRED):

The value is a string containing the absolute URL of the instance’s Service Catalog (§ 8.2 Instance-level Service Catalog); in the RDF representations, this member maps to the predicate aggr:serviceCatalog (§ 10.2.23 aggr:serviceCatalog).

service_collection_endpoint (REQUIRED):

The value is a string containing the absolute URL of the instance’s Service Collection to create and fetch the Aggregator Services (§ 9.1 Service Collection Endpoint); in the RDF representations, this member maps to the predicate aggr:serviceCollectionEndpoint (§ 10.2.4 aggr:serviceCollectionEndpoint).

This document MAY be the WebID of the Aggregator Instance when the provision flow § 6.2.1 Creation provision Flow was used. In that case this document MUST be an RDF document that conforms to the WebID Profile specification [WEBID-PROFILE].

{
  "@context": "https://w3id.org/aggregator/contexts/aggregator-description.jsonld",
  "aggregator_base_url": "https://aggregator.example/aggregators/agg-7890/",
  "type": "Aggregator",
  "created_at": "2025-12-17T17:20:00Z",
  "login_status": true,
  "token_expiry": "2025-12-17T18:20:00Z",
  "service_catalog": "https://aggregator.example/aggregators/agg-7890/service-catalog",
  "service_collection_endpoint": "https://aggregator.example/aggregators/agg-7890/services",
  "oidcIssuer": "https://issuer.example/"
}

8.2. Instance-level Service Catalog

This endpoint is the instance-level extension of the server-level Service Catalog defined in § 5.3 Server-level Service Catalog. It allows the Aggregator Server to make certain deployment functions available only to specific Aggregator instances by curating the catalog’s contents per instance.

Aggregator servers MUST publish this catalog at a deployment-specific URL of their choosing. This URL MUST be advertised in the § 8.1 Aggregator Description via the service_catalog field. The endpoint MUST follow the same content negotiation rules, and other requirements, as the server-level Service Catalog. Resources referenced by this Instance-Level Service Catalog MAY either be included directly in the RDF document or hosted by the Aggregator Server in separate documents. This Instance-Level Service Catalog, along with each resource referenced by it, MUST be protected using the § 7 Aggregator Security Model (Authentication & Authorization).

9. Aggregator Service Management

This section describes how users manage services deployed on an aggregator.

The Service Collection endpoint (§ 9.1 Service Collection Endpoint), which allows clients to:

Each deployed service MUST expose its own Service Description endpoint (§ 9.2 Service Description Endpoint), which allows clients to:

All endpoints described in this section MUST be protected using the authentication and authorization mechanisms defined in § 7 Aggregator Security Model (Authentication & Authorization).

9.1. Service Collection Endpoint

The location of this endpoint MUST be advertised in the Aggregator Description (§ 8.1 Aggregator Description) using the service_collection_endpoint field. Clients MUST treat the advertised URL as authoritative and MUST NOT assume a fixed path. Examples shown in this section use https://aggregator.example/agg1/services for illustration purposes only.

9.1.1. Deploying a Service

The Service Collection Endpoint MUST allow POST requests to deploy a new service.

The Service Collection Endpoint MAY allow POST requests to deploy new services. The supported content types MUST be advertised via the Accept-Post header defined in [LDP]. The POST request to deploy a new services MUST be authorized with the create scope on the Service Collection Endpoint.

The request body MAY allow POST requests to deploy new services. The supported content types MUST be advertised via the Accept-Post header defined in [LDP]. If the request body is a JSON-LD payload, it MUST use at least the predefined JSON-LD context https://w3id.org/aggregator/contexts/aggregator.jsonld, representing an aggr:ServiceRequest. The aggr:ServiceRequest:

The Service Request MAY be identified by a blank node or a URI indicating the desired Service endpoint location. The Aggregator MAY ignore the requested URI and assign its own. If the requested URI is syntactically invalid or not permitted, the server MUST respond with 400 Bad Request. If the requested URI is valid but already in use, the server MUST respond with 409 Conflict.

Upon successful processing, the Aggregator MUST:

  1. Invoke the deployment function identified by deploymentFunction with the inputs from the Service Request.

  2. Deploy the resulting Service and expose a Service Description Endpoint § 9.2 Service Description Endpoint, describing it according to the data model in § 4.3 Service. The Service description MUST reference the deployment function using aggr:deploymentFunction.

  3. Update the Service Collection and its associated ETag.

  4. Register the Service Description Endpoint as a UMA resource at the Authorization Server, advertising at least the read, update, and delete scopes.

  5. Register each distinct Service output endpoint URL as an UMA resource.

  6. Respond with 201 Created, including the Service description (as defined in § 4.3 Service) in the response body and a Location header identifying the Service Description Endpoint.

Error Responses:

The following example depicts a request that invokes the QueryViewDeployment deployment function.

POST https://aggregator.example/agg1/services HTTP/1.1
Host: aggregator.example
Content-Type: application/ld+json

{
    "@context": [
        "https://w3id.org/aggregator/contexts/aggregator.jsonld",
        {
            "query": "https://aggregator.example/deployments#query",
            "source": "https://aggregator.example/deployments#source"
        }
    ],
    "@id": "https://aggregator.example/agg1/services/query-view-service/",
    "@type": "ServiceRequest",
    "deploymentFunction": "https://aggregator.example/deployments#QueryViewDeployment",
    "implements": "https://aggregator.example/deployments#QueryViewIncremunica",
    "query": "SELECT * WHERE { ?s ?p ?o }",
    "source": "http://example.org/source"
}

9.1.2. Service Discovery

The Service Collection Endpoint MUST expose an RDF document whose base resource, identified by the document’s own retrieval URL, MUST be described as an aggr:ServiceCollection (§ 4.4 Service Collection). The endpoint SHOULD support HTTP content negotiation to allow clients to request different RDF serializations (e.g., Turtle, JSON-LD) of the RDF Document.

HEAD

Enables clients to detect changes to the collection without retrieving the full representation. The server MUST respond with:

  • 200 OK

  • An ETag header whose value changes whenever a service is added to or removed from the collection.

GET

Returns the service collection RDF Document. The server MUST respond with:

  • 200 OK

  • The same ETag value that would be returned in response to a HEAD request

  • The serialized service collection in the body

9.2. Service Description Endpoint

The Service Description Endpoint MUST expose the § 4.3 Service. It is also used to delete the corresponding service. This endpoint SHOULD support HTTP content negotiation as defined in [RFC9110].

GET

Retrieves the service description (as defined in § 4.3 Service).

  • The server MUST respond with 200 OK.

DELETE

Deletes a running Aggregator Service.

  • Upon successful processing, the Aggregator MUST:

    1. Stop and remove the running service from the Aggregator.

    2. Update the Service Collection and its associated ETag.

    3. Delete the corresponding UMA resources at the Authorization Server.

    4. Respond with either 200 OK or 204 No Content.

  • If the service does not exist, the Aggregator SHOULD respond with 404 Not Found.

Next to the GET and DELETE methods, the server MAY support:

PATCH

Updates the service description (as defined in § 4.3 Service).

  • The server MUST respond with 200 OK and include the updated service description in the response body.

  • If the service does not exist, the Aggregator SHOULD respond with 404 Not Found.

  • If the server supports PATCH, it MUST advertise the supported patch document formats using the HTTP Accept-Patch header.

  • If the request Content-Type is not a supported patch document format, the server MUST respond with 415 Unsupported Media Type.

  • If the request is syntactically malformed or semantically invalid, the server MUST respond with 400 Bad Request.

  • If the request is valid but the service fails to update, the server MUST respond with 500 Internal Server Error.

PUT

Replaces the service description (as defined in § 4.3 Service).

  • The server MUST respond with 200 OK and include the updated service description in the response body.

  • If the service does not exist, the Aggregator SHOULD respond with 404 Not Found.

  • If the request is syntactically malformed or semantically invalid, the server MUST respond with 400 Bad Request.

  • If the request is valid but the service fails to update, the server MUST respond with 500 Internal Server Error.

When the server supports PATCH or PUT, it SHOULD NOT allow the user to remove or modify values that are managed by the Aggregator itself. This includes at least the service identifier, the RDF types of the service, aggr:createdAt, aggr:status, aggr:statusDetail, dcat:servesDataset, and dcat:distribution. If a PATCH or PUT request attempts to remove or modify such values, the server SHOULD respond with 400 Bad Request.

9.2.1. Service Output Endpoints

Each Service Output Endpoint MUST be hosted at the same URL as the one referenced via dcat:accessURL in a corresponding service dcat:Distribution. Each Service Output Endpoint is the access interface for that distribution. It is distinct from the dcat:Dataset resource identified in the service description and MUST NOT itself be interpreted as the dataset.

10. Vocabulary

The Aggregator vocabulary is defined in the aggr: namespace (https://w3id.org/aggregator#). The following classes and properties are used throughout this specification.

10.1. Classes

10.1.1. aggr:Aggregator

Describes an Aggregator Instance (its base URL is the Aggregator Description resource).

type: rdfs:Class
subClassOf: schema:Service
subClassOf: foaf:Agent

10.1.2. aggr:Service

Represents a configured Aggregator Service that can be created, inspected, and removed via the Service Management API (e.g., /services/{service_id}).

type: rdfs:Class
subClassOf: prov:SoftwareAgent, dcat:DataService

10.1.3. aggr:AggregatorServer

Describes the Aggregator Server Description document that advertises discovery metadata.

type: rdfs:Class
subClassOf: schema:Service

10.1.4. aggr:ServiceCollection

Describes the service collection resource (e.g., /services).

type: rdfs:Class
subClassOf: schema:Collection, hydra:Collection

10.1.5. aggr:ServiceCatalog

Describes a service catalog resource that lists the deployment functions supported by an Aggregator Server (and optionally instance-specific deployment functions).

type: rdfs:Class
subClassOf: schema:Collection, hydra:Collection

10.1.6. aggr:ProvenanceLog

Describes a collection of provenance activities associated with a running Aggregator Service.

type: rdfs:Class
subClassOf: schema:Collection, hydra:Collection

10.1.7. aggr:ServiceRequest

Describes a request to deploy an Aggregator Service on an Aggregator

type: rdfs:Class

10.1.8. aggr:ManagementFlow

Describes a management flow supported by an Aggregator Server. This specification models each flow as an RDF class so that aggr:supportedManagementFlow can be semantically annotated by referencing the relevant flow class (e.g., aggr:AuthorizationCodeFlow).

type: rdfs:Class
subClassOf: rdfs:Class

10.1.9. aggr:NoAuthFlow

Management flow where the Aggregator Instance does not authenticate and only accesses public resources.

type: rdfs:Class
subClassOf: aggr:ManagementFlow

10.1.10. aggr:ProvisionFlow

Management flow where the Aggregator Server provisions an Aggregator Instance with its own identity.

type: rdfs:Class
subClassOf: aggr:ManagementFlow

10.1.11. aggr:AuthorizationCodeFlow

Management flow based on OAuth 2.0 Authorization Code [RFC6749] (https://datatracker.ietf.org/doc/html/rfc6749) (via OpenID Connect), where the Aggregator acts on behalf of an end-user with a token scoped to the Aggregator.

type: rdfs:Class
subClassOf: aggr:ManagementFlow

10.1.12. aggr:DeviceCodeFlow

Management flow based on OAuth 2.0 Device Authorization Grant [RFC8628].

type: rdfs:Class
subClassOf: aggr:ManagementFlow

10.2. Properties

10.2.1. aggr:createdAt

Timestamp when an aggr:Aggregator or aggr:Service was created.

type: rdf:Property
domain: aggr:Aggregator, aggr:Service
range: xsd:dateTime

10.2.2. aggr:loginStatus

Indicates whether the stored token set for an aggr:Aggregator is currently valid.

type: rdf:Property
domain: aggr:Aggregator
range: xsd:boolean

10.2.3. aggr:tokenExpiry

Timestamp when the current access token for an aggr:Aggregator will expire.

type: rdf:Property
domain: aggr:Aggregator
range: xsd:dateTime

10.2.4. aggr:serviceCollectionEndpoint

Links an aggr:Aggregator to its service collection endpoint.

type: rdf:Property
domain: aggr:Aggregator
range: xsd:anyURI

10.2.5. aggr:hasService

Links an aggr:ServiceCollection to the aggr:Service instances it advertises.

type: rdf:Property
domain: aggr:ServiceCollection
range: aggr:Service

10.2.6. aggr:hasDeploymentFunction

Links an aggr:ServiceCatalog to a supported fno:Function that deploys one or more Aggregator Services.

type: rdf:Property
domain: aggr:ServiceCatalog
range: fno:Function

10.2.7. aggr:hasAlgorithm

Links an aggr:ServiceCatalog to an algorithm it supports.

type: rdf:Property
domain: aggr:ServiceCatalog
range: fno:Algorithm

10.2.8. aggr:hasMapping

Links an aggr:ServiceCatalog to a mapping it supports.

type: rdf:Property
domain: aggr:ServiceCatalog
range: fno:Mapping

10.2.9. aggr:status

Provides the lifecycle phase of an aggr:Service (values such as running, stopped, or error).

type: rdf:Property
domain: aggr:Service
range: xsd:string

10.2.10. aggr:statusDetail

Provides a human-readable explanation of the current aggr:Service status (for example, a stop reason or error message).

type: rdf:Property
domain: aggr:Service
range: xsd:string

10.2.11. aggr:deploymentFunction

Links a service request and its resulting service to the FnO function used to deploy the service. The deployment function describes service creation and does not necessarily describe functionality performed by the deployed service.

type: rdf:Property
domain: aggr:Service, aggr:ServiceRequest
range: fno:Function

10.2.12. aggr:implements

Provides the implementation used by an aggr:Service to perform its transformation.

type: rdf:Property
domain: aggr:Service, aggr:ServiceRequest
range: fno:Implementation

10.2.13. aggr:fromAggregator

References the base URL of the aggr:Aggregator an Aggregator Instance (or Aggregator Service) resource belongs to. Used as an HTTP Link header relation ([Web-Linking]) to discover the enclosing Aggregator Instance.

type: rdf:Property
domain: rdfs:Resource
range: aggr:Aggregator

10.2.14. aggr:fromServer

References the base URL of the aggr:AggregatorServer an Aggregator Server, Aggregator Instance, or Aggregator Service resource belongs to. Used as an HTTP Link header relation ([Web-Linking]) to discover the enclosing Aggregator Server.

type: rdf:Property
domain: rdfs:Resource
range: aggr:AggregatorServer

10.2.15. aggr:fromService

References the base URL of the aggr:Service an Aggregator Service resource belongs to. Used as an HTTP Link header relation ([Web-Linking]) to discover the enclosing Aggregator Service. It MAY also be used to link a service output dcat:Distribution to the aggr:Service that exposes it.

type: rdf:Property
domain: rdfs:Resource
range: aggr:Service

10.2.16. aggr:provenanceLog

Links an aggr:Service to its provenance log.

type: rdf:Property
domain: aggr:Service
range: aggr:ProvenanceLog

10.2.17. aggr:hasActivity

Links an aggr:ProvenanceLog to an activity it includes.

type: rdf:Property
domain: aggr:ProvenanceLog
range: prov:Activity

10.2.18. aggr:managementEndpoint

Links an aggr:AggregatorServer to its management endpoint.

type: rdf:Property
domain: aggr:AggregatorServer
range: xsd:anyURI

10.2.19. aggr:supportedManagementFlow

Lists the management flows advertised by an aggr:AggregatorServer.

type: rdf:Property
domain: aggr:AggregatorServer
range: rdfs:Class (expected to be an aggr:ManagementFlow class)

10.2.20. aggr:managementRequestFormatSupported

Lists the supported request formats for an aggr:AggregatorServer management endpoint.

type: rdf:Property
domain: aggr:AggregatorServer
range: xsd:string

10.2.21. aggr:specVersion

States which version of this specification an aggr:AggregatorServer implements.

type: rdf:Property
domain: aggr:AggregatorServer
range: xsd:string

10.2.22. aggr:clientIdentifier

Links an aggr:AggregatorServer to its Client ID Document.

type: rdf:Property
domain: aggr:AggregatorServer
range: xsd:anyURI

10.2.23. aggr:serviceCatalog

References the service catalog of an aggr:Aggregator (its instance-level service catalog) or an aggr:AggregatorServer (its server-level service catalog).

type: rdf:Property
domain: aggr:Aggregator, aggr:AggregatorServer
range: aggr:ServiceCatalog

10.3. Claim Types

10.3.1. aggr:transformation-description

Identifier for the UMA claim_type used to request or provide a transformation description.

type: rdfs:Resource

Claim tokens of this type MUST be RDF descriptions of the intended transformation (for example an fno:Execution or a reference to a service catalog entry). Acceptable claim_token_format values are URIs identifying RDF serializations (such as http://www.w3.org/ns/formats/Turtle and http://www.w3.org/ns/formats/JSON-LD).

10.3.2. aggr:derivation-access

Identifier for the UMA claim_type used to request or provide upstream access tokens for derived resources.

type: rdfs:Resource

Claim tokens of this type MUST be access tokens issued by the upstream Authorization Server for the derivation_resource_id referenced in the claim request.

Conformance

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

References

Normative References

[A4DS]
Authorization for Data Spaces (A4DS). URL: https://spec.knows.idlab.ugent.be/A4DS/L1/latest/
[Client-ID]
Aaron Parecki; Emelia Smith. OAuth Client ID Metadata Document. 10 January 2025. Internet-Draft. URL: https://datatracker.ietf.org/doc/draft-parecki-oauth-client-id-metadata-document/
[Data-Catalog]
Data Catalog Vocabulary. URL: https://www.w3.org/TR/vocab-dcat-3/
[FNO]
Function Ontology (FnO). URL: https://w3id.org/function/spec/
[Hydra]
Hydra Core Vocabulary. URL: https://www.hydra-cg.com/spec/latest/core/
[LDP]
Steve Speicher; John Arwe; Ashok Malhotra. Linked Data Platform 1.0. URL: https://www.w3.org/2012/ldp/hg/ldp.html
[OIDC-Core]
OpenID Connect Core 1.0. URL: https://openid.net/specs/openid-connect-core-1_0.html
[PROV-O]
The Provenance Ontology. URL: https://www.w3.org/TR/prov-o/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
[SA4DS]
Service Authorization for Data Spaces (SA4DS). URL: https://solid.github.io/service-authorization-for-data-spaces/
[SEMVER]
Semantic Versioning 2.0.0. URL: https://semver.org/
[UMA]
User-Managed Access (UMA) 2.0. URL: https://docs.kantarainitiative.org/uma/rec-uma-core.html
[Web-Linking]
Web Linking. URL: https://www.rfc-editor.org/rfc/rfc8288
[WEBID-PROFILE]
WebID Profile. URL: https://solid.github.io/webid-profile/

Non-Normative References

[RFC3339]
G. Klyne; C. Newman. Date and Time on the Internet: Timestamps. July 2002. Proposed Standard. URL: https://www.rfc-editor.org/info/rfc3339/
[RFC6749]
D. Hardt, Ed.. The OAuth 2.0 Authorization Framework. October 2012. Proposed Standard. URL: https://www.rfc-editor.org/info/rfc6749/
[RFC6750]
M. Jones; D. Hardt. The OAuth 2.0 Authorization Framework: Bearer Token Usage. October 2012. Proposed Standard. URL: https://www.rfc-editor.org/info/rfc6750/
[RFC7636]
N. Sakimura, Ed.; J. Bradley; N. Agarwal. Proof Key for Code Exchange by OAuth Public Clients. September 2015. Proposed Standard. URL: https://www.rfc-editor.org/info/rfc7636/
[RFC8628]
W. Denniss; et al. OAuth 2.0 Device Authorization Grant. August 2019. Proposed Standard. URL: https://www.rfc-editor.org/info/rfc8628/
[RFC9110]
R. Fielding, Ed.; M. Nottingham, Ed.; J. Reschke, Ed.. HTTP Semantics. June 2022. Internet Standard. URL: https://httpwg.org/specs/rfc9110.html