From 00d39463053d0a22b6ee7d116821cdf1b72a1b5e Mon Sep 17 00:00:00 2001 From: ponachte Date: Mon, 3 Aug 2026 17:22:34 +0200 Subject: [PATCH 1/2] transformation -> deployment catalog --- contexts/aggregator-description.jsonld | 4 +- contexts/aggregator-server-description.jsonld | 4 +- contexts/aggregator.jsonld | 25 +- dist/index.html | 975 ++++-------------- dist/spec.bs | 819 +++------------ provenance-detailed-draft.bs | 244 +++++ sections/01-introduction.bs | 13 +- sections/02-definitions.bs | 11 +- .../03-architecture-and-resource-model.bs | 8 +- sections/04-aggregator-data-model.bs | 319 ++---- sections/05-aggregator-server-metadata.bs | 94 +- sections/08-aggregator-metadata.bs | 32 +- sections/09-aggregator-service-management.bs | 270 +---- sections/11-vocabulary.bs | 70 +- 14 files changed, 741 insertions(+), 2147 deletions(-) create mode 100644 provenance-detailed-draft.bs diff --git a/contexts/aggregator-description.jsonld b/contexts/aggregator-description.jsonld index 83fddde..8b0023d 100644 --- a/contexts/aggregator-description.jsonld +++ b/contexts/aggregator-description.jsonld @@ -24,8 +24,8 @@ "@id": "aggr:tokenExpiry", "@type": "xsd:dateTime" }, - "transformation_catalog": { - "@id": "aggr:transformationCatalog", + "deployment_catalog": { + "@id": "aggr:deploymentCatalog", "@type": "@id" }, "service_collection_endpoint": { diff --git a/contexts/aggregator-server-description.jsonld b/contexts/aggregator-server-description.jsonld index 20951fa..32b43a5 100644 --- a/contexts/aggregator-server-description.jsonld +++ b/contexts/aggregator-server-description.jsonld @@ -28,8 +28,8 @@ "@id": "aggr:clientIdentifier", "@type": "@id" }, - "transformation_catalog": { - "@id": "aggr:transformationCatalog", + "deployment_catalog": { + "@id": "aggr:deploymentCatalog", "@type": "@id" } } diff --git a/contexts/aggregator.jsonld b/contexts/aggregator.jsonld index 7c0d541..ce86e03 100644 --- a/contexts/aggregator.jsonld +++ b/contexts/aggregator.jsonld @@ -2,7 +2,6 @@ "@context": { "aggr": "https://w3id.org/aggregator#", "fno": "https://w3id.org/function/ontology#", - "fnoc": "https://fno.io/vocabulary/composition/0.1.0/", "dcat": "http://www.w3.org/ns/dcat#", "dct": "http://purl.org/dc/terms/", "prov": "http://www.w3.org/ns/prov#", @@ -25,25 +24,21 @@ "Service": "aggr:Service", "ServiceRequest": "aggr:ServiceRequest", "ServiceCollection": "aggr:ServiceCollection", - "TransformationCatalog": "aggr:TransformationCatalog", + "DeploymentCatalog": "aggr:DeploymentCatalog", "ProvenanceLog": "aggr:ProvenanceLog", "hasService": { "@id": "aggr:hasService", "@type": "@id" }, - "hasTransformation": { "@id": "aggr:hasTransformation", "@type": "@id" }, - "hasAppliedFunction": { "@id": "aggr:hasAppliedFunction", "@type": "@id" }, + "hasDeploymentFunction": { "@id": "aggr:hasDeploymentFunction", "@type": "@id" }, "hasAlgorithm": { "@id": "aggr:hasAlgorithm", "@type": "@id" }, "hasMapping": { "@id": "aggr:hasMapping", "@type": "@id" }, - "hasComposition": { "@id": "aggr:hasComposition", "@type": "@id" }, "hasActivity": { "@id": "aggr:hasActivity", "@type": "@id" }, - "performs": { "@id": "aggr:performs", "@type": "@id" }, - "applies": { "@id": "aggr:applies", "@type": "@id" }, + "deploymentFunction": { "@id": "aggr:deploymentFunction", "@type": "@id" }, "implements": { "@id": "aggr:implements", "@type": "@id" }, - "forOutput": { "@id": "aggr:forOutput", "@type": "@id" }, "fromAggregator": { "@id": "aggr:fromAggregator", "@type": "@id" }, "fromServer": { "@id": "aggr:fromServer", "@type": "@id" }, "fromService": { "@id": "aggr:fromService", "@type": "@id" }, "provenanceLog": { "@id": "aggr:provenanceLog", "@type": "@id" }, - "transformationCatalog": { "@id": "aggr:transformationCatalog", "@type": "@id" }, + "deploymentCatalog": { "@id": "aggr:deploymentCatalog", "@type": "@id" }, "status": "aggr:status", "statusDetail": "aggr:statusDetail", "createdAt": { "@id": "aggr:createdAt", "@type": "xsd:dateTime" }, @@ -57,18 +52,6 @@ "executes": { "@id": "fno:executes", "@type": "@id" }, "uses": { "@id": "fno:uses", "@type": "@id" }, - "applies_function": { "@id": "fnoc:applies", "@type": "@id" }, - "parameterBindings": { "@id": "fnoc:parameterBindings", "@type": "@id", "@container": "@list" }, - "boundParameter": { "@id": "fnoc:boundParameter", "@type": "@id" }, - "boundToTerm": "fnoc:boundToTerm", - "composition": { "@id": "fnoc:composition", "@type": "@id" }, - "mapFrom": "fnoc:mapFrom", - "mapTo": "fnoc:mapTo", - "constituentFunction": { "@id": "fnoc:constituentFunction", "@type": "@id" }, - "functionParameter": { "@id": "fnoc:functionParameter", "@type": "@id" }, - "functionOutput": { "@id": "fnoc:functionOutput", "@type": "@id" }, - "composedOf": "fnoc:composedOf", - "title": "dct:title", "description": "dct:description", "format": { "@id": "dct:format", "@type": "@id" }, diff --git a/dist/index.html b/dist/index.html index 6382185..76ddfae 100644 --- a/dist/index.html +++ b/dist/index.html @@ -2046,7 +2046,7 @@

Aggregator Specification

Living Document, -

+
Previous Versions: @@ -2064,7 +2064,7 @@

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 9 July 2026, +In addition, as of 3 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. @@ -2102,19 +2102,18 @@

Table of Contents

  • 4 Aggregator Data Model
      -
    1. 4.1 Transformation -
    2. 4.2 Transformation Catalog +
    3. 4.1 Deployment Function +
    4. 4.2 Deployment Catalog
    5. 4.3 Service
    6. 4.4 Service Collection -
    7. 4.5 Execution -
    8. 4.6 Provenance Log +
    9. 4.5 Provenance Log
  • 5 Aggregator Server Metadata
    1. 5.1 Aggregator Server Description
    2. 5.2 Client ID Document -
    3. 5.3 Server-level Transformation Catalog +
    4. 5.3 Server-level Deployment Catalog
  • 6 Aggregator Management @@ -2158,7 +2157,7 @@

    Table of Contents

    8 Aggregator Metadata
    1. 8.1 Aggregator Description -
    2. 8.2 Instance-level Transformation Catalog +
    3. 8.2 Instance-level Deployment Catalog
  • 9 Aggregator Service Management @@ -2167,19 +2166,13 @@

    Table of Contents

    9.1 Service Collection Endpoint
    1. 9.1.1 Deploying a Service -
    2. 9.1.2 Deploying Pipelines -
    3. 9.1.3 Service Discovery +
    4. 9.1.2 Service Discovery
  • 9.2 Service Description Endpoint
    1. 9.2.1 Service Output Endpoints
    -
  • - 9.3 Service Provenance -
      -
    1. 9.3.1 Continuous updates -
  • 10 Vocabulary @@ -2191,7 +2184,7 @@

    Table of Contents

  • 10.1.2 aggr:Service
  • 10.1.3 aggr:AggregatorServer
  • 10.1.4 aggr:ServiceCollection -
  • 10.1.5 aggr:TransformationCatalog +
  • 10.1.5 aggr:DeploymentCatalog
  • 10.1.6 aggr:ProvenanceLog
  • 10.1.7 aggr:ServiceRequest
  • 10.1.8 aggr:ManagementFlow @@ -2208,28 +2201,24 @@

    Table of Contents

  • 10.2.3 aggr:tokenExpiry
  • 10.2.4 aggr:serviceCollectionEndpoint
  • 10.2.5 aggr:hasService -
  • 10.2.6 aggr:hasTransformation -
  • 10.2.7 aggr:hasAppliedTransformation -
  • 10.2.8 aggr:hasAlgorithm -
  • 10.2.9 aggr:hasMapping -
  • 10.2.10 aggr:hasComposition -
  • 10.2.11 aggr:status -
  • 10.2.12 aggr:statusDetail -
  • 10.2.13 aggr:performs -
  • 10.2.14 aggr:applies -
  • 10.2.15 aggr:implements -
  • 10.2.16 aggr:forOutput -
  • 10.2.17 aggr:fromAggregator -
  • 10.2.18 aggr:fromServer -
  • 10.2.19 aggr:fromService -
  • 10.2.20 aggr:provenanceLog -
  • 10.2.21 aggr:hasActivity -
  • 10.2.22 aggr:managementEndpoint -
  • 10.2.23 aggr:supportedManagementFlow -
  • 10.2.24 aggr:managementRequestFormatSupported -
  • 10.2.25 aggr:specVersion -
  • 10.2.26 aggr:clientIdentifier -
  • 10.2.27 aggr:transformationCatalog +
  • 10.2.6 aggr:hasDeploymentFunction +
  • 10.2.7 aggr:hasAlgorithm +
  • 10.2.8 aggr:hasMapping +
  • 10.2.9 aggr:status +
  • 10.2.10 aggr:statusDetail +
  • 10.2.11 aggr:deploymentFunction +
  • 10.2.12 aggr:implements +
  • 10.2.13 aggr:fromAggregator +
  • 10.2.14 aggr:fromServer +
  • 10.2.15 aggr:fromService +
  • 10.2.16 aggr:provenanceLog +
  • 10.2.17 aggr:hasActivity +
  • 10.2.18 aggr:managementEndpoint +
  • 10.2.19 aggr:supportedManagementFlow +
  • 10.2.20 aggr:managementRequestFormatSupported +
  • 10.2.21 aggr:specVersion +
  • 10.2.22 aggr:clientIdentifier +
  • 10.2.23 aggr:deploymentCatalog
  • 10.3 Claim Types @@ -2251,14 +2240,13 @@

    Table of Contents

    1. Introduction

    This specification defines the Aggregator Protocol, an HTTP-based interface that lets a client create and manage Aggregator -Instances and configure Aggregator Services that execute data transformations. Transformations are described and discovered -using the Function Ontology (FnO) [FNO]; a service is configured by referencing a transformation (a fno:Function) and -providing its parameters (using an fno:AppliedFunction), after which the client can retrieve the derived result from the -output defined by that function.

    +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 transformation catalog (§ 5 Aggregator Server Metadata). Using the management +management flows, and the server’s deployment 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 transformations endpoint +instance’s Aggregator Description to find the instance’s service collection and deployment 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] @@ -2281,12 +2269,12 @@

    § 9 Aggregator Service Management).

    +

    Aggregator Service (or “Service”): A deployed dcat:DataService and prov:SoftwareAgent inside an Aggregator +Instance. It serves one or more datasets and links to the FnO deployment function used to create it (see +§ 9 Aggregator Service Management).

  • -

    Transformation Catalog: A catalog that describes the FnO Functions supported by the Aggregator Server and the FnO AppliedFunctions hosted on an Aggregator -Instance (see § 5.3 Server-level Transformation Catalog and § 8.2 Instance-level Transformation Catalog).

    +

    Deployment Catalog: A catalog of FnO deployment functions supported by an Aggregator Server or Aggregator +Instance (see § 5.3 Server-level Deployment Catalog and § 8.2 Instance-level Deployment Catalog).

    2.2. Identity, Authorization, and Tokens

      @@ -2329,8 +2317,6 @@

      <

      dct: → http://purl.org/dc/terms/

    • fno: → https://w3id.org/function/ontology#

      -
    • -

      fnoc: → https://fno.io/vocabulary/composition/0.1.0/

    • dcat: → http://www.w3.org/ns/dcat#

    • @@ -2356,7 +2342,7 @@

      § 9 Aggregator Service Management).

    • Aggregator Service resources: a service collection and individual services managed under the instance (see -§ 9.1.3 Service Discovery and service resource and provenance).

      +§ 9.1.2 Service Discovery and the service resource).

    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:

    @@ -2400,7 +2386,7 @@

  • Server-level discovery resources: deployments MAY expose the server description (see § 5.1 Aggregator Server Description) and -the server-level transformation catalog (see § 5.3 Server-level Transformation Catalog) without authentication, or MAY +the server-level deployment catalog (see § 5.3 Server-level Deployment Catalog) without authentication, or MAY protect them using an OpenID Connect (OIDC) ID Token. The Client ID Document (see § 5.2 Client ID Document) is typically accessible without authentication.

  • @@ -2428,11 +2414,11 @@

    Client ID Document: https://aggregator.example/client.jsonld

  • -

    Transformation catalog: https://aggregator.example/transformations

    +

    Deployment catalog: https://aggregator.example/deployments

  • Instance description: https://aggregator.example/agg1/

  • -

    Instance Transformation catalog: https://aggregator.example/agg1/transformations

    +

    Instance Deployment catalog: https://aggregator.example/agg1/deployments

  • Service collection: https://aggregator.example/agg1/services

  • @@ -2441,9 +2427,9 @@

    Service output: https://aggregator.example/agg1/services/service1/output

    4. Aggregator Data Model

    -

    This section specifies the data model used to describe the aggregator components like running aggregator services -and the transformations they implement as well as the outputs they generate. By describing them as linked data the -model enables interoperable publication, discovery, execution, and provenance tracking of aggregator services.

    +

    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], @@ -2452,54 +2438,69 @@

    4 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. Transformation

    -

    An aggregator transformation defines a well-described functional interface using the Function Ontology [FNO]. -Each transformation MUST be described as an fno:Function that SHOULD use dct:description to provide a -human-readable description of the transformation. Each transformation MAY use a fno:name to provide a short name for -the transformation, but clients SHOULD NOT rely on this property for unique identification. The transformation MAY -describe zero or more fno:Parameters and fno:Outputs using the fno:expects and fno:returns properties respectively. -Each parameter and output:

    +

    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:

    +
      +
    • +

      MUST be described as an fno:Function.

      +
    • +

      SHOULD use dct:description to provide a human-readable description.

      +
    • +

      MAY use fno:name to provide a short name, but clients SHOULD NOT rely on this property for unique +identification.

      +
    • +

      MAY describe zero or more fno:Parameter resources using fno:expects.

      +
    • +

      MUST describe exactly one fno:Output using fno:returns.

      +
    +

    Each parameter:

    • -

      MUST be a fno:Parameter or fno:Output respectively.

      +

      MUST be an fno:Parameter.

      +
    • +

      MUST use fno:predicate to specify the predicate used to provide its value in an aggr:ServiceRequest.

      +
    • +

      SHOULD use fno:type to describe the parameter type.

    • -

      MUST use fno:predicate to specify the predicate that will be used to signify its -value used by an fno:Execution and aggr:ServiceRequest.

      +

      MAY use dct:format to describe the parameter format.

    • -

      MUST define the fno:type of the output as a dcat:Dataset.

      +

      MAY use dct:conformsTo to indicate that the parameter follows a specification or protocol.

    • -

      SHOULD use fno:type to describe the parameter types.

      +

      MAY use fno:required to indicate whether the parameter is required or optional. If this property is absent, +clients MUST assume the parameter is optional.

      +
    +

    The output:

    +
    • -

      MAY use dct:format to describe the format of the parameter.

      +

      MUST be an fno:Output.

    • -

      MAY use dct:conformsTo to signify the parameter follows a certain specification/protocol.

      +

      MUST have aggr:Service as its fno:type.

    • -

      MAY use dct:conformsTo to signify the output follows a certain shape. If such a shape is defined, the dataset -generated for that output and the distributions referenced from that dataset MUST conform to it.

      +

      MUST use fno:predicate to specify the output predicate.

    • -

      MAY use fno:required to indicate whether the parameter is required or optional. If not specified, clients MUST -assume the parameter is optional.

      +

      MAY use dct:conformsTo to further describe the kind of service produced by the deployment function. This +specification does not prescribe the referenced description or profile.

    -

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

    -
    - +

    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/transformations#> .
-@prefix dcat: <http://www.w3.org/ns/dcat#> .
+
    @base <http://aggregator.example.org/deployments#> .
+@prefix aggr: <https://w3id.org/aggregator#> .
 @prefix fno: <https://w3id.org/function/ontology#> .
-@prefix rr: <http://www.w3.org/ns/r2rml#> .
-@prefix sh: <http://www.w3.org/ns/shacl#> .
 @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
 @prefix dct: <http://purl.org/dc/terms/> .
-@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
 
-<QueryView>
+<QueryViewDeployment>
   a                   fno:Function ;
   fno:name            "The SPARQL QueryView function"^^xsd:string ;
-  dct:description     "Performs a query on a source and materializes view as a SPARQL endpoint"^^xsd:string ;
+  dct:description     "Deploys a service that exposes a materialized SPARQL query view"^^xsd:string ;
   fno:expects         ( <QuerySource> <QueryString> ) ;
-  fno:returns         ( <ViewOutput> ) .
+  fno:returns         ( <ServiceOutput> ) .
 
 <QuerySource>
   a                   fno:Parameter ;
@@ -2514,94 +2515,21 @@ 
    dct:conformsTo  <https://www.w3.org/TR/2013/REC-sparql11-query-20130321/> ;
   fno:required    "true"^^xsd:boolean .
 
-<ViewOutput>
-  a               fno:Output ;
-  fno:type        dcat:Dataset ;
-  dct:conformsTo  ex:SPARQLResultDatasetShape .
-  fno:predicate   <view> .
-
-<SPARQLResultDatasetShape>
-  a sh:NodeShape ;
-  sh:targetClass dcat:Dataset ;
-  sh:property [
-    sh:path dcat:distribution ;
-    sh:minCount 1 ;
-    sh:node <SPARQLXMLDistributionShape>
-  ] ;
-  sh:property [
-    sh:path dcat:distribution ;
-    sh:minCount 1 ;
-    sh:node <SPARQLJSONDistributionShape>
-  ] .
-
-<SPARQLXMLDistributionShape>
-  a sh:NodeShape ;
-  sh:property [
-    sh:path dcat:mediaType ;
-    sh:hasValue <http://www.iana.org/assignments/media-types/application/sparql-results+xml>
-  ] .
-
-<SPARQLJSONDistributionShape>
-  a sh:NodeShape ;
-  sh:property [
-    sh:path dcat:mediaType ;
-    sh:hasValue <http://www.iana.org/assignments/media-types/application/sparql-results+json>
-  ] .
-
-<RMLMapper>
-  a fno:Function ;
-  fno:name "The RML Mapper Function"^^xsd:string ;
-  dct:description "Performs RML mappings on a source and materializes results as a SPARQL endpoint"^^xsd:string ;
-  fno:expects ( <RMLMapping> ) ;
-  fno:returns ( <KGOutput> ) .
-
-<RMLMapping> 
-  a                   fno:Parameter ;
-  fno:type            rr:TriplesMap ;
-  dct:format          <http://www.w3.org/ns/formats/Turtle> ;
-  fno:predicate       <mapping> ;
-  fno:required        "true"^^xsd:boolean .
-
-<KGOutput>
+<ServiceOutput>
   a               fno:Output ;
-  fno:type        dcat:Dataset ;
-  fno:predicate   <kg> .
+  fno:type        aggr:Service ;
+  fno:predicate   <service> ;
+  dct:conformsTo  <https://example.org/profiles/sparql-query-service> .
    -

    An Applied Transformation is a Transformation in which one or more parameters are bound to concrete values and is -represented using an fno:AppliedFunction from [FNO].

    -
    - - -
    @base <http://aggregator.example.org/transformations#> .
-@prefix fno: <https://w3id.org/function/ontology#> .
-@prefix fnoc: <https://fno.io/vocabulary/composition/0.1.0/> .
-@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
-
-<GivenNameView>
-  a fno:AppliedFunction ;
-  fnoc:applies <QueryView> ;
-  fnoc:parameterBindings (
-    [
-      fnoc:boundParameter <QuerySource> ;
-      fnoc:boundToTerm "http://example.org/source"
-    ]
-    [
-      fnoc:boundParameter <QueryString> ;
-      fnoc:boundToTerm "SELECT * WHERE { ?person foaf:givenName ?name }"^^xsd:string
-    ]
-  ) .
-
    -
    -

    4.2. Transformation Catalog

    -

    A Transformation Catalog references all transformations made available on an Aggregator Server including any metadata -mentioned earlier.

    -

    The Transformation Catalog:

    +

    4.2. Deployment Catalog

    +

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

    +

    The Deployment Catalog:

    • -

      MUST be described as an aggr:TransformationCatalog.

      +

      MUST be described as an aggr:DeploymentCatalog.

    • -

      MUST reference all supported (applied) transformations using aggr:hasTransformation.

      +

      MUST reference all supported deployment functions using aggr:hasDeploymentFunction.

    • MAY reference a supported algorithm using aggr:hasAlgorithm.

    • @@ -2609,25 +2537,22 @@

      MUST reference all resources not hosted by the Aggregator Server using rdfs:seeAlso.

    -
    - +
    + -
    @base <http://aggregator.example.org/transformations#> .
+
    @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 fnoc: <https://fno.io/vocabulary/composition/0.1.0/> .
 @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:TransformationCatalog ;
-    aggr:hasTransformation 
-      <QueryView> , 
-      <GivenNameView> ,
-      <RMLMapper> ,
+<> a aggr:DeploymentCatalog ;
+    aggr:hasDeploymentFunction
+      <QueryViewDeployment> ,
       <http://example.org/external/ExternalFunction> ;
     rdfs:seeAlso <http://example.org/external/ExternalFunction> .
 
    
@@ -2639,36 +2564,27 @@ 
    an aggr:Service
    
     
  • 
      
    a dcat:DataService ([Data-Catalog])
    
-    
  • 
-     
    a prov:SoftwareAgent ([PROV-O])
    
    
    
    Furthermore, the service:
    
    
      
     
    • 
-     
      MUST serve exactly one dataset for each output of the transformation identified by aggr:performs.
      
-    
    • 
-     
      MUST link using aggr:performs to the underlying fno:Function.
      
+     
      MUST link using aggr:deploymentFunction to the fno:Function used to deploy it.
      
     
    • 
-     
      MUST link using dcat:servesDataset to the corresponding dataset described as a dcat:Dataset.
      
+     
      MUST link using dcat:servesDataset to one or more datasets described as dcat:Dataset resources.
      
     
    • 
      
      SHOULD declare operational metadata such as status and creation time.
      
     
    • 
      
      SHOULD indicate it adheres to the aggregator protocol using dct:conformsTo.
      
-    
    • 
-     
      MAY link using aggr:applies to an applied transformation that applies the performed function
-with a set of input values when the usecase allows these to be disclosed.
      
-    
    • 
-     
      MAY specify the exact implementation using a link to an fno:Implementation with aggr:implements.
      
    
    
-   
    The corresponding dataset:
    
+   
    Each corresponding dataset:
    
    
      
     
    • 
      
      MUST be described as a dcat:Dataset.
      
     
    • 
-     
      MUST link to exactly one fno:Output of that transformation using aggr:forOutput.
      
-    
    • 
-     
      MUST reference a dcat:distribution.
      
+     
      MAY reference one or more dcat:Distribution resources using dcat:distribution.
      
    
    
+   
    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:
    
    
      
     
    • 
@@ -2690,12 +2606,11 @@ 
      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 inst-trans: <https://aggregator.example.org/agg1/transformations/> .
-@prefix server-trans: <https://aggregator.example.org/transformations#> .
+@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#> .
@@ -2708,14 +2623,12 @@ 
      a prov:SoftwareAgent ;
     aggr:status "running" ;
     aggr:createdAt "2024-01-01T12:00:00Z"^^xsd:dateTime ;
-    aggr:performs server-trans:QueryView ;
-    aggr:applies inst-trans:QueryViewApplied ;
+    aggr:deploymentFunction server-deploy:QueryViewDeployment ;
     dct:conformsTo <https://w3id.org/aggregator#> ;
     dcat:servesDataset <#dataset> .
 
 <#dataset>
     a dcat:Dataset ;
-    aggr:forOutput server-trans:ViewOutput ;
     dcat:distribution <#distribution-xml> ,
      <#distribution-json> .
 
@@ -2753,137 +2666,10 @@ 
      
     <http://aggregator.example.org/agg1/services/rml-mapper-service> .
 
      
    
      
-   
      4.5. Execution
      
-   
      An Execution represents the service output provenance information. Each execution:
      
-   
        
-    
      • 
-     
        MUST be a fno:Execution.
        
-    
      • 
-     
        MUST link to the executed transformation using fno:executes.
        
-    
      • 
-     
        MUST link to the generated datasets using the output predicates defined in § 4.1 Transformation.
        
-    
      • 
-     
        MUST link to the used parameter values using the parameter predicates defined in § 4.1 Transformation.
        
-    
      • 
-     
        MAY link to the used mapping using fno:uses to indicate the used implementation
        
-    
      • 
-     
        MUST be a prov:Activity.
        
-    
      • 
-     
        MUST be associated with the service using prov:associatedWith.
        
-    
      • 
-     
        MUST include a start time using prov:startedAtTime.
        
-    
      • 
-     
        MAY include an end time using prov:endedAtTime.
        
-   
      
-   
      The execution MAY provide additional metadata such as prov:qualifiedAssociation, or any other
-relevant provenance information. The executed transformation MUST be the same as the transformation declared in the 
-service description using aggr:performs.
      
-   
      The generated dataset produced by an execution either is the logical dataset served by the
-service, or it is a distinct version of that logical dataset, depending on whether the service
-retains version history.
      
-   
      In either case, the generated dataset:
      
-   
        
-    
      • 
-     
        MUST be typed as a dcat:Dataset.
        
-    
      • 
-     
        MUST be typed as a prov:Entity.
        
-    
      • 
-     
        MUST link to the execution using prov:wasGeneratedBy.
        
-    
      • 
-     
        SHOULD include prov:wasGeneratedAtTime.
        
-   
      
-   
      If the service retains version history, the generated dataset additionally:
      
-   
        
-    
      • 
-     
        MUST specify it is a version of the service dataset using dcat:isVersionOf.
        
-   
      
-   
      If the service retains version history, the logical dataset:
      
-   
        
-    
      • 
-     
        MUST declare the latest known version using dcat:hasCurrentVersion.
        
-    
      • 
-     
        MUST declare other known versions using dcat:hasVersion.
        
-   
      
-   
      The following example shows an execution that produces a new version of a service dataset.
      
-   
      
-    
-
-
      @base <https://aggregator.example.org/agg1/services/sparql-query-view-service/provenance#> .
-@prefix svc: <https://aggregator.example.org/agg1/services/sparql-query-view-service#> .
-@prefix server-trans: <https://aggregator.example.org/transformations#> .
-@prefix aggr: <https://w3id.org/aggregator#> .
-@prefix fno: <https://w3id.org/function/ontology#> .
-@prefix dcat: <http://www.w3.org/ns/dcat#> .
-@prefix prov: <http://www.w3.org/ns/prov#> .
-@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
-
-<execution-1>
-  a fno:Execution ;
-  a prov:Activity ;
-  fno:executes server-trans:sparql-query-view ;
-  server-trans:query "SELECT * WHERE { ?s ?p ?o }" ;
-  server-trans:source "http://example.org/source1" ;
-  server-trans:view <dataset-1> ;
-  prov:associatedWith <https://example.org/agg1/services/sparql-query-view-service> ;
-  prov:startedAtTime "2025-01-02T12:00:00Z"^^xsd:dateTime ;
-  prov:endedAtTime "2025-01-02T12:02:00Z"^^xsd:dateTime .
-
-<dataset-1>
-  a dcat:Dataset ;
-  a prov:Entity ;
-  dcat:isVersionOf svc:dataset ;
-  prov:wasGeneratedBy <execution-1> ;
-  prov:wasGeneratedAtTime "2025-01-02T12:02:00Z"^^xsd:dateTime .
-
      
-   
      
-   
      With the logical dataset referencing the generated datasets.
      
-   
      
-    
-
-
      @base : <https://aggregator.example.org/agg1/services/sparql-query-view-service> .
-@prefix provlog: <https://aggregator.example.org/agg1/services/sparql-query-view-service/provenance#> .
-@prefix server-trans: <https://aggregator.example.org/transformations#> .
-@prefix aggr: <https://w3id.org/aggregator#> .
-@prefix fno: <https://w3id.org/function/ontology#> .
-@prefix dcat: <http://www.w3.org/ns/dcat#> .
-@prefix prov: <http://www.w3.org/ns/prov#> .
-@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
-
-<#dataset>
-    a dcat:Dataset ;
-    aggr:forOutput server-trans:view-output ;
-    dcat:distribution <#distribution-xml> ,
-     <#distribution-json> ;
-    dcat:hasCurrentVersion provlog:dataset-1 ;
-    dcat:hasVersion provlog:dataset-0 ,
-      provlog:dataset-1 .
-
      
-   
      
-   
      4.6. Provenance Log
      
-   
      A Provenance Log consolidates all service output provenance information by referencing executions.
      
-   
      The Provenance Log:
      
-   
        
-    
      • 
-     
        MUST be described as an aggr:ProvenanceLog.
        
-    
      • 
-     
        MUST reference one or more execution activities using aggr:hasActivity.
        
-   
      
-   
      The Service:
      
-   
        
-    
      • 
-     
        MUST link its provenance log using aggr:provenanceLog.
        
-   
      
-   
      
-    
-
-
      @base <https://aggregator.example.org/agg1/services/sparql-query-view-service/provenance>
-@prefix aggr: <https://w3id.org/aggregator#> .
-
-<>
-  a aggr:ProvenanceLog ;
-  aggr:hasActivity :execution-0 .
-
      
-   
      
+   
      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.
      
    
      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 
@@ -2903,12 +2689,12 @@ 
      
      
      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.22 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.23 aggr:supportedManagementFlow) whose object is the corresponding flow class IRI.
      
+(§ 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:

    • -
    - +
    + 
    {
   "@context": "https://w3id.org/aggregator/contexts/aggregator-server-description.jsonld",
@@ -2961,7 +2747,7 @@ 
    ],
   "version": "1.0.0",
   "client_identifier": "https://aggregator.example/client.jsonld",
-  "transformation_catalog": "https://aggregator.example/transformations"
+  "deployment_catalog": "https://aggregator.example/deployments"
 }
    @@ -2972,90 +2758,15 @@

    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 Transformation Catalog

    -

    The Transformation Catalog is an RDF document whose base resource, identified by the document’s -own retrieval URL, MUST be described as an aggr:TransformationCatalog (§ 4.2 Transformation Catalog). -Resources referenced by the Transformation Catalog MAY either be included directly in the RDF document or +

    5.3. Server-level Deployment Catalog

    +

    The Deployment Catalog is an RDF document whose base resource, identified by the document’s +own retrieval URL, MUST be described as an aggr:DeploymentCatalog (§ 4.2 Deployment Catalog). +Resources referenced by the Deployment 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 transformation_catalog field. +The URL MUST be advertised in the § 5.1 Aggregator Server Description via the deployment_catalog field. The catalog SHOULD support HTTP content negotiation, allowing clients to request different RDF serializations (e.g., Turtle, JSON-LD).

    -

    A transformation MAY be linked to an fnoc:Composition using fnoc:composition. This MAY be done -solely to describe the internal structure of a transformation. In this case, the composition serves as descriptive metadata -to provide additional transparency. Composite transformations remain fno:Function resources and therefore MUST be -advertised using aggr:hasTransformation. If all transformations referenced within the fnoc:Composition are also -included in the catalog, each of them represents a deployable service. This enables an Aggregator to expose a pipeline as a -single service while internally orchestrating multiple individual services.

    -
    - -The following example describes a pipeline that: - -
      -
    1. -

      Uses RML to map a non-RDF source.

      -
    2. -

      Executes a query over the generated RDF.

      -
    3. -

      Exposes the resulting query output.

      -
    -
    @base <http://aggregator.example.org/transformations#> .
-@prefix aggr: <https://w3id.org/aggregator#> .
-@prefix dct: <http://purl.org/dc/terms/> .
-@prefix fno: <https://w3id.org/function/ontology#> .
-@prefix fnoc: <https://fno.io/vocabulary/composition/0.1.0/> .
-
-<> a aggr:TransformationCatalog ;
-    dct:title "Aggregator transformations" ;
-    aggr:hasTransformation <RMLQueryPipeline> ;
-    aggr:hasTransformation <QueryView> ;
-    aggr:hasTransformation <RMLMapper> ;
-
-<RMLQueryPipeline>
-  a fno:Function ;
-  fno:expects ( <RMLMapping> <QueryString> ) ;
-  fno:returns ( <ViewOutput> ) ;
-  fno:composition [
-    fnoc:composedOf [
-      fnoc:mapFrom [
-        fnoc:constituentFunction <RMLQueryPipeline> ;
-        fnoc:functionParameter <RMLMapping> .
-      ] ;
-      fnoc:mapTo [
-        fnoc:constituentFunction <RMLMapper> ;
-        fnoc:functionParameter <RMLMapping> .
-      ] .
-    ],[
-      fnoc:mapFrom [
-        fnoc:constituentFunction <RMLQueryPipeline> ;
-        fnoc:functionParameter <QueryString> .
-      ] ;
-      fnoc:mapTo [
-        fnoc:constituentFunction <QueryView> ;
-        fnoc:functionParameter <QueryString> .
-      ] .
-    ],[
-      fnoc:mapFrom [
-        fnoc:constituentFunction <RMLMapper> ;
-        fnoc:functionParameter <KGOutput> .
-      ] ;
-      fnoc:mapTo [
-        fnoc:constituentFunction <QueryView> ;
-        fnoc:functionParameter <QuerySource> ;
-      ] .
-    ],[
-      fnoc:mapFrom [
-        fnoc:constituentFunction <QueryView> ;
-        fnoc:functionOutput <ViewOutput> .
-      ] ;
-      fnoc:mapTo [
-        fnoc:constituentFunction <RMLQueryPipeline> ;
-        fnoc:functionParameter <ViewOutput> .
-      ] .
-    ] .
-  ] .
-
    -

    6. Aggregator Management

    This section describes how Aggregator Instances are managed at the Aggregator Server level. Deployments define their own @@ -3964,7 +3675,7 @@
    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 -transformation_catalog and service_collection_endpoint fields) so clients can discover the deployment-specific layout.

    +deployment_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 @@ -3997,11 +3708,11 @@

    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).

    -
    transformation_catalog (REQUIRED): +
    deployment_catalog (REQUIRED):
    -

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

    +

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

    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 @@ -4010,8 +3721,8 @@

    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",
@@ -4020,30 +3731,28 @@ 
    "created_at": "2025-12-17T17:20:00Z",
   "login_status": true,
   "token_expiry": "2025-12-17T18:20:00Z",
-  "transformation_catalog": "https://aggregator.example/aggregators/agg-7890/transformations",
+  "deployment_catalog": "https://aggregator.example/aggregators/agg-7890/deployments",
   "service_collection_endpoint": "https://aggregator.example/aggregators/agg-7890/services",
   "oidcIssuer": "https://issuer.example/"
 }
    -

    8.2. Instance-level Transformation Catalog

    -

    This endpoint is the instance-level extension of the server-level Transformation Catalog defined in -§ 5.3 Server-level Transformation Catalog. It allows the Aggregator Server to make certain transformations available -only to specific Aggregator instances, by curating the catalog’s contents per instance. This Instance-Level -Transformation Catalog also includes all Applied Transformations used by the Aggregator’s deployed Services, -as well as all client-defined pipelines (further explained in § 9.1.1 Deploying a Service).

    +

    8.2. Instance-level Deployment Catalog

    +

    This endpoint is the instance-level extension of the server-level Deployment Catalog defined in +§ 5.3 Server-level Deployment 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 instance_transformation_catalog field. The endpoint -MUST follow the same content negotiation rules, and other requirements, as the server-level Transformation -Catalog. Resources referenced by this Instance-Level Transformation Catalog MAY either be included directly in -the RDF document or hosted by the Aggregator Server in separate documents. This Instance-Level Transformation +be advertised in the § 8.1 Aggregator Description via the deployment_catalog field. The endpoint +MUST follow the same content negotiation rules, and other requirements, as the server-level Deployment +Catalog. Resources referenced by this Instance-Level Deployment Catalog MAY either be included directly in +the RDF document or hosted by the Aggregator Server in separate documents. This Instance-Level Deployment 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:

    @@ -4078,7 +3787,7 @@

    MUST be identified using either a unique URI or a blank node.

  • -

    MUST declare a Transformation using performs.

    +

    MUST identify a deployment function using deploymentFunction.

  • MUST provide inputs for at least all required parameters, using the parameter predicates defined using fno:predicate in the function description.

    @@ -4092,13 +3801,11 @@

    Upon successful processing, the Aggregator MUST:

    1. -

      Include an Applied Transformation representing the performed Transformation with the given inputs to the -Instance-Level Transformation Catalog. This resource MUST be referenced using aggr:applies and protected -using the § 7 Aggregator Security Model (Authentication & Authorization).

      +

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

    2. -

      Deploy a new Service that performs the transformation indicated by performs (and, if present, the implementation -indicated by implements), and expose a Service Description Endpoint § 9.2 Service Description Endpoint describing it according -to the data model in § 4.3 Service.

      +

      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. @@ -4118,14 +3825,14 @@

      MUST respond with 409 Conflict if the requested URI is valid but already in use.

    5. MUST respond with 400 Bad Request if the request body is syntactically malformed or semantically invalid -(e.g., missing required parameter bindings or referencing an unknown transformation).

      +(e.g., missing required parameter values or referencing an unknown deployment function).

    6. MUST respond with 500 Internal Server Error if the request is valid but the Aggregator fails to deploy the Service.

      -

      The following example depicts a request that deploys a service performing the QueryView Transformation.

      -
      - +

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

      +
      + 
      POST https://aggregator.example/agg1/services HTTP/1.1
 Host: aggregator.example
@@ -4135,130 +3842,20 @@ 
      "@context": [
         "https://w3id.org/aggregator/contexts/aggregator.jsonld",
         {
-            "query": "https://aggregator.example/transformations#query",
-            "source": "https://aggregator.example/transformations#source"
+            "query": "https://aggregator.example/deployments#query",
+            "source": "https://aggregator.example/deployments#source"
         }
     ],
     "@id": "https://aggregator.example/agg1/services/query-view-service/",
     "@type": "ServiceRequest",
-    "performs": "https://aggregator.example/transformations#QueryView",
-    "implements": "https://aggregator.example/transformations#QueryViewIncremunica",
+    "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. Deploying Pipelines

      -

      Deploying a service that performs a composite transformation MUST use the same request format as any other -transformation service. Only a single Service Description Endpoint, for the top-level (composite) transformation, -MUST be exposed; its Service Output Endpoints serve the datasets produced by the composite transformation’s -declared outputs, which are in turn populated from the mapped outputs of the internally deployed constituent -services. A composite transformation MAY either be predefined in a Transformation Catalog, or defined by the -client as a pipeline inline in the request.

      -

      When a client defines a pipeline inline in the request:

      -
        -
      • -

        Constituent functions MUST be reused from a Transformation Catalog

        -
      • -

        Any of the parameters or outputs, MAY be reused from a Transformation Catalog, -using their existing identifiers and predicates.

        -
      • -

        All newly introduced identifiers, namely the composite function itself and any parameters, outputs, or predicates -that cannot be reused from a Transformation Catalog, MUST be scoped to the Instance-Level Transformation -Catalog.

        -
      • -

        The Aggregator MUST add the composite transformation, together with any newly introduced parameters and -outputs, to the Instance-Level Transformation Catalog, so that it can subsequently be referenced using -aggr:performs in the resulting Service description.

        -
      • -

        If a client-proposed identifier is already in use in the Instance-Level Transformation Catalog, the Aggregator -MUST respond with 409 Conflict.

        -
      -
      - - -
      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",
-        {
-            "server-catalog": "https://aggregator.example/transformations#",
-            "inst-catalog": "https://aggregator.example/agg1/transformations#",
-            "query": "server-catalog:query",
-            "mapping": "server-catalog:mapping"
-        }
-    ],
-    "@graph": [
-        {
-            "@id": "https://aggregator.example/agg1/services/pipeline-service/",
-            "@type": "ServiceRequest",
-            "performs": "inst-catalog:RMLQueryPipeline",
-            "mapping": "...",
-            "query": "SELECT * WHERE { ?s ?p ?o }"
-        },
-        {
-            "@id": "inst-catalog:RMLQueryPipeline",
-            "@type": "Function",
-            "expects": [
-                { "@id": "server-catalog:RMLMapping" },
-                { "@id": "server-catalog:QueryString" }
-            ],
-            "returns": [
-                { "@id": "server-catalog:ViewOutput" }
-            ],
-            "composition": {
-                "composedOf": [
-                    {
-                        "mapFrom": {
-                            "constituentFunction": "inst-catalog:RMLQueryPipeline",
-                            "functionParameter": "server-catalog:RMLMapping"
-                        },
-                        "mapTo": {
-                            "constituentFunction": "server-catalog:RMLMapper",
-                            "functionParameter": "server-catalog:RMLMapping"
-                        }
-                    },
-                    {
-                        "mapFrom": {
-                            "constituentFunction": "inst-catalog:RMLQueryPipeline",
-                            "functionParameter": "server-catalog:QueryString"
-                        },
-                        "mapTo": {
-                            "constituentFunction": "server-catalog:QueryView",
-                            "functionParameter": "server-catalog:QueryString"
-                        }
-                    },
-                    {
-                        "mapFrom": {
-                            "constituentFunction": "server-catalog:RMLMapper",
-                            "functionOutput": "server-catalog:KGOutput"
-                        },
-                        "mapTo": {
-                            "constituentFunction": "server-catalog:QueryView",
-                            "functionParameter": "server-catalog:QuerySource",
-                        }
-                    },
-                    {
-                        "mapFrom": {
-                            "constituentFunction": "server-catalog:QueryView",
-                            "functionOutput": "server-catalog:ViewOutput"
-                        },
-                        "mapTo": {
-                            "constituentFunction": "inst-catalog:RMLQueryPipeline",
-                            "functionParameter": "server-catalog:ViewOutput"
-                        }
-                    }
-                ]
-            }
-        }
-    ]
-}
-
      -
      -

      9.1.3. Service Discovery

      +

      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 @@ -4318,7 +3915,7 @@

      9.2.1. Service Output Endpoints

      @@ -4363,138 +3960,6 @@

      9.3. Service Provenance

      -

      This section describes how an Aggregator SHOULD store, expose, and maintain provenance metadata of service outputs. -An Aggregator is not required to manage provenance data. However, if it does, it MUST conform to this specification. -A service’s aggr:ProvenanceLog MUST reference AT LEAST the most recent fno:Execution -(§ 4.5 Execution).

      -

      Aggregators MAY publish a services' Provenance Log as an RDF Document whose base resource, identified by the document’s -own retrieval URL, MUST be described as an aggr:ProvenanceLog (§ 4.6 Provenance Log). Aggregators MUST -publish this document, at any deployment-specific URL of their choosing using the GET method. The endpoint MUST -be advertised in the Service Description through the aggr:provenanceLog predicate. The endpoint SHOULD support HTTP -content negotiation, allowing clients to request different RDF serializations (e.g., Turtle, JSON-LD). The executions that -are defined in the provenance log MAY be embedded in the Provenance Log document or MAY be hosted on separate endpoints -as individual RDF documents.

      -

      If the Provenance Log keeps a history log of multiple executions, it SHOULD be subject to a retention policy -defining how long execution records remain included in the log. This prevents unbounded growth of the log over time -and ensures manageable storage and query performance. If the Provenance Log only retains the most recent execution, versioning -MAY be omitted and the execution can directly reference the dataset from the Service Description.

      -
      - -This example shows a Service Description for a service that updates its dataset on a daily basis. -In this example, the retained executions produce new versions of the logical service dataset, so that dataset is modeled -as a versioned dataset and references concrete dataset versions that are described in the Provenance Log. - -
      @base <https://aggregator.example/agg1/services/service1> .
-@prefix dcat: <http://www.w3.org/ns/dcat#> .
-@prefix dct: <http://purl.org/dc/terms/> .
-@prefix freq: <http://purl.org/cld/freq/> .
-@prefix aggr: <https://w3id.org/aggregator#> .
-@prefix prov: <http://www.w3.org/ns/prov#> .
-@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
-
-<#dataset>
-    a dcat:Dataset ;
-    aggr:forOutput <#result> ;
-    dcat:distribution <#distribution> ;
-    dcat:hasCurrentVersion <https://aggregator.example/agg1/services/service1/provenance#dataset-1> ;
-    dcat:hasVersion
-        <https://aggregator.example/agg1/services/service1/provenance#dataset-0>,
-        <https://aggregator.example/agg1/services/service1/provenance#dataset-1> ;
-    dct:accrualPeriodicity freq:daily ;
-    dct:modified "2025-01-02T12:02:00Z"^^xsd:dateTime .
-
-<>
-    a aggr:Service ;
-    a dcat:DataService ;
-    a prov:SoftwareAgent ;
-    dcat:servesDataset <#dataset> ;
-    aggr:provenanceLog <https://aggregator.example/agg1/services/service1/provenance> ;
-    aggr:performs <https://aggregator.example/transformations#QueryView> .
-
-<#distribution>
-    a dcat:Distribution ;
-    dcat:accessURL <https://aggregator.example/agg1/services/service1/output> ;
-    dcat:accessService <> .
-
      -
      -
      - -The Provenance Log below illustrates two executions of a service that each produce a new version of the logical service dataset. - -
      @base <https://aggregator.example/agg1/services/service1/provenance> .
-@prefix aggr: <https://w3id.org/aggregator#> .
-@prefix fno: <https://w3id.org/function/ontology#> .
-@prefix prov: <http://www.w3.org/ns/prov#> .
-@prefix dcat: <http://www.w3.org/ns/dcat#> .
-@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
-@prefix trans: <https://aggregator.example/transformations#> .
-
-<>
-    a aggr:ProvenanceLog ;
-    aggr:hasActivity <#execution-0>, <#execution-1> .
-
-<#execution-0>
-    a fno:Execution ;
-    a prov:Activity ;
-    fno:executes trans:QueryView ;
-    trans:query "SELECT * WHERE { ?s ?p ?o }" ;
-    trans:source "http://example.org/source1" ;
-    trans:result <#dataset-0> ;
-    prov:wasAssociatedWith <https://aggregator.example/agg1/services/service1> ;
-    prov:qualifiedAssociation [
-        a prov:Association ;
-        prov:agent <https://aggregator.example/agg1/services/service1> ;
-        prov:hadPlan trans:QueryView .
-    ] ;
-    prov:used trans:QueryView ;
-    prov:startedAtTime "2025-01-01T12:00:00Z"^^xsd:dateTime ;
-    prov:endedAtTime "2025-01-01T12:02:00Z"^^xsd:dateTime .
-
-<#execution-1>
-    a fno:Execution ;
-    a prov:Activity ;
-    fno:executes transQueryView ;
-    trans:query "SELECT * WHERE { ?s ?p ?o }" ;
-    trans:source "http://example.org/source1" ;
-    trans:result <#dataset-1> ;
-    prov:wasAssociatedWith <https://aggregator.example/agg1/services/service1> ;
-    prov:qualifiedAssociation [
-        a prov:Association ;
-        prov:agent <https://aggregator.example/agg1/services/service1> ;
-        prov:hadPlan <https://aggregator.example/agg1/services/service1/transformations#QueryView> .
-    ] ;
-    prov:used <https://aggregator.example/agg1/services/service1/transformations#QueryView> ;
-    prov:invalidated <#dataset-0> ;
-    prov:startedAtTime "2025-01-02T12:00:00Z"^^xsd:dateTime ;
-    prov:endedAtTime "2025-01-02T12:02:00Z"^^xsd:dateTime .
-
-<#dataset-0>
-    a dcat:Dataset ;
-    prov:wasGeneratedBy <#execution-0> ;
-    prov:wasInvalidatedBy <#execution-1> ;
-    dcat:isVersionOf <https://aggregator.example/agg1/services/service1#dataset> .
-
-<#dataset-1>
-    a dcat:Dataset ;
-    prov:wasGeneratedBy <#execution-1> ;
-    dcat:isVersionOf <https://aggregator.example/agg1/services/service1#dataset> ;
-    dcat:previousVersion <#dataset-0> .
-
      -
      -

      9.3.1. Continuous updates

      -

      For services that continuously update their data (e.g., event-driven or streaming updates) the execution MUST omit -prov:endedAtTime. All newly generated datasets MUST reference the same ongoing prov:Activity. Creating a new -dcat:Dataset for every minor change may lead to excessive provenance granularity and operational overhead. -Therefore, an Aggregator Server MUST determine an appropriate provenance granularity level based on its use case, -performance constraints, and retention policy. The server MAY choose, for example, to:

      -
        -
      • -

        Apply time-based grouping (e.g., hourly or daily snapshots)

        -
      • -

        Only materialize provenance when used externally (e.g., when dataset was requested)

        -
      -

      The chosen strategy SHOULD be documented and consistently applied to ensure predictable provenance semantics.

      10. Vocabulary

      The Aggregator vocabulary is defined in the aggr: namespace (https://w3id.org/aggregator#). The following classes and properties are used @@ -4510,7 +3975,7 @@

      foaf:Agent

      10.1.2. aggr:Service

      -Represents a configured Aggregator pipeline that can be created, inspected, and removed via the Service +Represents a configured Aggregator Service that can be created, inspected, and removed via the Service Management API (e.g., /services/{service_id}). @@ -4532,10 +3997,10 @@

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

      -

      10.1.5. aggr:TransformationCatalog

      +

      10.1.5. aggr:DeploymentCatalog

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

      type: rdfs:Class
      @@ -4543,7 +4008,7 @@

      hydra:Collection

      10.1.6. aggr:ProvenanceLog

      -Describes the provenance of generated entities and performed executions of a running Aggregator Service +Describes a collection of provenance activities associated with a running Aggregator Service.

      type: rdfs:Class
      @@ -4635,48 +4100,31 @@

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

      -

      10.2.6. aggr:hasTransformation

      +

      10.2.6. aggr:hasDeploymentFunction

      -Links an aggr:TransformationCatalog to a supported fno:Function. Composite transformations are also linked -with this property because they remain fno:Function resources. +Links an aggr:DeploymentCatalog to a supported fno:Function that deploys one or more Aggregator Services.

      type: rdf:Property
      -domain: aggr:TransformationCatalog
      +domain: aggr:DeploymentCatalog
      range: fno:Function

      -

      10.2.7. aggr:hasAppliedTransformation

      +

      10.2.7. aggr:hasAlgorithm

      -Links an aggr:TransformationCatalog to a reusable fno:AppliedFunction template it advertises. +Links an aggr:DeploymentCatalog to an algorithm it supports.

      type: rdf:Property
      -domain: aggr:TransformationCatalog
      -range: fno:AppliedFunction

      -

      10.2.8. aggr:hasAlgorithm

      - -Links an aggr:TransformationCatalog to an algorithm it supports. - - -

      type: rdf:Property
      -domain: aggr:TransformationCatalog
      +domain: aggr:DeploymentCatalog
      range: fno:Algorithm

      -

      10.2.9. aggr:hasMapping

      +

      10.2.8. aggr:hasMapping

      -Links an aggr:TransformationCatalog to a mapping it supports. +Links an aggr:DeploymentCatalog to a mapping it supports.

      type: rdf:Property
      -domain: aggr:TransformationCatalog
      +domain: aggr:DeploymentCatalog
      range: fno:Mapping

      -

      10.2.10. aggr:hasComposition

      - -Links an aggr:TransformationCatalog to a composition it supports. - - -

      type: rdf:Property
      -domain: aggr:TransformationCatalog
      -range: fno:Function

      -

      10.2.11. aggr:status

      +

      10.2.9. aggr:status

      Provides the lifecycle phase of an aggr:Service (values such as running, stopped, or error). @@ -4684,7 +4132,7 @@

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

      -

      10.2.12. aggr:statusDetail

      +

      10.2.10. aggr:statusDetail

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

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

      -

      10.2.13. aggr:performs

      +

      10.2.11. aggr:deploymentFunction

      -Provides the transformation an aggr:Service performs. +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.14. aggr:applies

      - -Links an aggr:Service to the fno:AppliedFunction that captures the configured parameter bindings for that service. - - -

      type: rdf:Property
      -domain: aggr:Service
      -range: fno:AppliedFunction

      -

      10.2.15. aggr:implements

      +

      10.2.12. aggr:implements

      Provides the implementation used by an aggr:Service to perform its transformation. @@ -4718,15 +4159,7 @@

      aggr:Service, aggr:ServiceRequest
      range: fno:Implementation

      -

      10.2.16. aggr:forOutput

      - -Links a dcat:Dataset exposed by an aggr:Service to the fno:Output it represents. - - -

      type: rdf:Property
      -domain: dcat:Dataset
      -range: fno:Output

      -

      10.2.17. aggr:fromAggregator

      +

      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. @@ -4735,7 +4168,7 @@

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

      -

      10.2.18. aggr:fromServer

      +

      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. @@ -4744,7 +4177,7 @@

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

      -

      10.2.19. aggr:fromService

      +

      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. @@ -4754,7 +4187,7 @@

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

      -

      10.2.20. aggr:provenanceLog

      +

      10.2.16. aggr:provenanceLog

      Links an aggr:Service to its provenance log. @@ -4762,15 +4195,15 @@

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

      -

      10.2.21. aggr:hasActivity

      +

      10.2.17. aggr:hasActivity

      Links an aggr:ProvenanceLog to an activity it includes.

      type: rdf:Property
      domain: aggr:ProvenanceLog
      -range: fno:Execution

      -

      10.2.22. aggr:managementEndpoint

      +range: prov:Activity

      +

      10.2.18. aggr:managementEndpoint

      Links an aggr:AggregatorServer to its management endpoint. @@ -4778,7 +4211,7 @@

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

      -

      10.2.23. aggr:supportedManagementFlow

      +

      10.2.19. aggr:supportedManagementFlow

      Lists the management flows advertised by an aggr:AggregatorServer. @@ -4786,7 +4219,7 @@

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

      -

      10.2.24. aggr:managementRequestFormatSupported

      +

      10.2.20. aggr:managementRequestFormatSupported

      Lists the supported request formats for an aggr:AggregatorServer management endpoint. @@ -4794,7 +4227,7 @@

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

      -

      10.2.25. aggr:specVersion

      +

      10.2.21. aggr:specVersion

      States which version of this specification an aggr:AggregatorServer implements. @@ -4802,7 +4235,7 @@

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

      -

      10.2.26. aggr:clientIdentifier

      +

      10.2.22. aggr:clientIdentifier

      Links an aggr:AggregatorServer to its Client ID Document. @@ -4810,15 +4243,15 @@

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

      -

      10.2.27. aggr:transformationCatalog

      +

      10.2.23. aggr:deploymentCatalog

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

      type: rdf:Property
      domain: aggr:Aggregator, aggr:AggregatorServer
      -range: aggr:TransformationCatalog

      +range: aggr:DeploymentCatalog

      10.3. Claim Types

      10.3.1. aggr:transformation-description

      @@ -4827,7 +4260,7 @@

      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 transformation catalog entry). Acceptable claim_token_format values are URIs identifying RDF +reference to a deployment 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

      diff --git a/dist/spec.bs b/dist/spec.bs index e9e32f6..d899556 100644 --- a/dist/spec.bs +++ b/dist/spec.bs @@ -88,16 +88,15 @@ spec: HTML; urlPrefix: https://html.spec.whatwg.org/multipage/# Introduction {#introduction} ==================== -This specification defines the Aggregator Protocol, an HTTP-based interface that lets a client create and manage Aggregator -Instances and configure Aggregator Services that execute data transformations. Transformations are described and discovered -using the Function Ontology (FnO) [[!FNO]]; a service is configured by referencing a transformation (a `fno:Function`) and -providing its parameters (using an `fno:AppliedFunction`), after which the client can retrieve the derived result from the -output defined by that function. +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 transformation catalog ([[#aggregator-server-metadata]]). Using the management +management flows, and the server’s deployment catalog ([[#aggregator-server-metadata]]). Using the management endpoint, a client creates (or manages) an Aggregator Instance ([[#aggregator-management]]) and then follows the -instance’s Aggregator Description to find the instance’s service collection and transformations endpoint +instance’s Aggregator Description to find the instance’s service collection and deployment catalog ([[#aggregator-description]] and [[#aggregator-service-management]]). Management operations are authenticated and authorized unless a specific management flow explicitly allows unauthenticated @@ -128,12 +127,12 @@ Core Roles and Components {#definitions-core} - **Aggregator Instance** (or “Aggregator”): A user- or tenant-scoped logical instance created via the management endpoint. An instance exposes an Aggregator Description and an authenticated management API for configuring services. -- **Aggregator Service** (or “Service”): A configured data processing pipeline inside an Aggregator Instance. A service is - represented as an FnO Implementation (`fno:Implementation`) that implements an FnO AppliedFunction (`fno:AppliedFunction`), - which defines inputs and outputs (see [[#aggregator-service-management]]). +- **Aggregator Service** (or “Service”): A deployed `dcat:DataService` and `prov:SoftwareAgent` inside an Aggregator + Instance. It serves one or more datasets and links to the FnO deployment function used to create it (see + [[#aggregator-service-management]]). -- **Transformation Catalog:** A catalog that describes the FnO Functions supported by the Aggregator Server and the FnO AppliedFunctions hosted on an Aggregator - Instance (see [[#server-level-transformation-catalog]] and [[#instance-level-transformation-catalog]]). +- **Deployment Catalog:** A catalog of FnO deployment functions supported by an Aggregator Server or Aggregator + Instance (see [[#server-level-deployment-catalog]] and [[#instance-level-deployment-catalog]]). Identity, Authorization, and Tokens {#definitions-security} ---------------------------------------------------------- @@ -175,7 +174,6 @@ The following namespace prefixes are used throughout this specification and **SH - `aggr:` → `https://w3id.org/aggregator#` - `dct:` → `http://purl.org/dc/terms/` - `fno:` → `https://w3id.org/function/ontology#` -- `fnoc:` → `https://fno.io/vocabulary/composition/0.1.0/` - `dcat:` → `http://www.w3.org/ns/dcat#` - `rdf:` → `http://www.w3.org/1999/02/22-rdf-syntax-ns#` - `rdfs:` → `http://www.w3.org/2000/01/rdf-schema#` @@ -200,7 +198,7 @@ This specification defines HTTP resources at three levels: - **Aggregator Instance resources:** instance metadata and service management (see [[#aggregator-metadata]] and [[#aggregator-service-management]]). - **Aggregator Service resources:** a service collection and individual services managed under the instance (see - [[#service-discovery]] and service resource and provenance). + [[#service-discovery]] and the service resource). 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: @@ -235,7 +233,7 @@ Security Boundaries {#security-boundaries} All security requirements are defined in [[#aggregator-security-model]]. At a high level: - **Server-level discovery resources:** deployments **MAY** expose the server description (see [[#server-description]]) and - the server-level transformation catalog (see [[#server-level-transformation-catalog]]) without authentication, or **MAY** + the server-level deployment catalog (see [[#server-level-deployment-catalog]]) without authentication, or **MAY** protect them using an OpenID Connect (OIDC) ID Token. The Client ID Document (see [[#client-id-document]]) is typically accessible without authentication. - **Management endpoint:** deployments **MAY** protect the management endpoint (see [[#aggregator-management]]) using OIDC. @@ -260,9 +258,9 @@ Service in a path-based deployment: - Server description: `https://aggregator.example/` - Aggregator Management: `https://aggregator.example/registration` - Client ID Document: `https://aggregator.example/client.jsonld` -- Transformation catalog: `https://aggregator.example/transformations` +- Deployment catalog: `https://aggregator.example/deployments` - Instance description: `https://aggregator.example/agg1/` -- Instance Transformation catalog: `https://aggregator.example/agg1/transformations` +- Instance Deployment catalog: `https://aggregator.example/agg1/deployments` - Service collection: `https://aggregator.example/agg1/services` - Service description: `https://aggregator.example/agg1/services/service1/` - Service output: `https://aggregator.example/agg1/services/service1/output` @@ -272,9 +270,9 @@ Service in a path-based deployment: Aggregator Data Model {#data-model} ============================================== -This section specifies the data model used to describe the aggregator components like running aggregator services -and the transformations they implement as well as the outputs they generate. By describing them as linked data the -model enables interoperable publication, discovery, execution, and provenance tracking of aggregator services. +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 @@ -285,47 +283,54 @@ specialized member names: `https://w3id.org/aggregator/contexts/aggregator-serve [[#server-description]] and `https://w3id.org/aggregator/contexts/aggregator-description.jsonld` for the [[#aggregator-description]]. -Transformation {#data-model-transformation} -------------------------------------------- - -An aggregator transformation defines a well-described functional interface using the Function Ontology [[!FNO]]. -Each transformation **MUST** be described as an `fno:Function` that **SHOULD** use `dct:description` to provide a -human-readable description of the transformation. Each transformation **MAY** use a `fno:name` to provide a short name for -the transformation, but clients **SHOULD NOT** rely on this property for unique identification. The transformation **MAY** -describe zero or more `fno:Parameters` and `fno:Outputs` using the `fno:expects` and `fno:returns` properties respectively. -Each parameter and output: - - **MUST** be a `fno:Parameter` or `fno:Output` respectively. - - **MUST** use `fno:predicate` to specify the predicate that will be used to signify its - value used by an `fno:Execution` and `aggr:ServiceRequest`. - - **MUST** define the `fno:type` of the output as a `dcat:Dataset`. - - **SHOULD** use `fno:type` to describe the parameter types. - - **MAY** use `dct:format` to describe the format of the parameter. - - **MAY** use `dct:conformsTo` to signify the parameter follows a certain specification/protocol. - - **MAY** use `dct:conformsTo` to signify the output follows a certain shape. If such a shape is defined, the dataset - generated for that output and the distributions referenced from that dataset **MUST** conform to it. - - **MAY** use `fno:required` to indicate whether the parameter is required or optional. If not specified, clients **MUST** - assume the parameter is optional. - -Additional metadata **MAY** be linked to a transformation, such as an `fno:Implementation` using an `fno:Mapping`, or the -algorithm it implements using `fno:Algorithm` as specified by [[!FNO]]. +Deployment Function {#data-model-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: + - **MUST** be described as an `fno:Function`. + - **SHOULD** use `dct:description` to provide a human-readable description. + - **MAY** use `fno:name` to provide a short name, but clients **SHOULD NOT** rely on this property for unique + identification. + - **MAY** describe zero or more `fno:Parameter` resources using `fno:expects`. + - **MUST** describe exactly one `fno:Output` using `fno:returns`. + +Each parameter: + - **MUST** be an `fno:Parameter`. + - **MUST** use `fno:predicate` to specify the predicate used to provide its value in an `aggr:ServiceRequest`. + - **SHOULD** use `fno:type` to describe the parameter type. + - **MAY** use `dct:format` to describe the parameter format. + - **MAY** use `dct:conformsTo` to indicate that the parameter follows a specification or protocol. + - **MAY** use `fno:required` to indicate whether the parameter is required or optional. If this property is absent, + clients **MUST** assume the parameter is optional. + +The output: + - **MUST** be an `fno:Output`. + - **MUST** have `aggr:Service` as its `fno:type`. + - **MUST** use `fno:predicate` to specify the output predicate. + - **MAY** use `dct:conformsTo` to further describe the kind of service produced by the deployment function. This + specification does not prescribe the referenced description or profile. + +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]].
      ```turtle -@base . -@prefix dcat: . +@base . +@prefix aggr: . @prefix fno: . -@prefix rr: . -@prefix sh: . @prefix xsd: . @prefix dct: . -@prefix rdf: . - + a fno:Function ; fno:name "The SPARQL QueryView function"^^xsd:string ; - dct:description "Performs a query on a source and materializes view as a SPARQL endpoint"^^xsd:string ; + dct:description "Deploys a service that exposes a materialized SPARQL query view"^^xsd:string ; fno:expects ( ) ; - fno:returns ( ) . + fno:returns ( ) . a fno:Parameter ; @@ -340,118 +345,41 @@ algorithm it implements using `fno:Algorithm` as specified by [[!FNO]]. dct:conformsTo ; fno:required "true"^^xsd:boolean . - - a fno:Output ; - fno:type dcat:Dataset ; - dct:conformsTo ex:SPARQLResultDatasetShape . - fno:predicate . - - - a sh:NodeShape ; - sh:targetClass dcat:Dataset ; - sh:property [ - sh:path dcat:distribution ; - sh:minCount 1 ; - sh:node - ] ; - sh:property [ - sh:path dcat:distribution ; - sh:minCount 1 ; - sh:node - ] . - - - a sh:NodeShape ; - sh:property [ - sh:path dcat:mediaType ; - sh:hasValue - ] . - - - a sh:NodeShape ; - sh:property [ - sh:path dcat:mediaType ; - sh:hasValue - ] . - - - a fno:Function ; - fno:name "The RML Mapper Function"^^xsd:string ; - dct:description "Performs RML mappings on a source and materializes results as a SPARQL endpoint"^^xsd:string ; - fno:expects ( ) ; - fno:returns ( ) . - - - a fno:Parameter ; - fno:type rr:TriplesMap ; - dct:format ; - fno:predicate ; - fno:required "true"^^xsd:boolean . - - + a fno:Output ; - fno:type dcat:Dataset ; - fno:predicate . + fno:type aggr:Service ; + fno:predicate ; + dct:conformsTo . ```
      -An Applied Transformation is a Transformation in which one or more parameters are bound to concrete values and is -represented using an `fno:AppliedFunction` from [[!FNO]]. - -
      -```turtle -@base . -@prefix fno: . -@prefix fnoc: . -@prefix xsd: . - - - a fno:AppliedFunction ; - fnoc:applies ; - fnoc:parameterBindings ( - [ - fnoc:boundParameter ; - fnoc:boundToTerm "http://example.org/source" - ] - [ - fnoc:boundParameter ; - fnoc:boundToTerm "SELECT * WHERE { ?person foaf:givenName ?name }"^^xsd:string - ] - ) . -``` -
      - -Transformation Catalog {#data-model-tf-catalog} ------------------------------------------------ +Deployment Catalog {#data-model-deployment-catalog} +--------------------------------------------------- -A Transformation Catalog references all transformations made available on an Aggregator Server including any metadata -mentioned earlier. +A Deployment Catalog references all deployment functions made available on an Aggregator Server. -The Transformation Catalog: - - **MUST** be described as an `aggr:TransformationCatalog`. - - **MUST** reference all supported (applied) transformations using `aggr:hasTransformation`. +The Deployment Catalog: + - **MUST** be described as an `aggr:DeploymentCatalog`. + - **MUST** reference all supported deployment functions using `aggr:hasDeploymentFunction`. - **MAY** reference a supported algorithm using `aggr:hasAlgorithm`. - **MAY** reference a supported mapping using `aggr:hasMapping`. - **MUST** reference all resources not hosted by the Aggregator Server using `rdfs:seeAlso`.
      ```turtle -@base . +@base . @prefix aggr: . @prefix dcat: . @prefix dct: . @prefix rdfs: . @prefix fno: . -@prefix fnoc: . @prefix rdf: . @prefix xsd: . @prefix foaf: -<> a aggr:TransformationCatalog ; - aggr:hasTransformation - , - , - , +<> a aggr:DeploymentCatalog ; + aggr:hasDeploymentFunction + , ; rdfs:seeAlso . ``` @@ -463,22 +391,19 @@ Service {#data-model-service} A deployed aggregator service is the running resource created from a service request and **MUST** be modelled as: - an `aggr:Service` - a `dcat:DataService` ([[!Data-Catalog]]) - - a `prov:SoftwareAgent` ([[!PROV-O]]) Furthermore, the service: - - **MUST** serve exactly one dataset for each output of the transformation identified by `aggr:performs`. - - **MUST** link using `aggr:performs` to the underlying `fno:Function`. - - **MUST** link using `dcat:servesDataset` to the corresponding dataset described as a `dcat:Dataset`. + - **MUST** link using `aggr:deploymentFunction` to the `fno:Function` used to deploy it. + - **MUST** link using `dcat:servesDataset` to one or more datasets described as `dcat:Dataset` resources. - **SHOULD** declare operational metadata such as status and creation time. - **SHOULD** indicate it adheres to the aggregator protocol using `dct:conformsTo`. - - **MAY** link using `aggr:applies` to an applied transformation that applies the performed function - with a set of input values when the usecase allows these to be disclosed. - - **MAY** specify the exact implementation using a link to an `fno:Implementation` with `aggr:implements`. -The corresponding dataset: +Each corresponding dataset: - **MUST** be described as a `dcat:Dataset`. - - **MUST** link to exactly one `fno:Output` of that transformation using `aggr:forOutput`. - - **MUST** reference a `dcat:distribution`. + - **MAY** reference one or more `dcat:Distribution` resources using `dcat:distribution`. + +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: - **MUST** reference the corresponding output endpoint using `dcat:accessURL`. @@ -496,8 +421,7 @@ or describe the service API using the Hydra Core Ontology ([[!Hydra]]).
      ```turtle @base . -@prefix inst-trans: . -@prefix server-trans: . +@prefix server-deploy: . @prefix aggr: . @prefix dcat: . @prefix prov: . @@ -510,14 +434,12 @@ or describe the service API using the Hydra Core Ontology ([[!Hydra]]). a prov:SoftwareAgent ; aggr:status "running" ; aggr:createdAt "2024-01-01T12:00:00Z"^^xsd:dateTime ; - aggr:performs server-trans:QueryView ; - aggr:applies inst-trans:QueryViewApplied ; + aggr:deploymentFunction server-deploy:QueryViewDeployment ; dct:conformsTo ; dcat:servesDataset <#dataset> . <#dataset> a dcat:Dataset ; - aggr:forOutput server-trans:ViewOutput ; dcat:distribution <#distribution-xml> , <#distribution-json> . @@ -556,121 +478,12 @@ The Service Collection: ```
      -Execution {#data-model-service-execution} ------------------------------------------ - -An Execution represents the service output provenance information. Each execution: - - **MUST** be a `fno:Execution`. - - **MUST** link to the executed transformation using `fno:executes`. - - **MUST** link to the generated datasets using the output predicates defined in [[#data-model-transformation]]. - - **MUST** link to the used parameter values using the parameter predicates defined in [[#data-model-transformation]]. - - **MAY** link to the used mapping using `fno:uses` to indicate the used implementation - - **MUST** be a `prov:Activity`. - - **MUST** be associated with the service using `prov:associatedWith`. - - **MUST** include a start time using `prov:startedAtTime`. - - **MAY** include an end time using `prov:endedAtTime`. - -The execution **MAY** provide additional metadata such as `prov:qualifiedAssociation`, or any other -relevant provenance information. The executed transformation **MUST** be the same as the transformation declared in the -service description using `aggr:performs`. - -The generated dataset produced by an execution either *is* the logical dataset served by the -service, or it is a distinct version of that logical dataset, depending on whether the service -retains version history. - -In either case, the generated dataset: - - **MUST** be typed as a `dcat:Dataset`. - - **MUST** be typed as a `prov:Entity`. - - **MUST** link to the execution using `prov:wasGeneratedBy`. - - **SHOULD** include `prov:wasGeneratedAtTime`. - -If the service retains version history, the generated dataset additionally: - - **MUST** specify it is a version of the service dataset using `dcat:isVersionOf`. - -If the service retains version history, the logical dataset: - - **MUST** declare the latest known version using `dcat:hasCurrentVersion`. - - **MUST** declare other known versions using `dcat:hasVersion`. - -The following example shows an execution that produces a new version of a service dataset. - -
      -```turtle -@base . -@prefix svc: . -@prefix server-trans: . -@prefix aggr: . -@prefix fno: . -@prefix dcat: . -@prefix prov: . -@prefix xsd: . - - - a fno:Execution ; - a prov:Activity ; - fno:executes server-trans:sparql-query-view ; - server-trans:query "SELECT * WHERE { ?s ?p ?o }" ; - server-trans:source "http://example.org/source1" ; - server-trans:view ; - prov:associatedWith ; - prov:startedAtTime "2025-01-02T12:00:00Z"^^xsd:dateTime ; - prov:endedAtTime "2025-01-02T12:02:00Z"^^xsd:dateTime . - - - a dcat:Dataset ; - a prov:Entity ; - dcat:isVersionOf svc:dataset ; - prov:wasGeneratedBy ; - prov:wasGeneratedAtTime "2025-01-02T12:02:00Z"^^xsd:dateTime . -``` -
      - -With the logical dataset referencing the generated datasets. - -
      -```turtle -@base : . -@prefix provlog: . -@prefix server-trans: . -@prefix aggr: . -@prefix fno: . -@prefix dcat: . -@prefix prov: . -@prefix xsd: . - -<#dataset> - a dcat:Dataset ; - aggr:forOutput server-trans:view-output ; - dcat:distribution <#distribution-xml> , - <#distribution-json> ; - dcat:hasCurrentVersion provlog:dataset-1 ; - dcat:hasVersion provlog:dataset-0 , - provlog:dataset-1 . -``` -
      - Provenance Log {#data-model-provenance-log} ------------------------------------------- -A Provenance Log consolidates all service output provenance information by referencing executions. - -The Provenance Log: - - **MUST** be described as an `aggr:ProvenanceLog`. - - **MUST** reference one or more execution activities using `aggr:hasActivity`. - -The Service: - - **MUST** link its provenance log using `aggr:provenanceLog`. - - -
      -```turtle -@base -@prefix aggr: . - -<> - a aggr:ProvenanceLog ; - aggr:hasActivity :execution-0 . -``` -
      +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`. @@ -721,10 +534,10 @@ in Turtle). Clients **MAY** rely on this type statement when consuming semantic :: The value is a string containing the absolute URL of the Client ID Document ([[#client-id-document]]); in the RDF representations, this member maps to the predicate `aggr:clientIdentifier` ([[#clientIdentifier]]). -: **transformation_catalog** (REQUIRED): -:: The value is a string containing the absolute URL of the server-level Transformation Catalog - ([[#server-level-transformation-catalog]]); in the RDF representations, this member maps to the predicate - `aggr:transformationCatalog` ([[#transformationCatalog]]). +: **deployment_catalog** (REQUIRED): +:: The value is a string containing the absolute URL of the server-level Deployment Catalog + ([[#server-level-deployment-catalog]]); in the RDF representations, this member maps to the predicate + `aggr:deploymentCatalog` ([[#deploymentCatalog]]).
      ```json @@ -743,7 +556,7 @@ in Turtle). Clients **MAY** rely on this type statement when consuming semantic ], "version": "1.0.0", "client_identifier": "https://aggregator.example/client.jsonld", - "transformation_catalog": "https://aggregator.example/transformations" + "deployment_catalog": "https://aggregator.example/deployments" } ```
      @@ -759,90 +572,18 @@ aggregator, the `redirect_uris` property is **OPTIONAL** instead of **REQUIRED** 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. -Server-level Transformation Catalog {#server-level-transformation-catalog} --------------------------------------------------------------------------- +Server-level Deployment Catalog {#server-level-deployment-catalog} +------------------------------------------------------------------ -The Transformation Catalog is an RDF document whose base resource, identified by the document's -own retrieval URL, **MUST** be described as an `aggr:TransformationCatalog` ([[#data-model-tf-catalog]]). -Resources referenced by the Transformation Catalog **MAY** either be included directly in the RDF document or +The Deployment Catalog is an RDF document whose base resource, identified by the document's +own retrieval URL, **MUST** be described as an `aggr:DeploymentCatalog` ([[#data-model-deployment-catalog]]). +Resources referenced by the Deployment 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 [[#server-description]] via the `transformation_catalog` field. +The URL **MUST** be advertised in the [[#server-description]] via the `deployment_catalog` field. The catalog **SHOULD** support HTTP content negotiation, allowing clients to request different RDF serializations -(e.g., Turtle, JSON-LD). - -A transformation **MAY** be linked to an `fnoc:Composition` using `fnoc:composition`. This **MAY** be done -solely to describe the internal structure of a transformation. In this case, the composition serves as descriptive metadata -to provide additional transparency. Composite transformations remain `fno:Function` resources and therefore **MUST** be -advertised using `aggr:hasTransformation`. If all transformations referenced within the `fnoc:Composition` are also -included in the catalog, each of them represents a deployable service. This enables an Aggregator to expose a pipeline as a -single service while internally orchestrating multiple individual services. - -
      -The following example describes a pipeline that: - 1. Uses RML to map a non-RDF source. - 2. Executes a query over the generated RDF. - 3. Exposes the resulting query output. - -```turtle -@base . -@prefix aggr: . -@prefix dct: . -@prefix fno: . -@prefix fnoc: . - -<> a aggr:TransformationCatalog ; - dct:title "Aggregator transformations" ; - aggr:hasTransformation ; - aggr:hasTransformation ; - aggr:hasTransformation ; - - - a fno:Function ; - fno:expects ( ) ; - fno:returns ( ) ; - fno:composition [ - fnoc:composedOf [ - fnoc:mapFrom [ - fnoc:constituentFunction ; - fnoc:functionParameter . - ] ; - fnoc:mapTo [ - fnoc:constituentFunction ; - fnoc:functionParameter . - ] . - ],[ - fnoc:mapFrom [ - fnoc:constituentFunction ; - fnoc:functionParameter . - ] ; - fnoc:mapTo [ - fnoc:constituentFunction ; - fnoc:functionParameter . - ] . - ],[ - fnoc:mapFrom [ - fnoc:constituentFunction ; - fnoc:functionParameter . - ] ; - fnoc:mapTo [ - fnoc:constituentFunction ; - fnoc:functionParameter ; - ] . - ],[ - fnoc:mapFrom [ - fnoc:constituentFunction ; - fnoc:functionOutput . - ] ; - fnoc:mapTo [ - fnoc:constituentFunction ; - fnoc:functionParameter . - ] . - ] . - ] . -``` -
      +(e.g., Turtle, JSON-LD). @@ -1796,7 +1537,7 @@ Aggregator Metadata {#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 -`transformation_catalog` and `service_collection_endpoint` fields) so clients can discover the deployment-specific layout. +`deployment_catalog` and `service_collection_endpoint` fields) so clients can discover the deployment-specific layout. Aggregator Description {#aggregator-description} ---------------------------------------------------------- @@ -1829,10 +1570,10 @@ that the described resource has RDF type `aggr:Aggregator` ([[#Aggregator]]) (e. :: 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` ([[#tokenExpiry]]). -: **transformation_catalog** (**REQUIRED**): -:: The value is a string containing the absolute URL of the instance’s Transformations Endpoint - ([[#instance-level-transformation-catalog]]); in the RDF representations, this member maps to the predicate - `aggr:transformationCatalog` ([[#transformationCatalog]]). +: **deployment_catalog** (**REQUIRED**): +:: The value is a string containing the absolute URL of the instance’s Deployment Catalog + ([[#instance-level-deployment-catalog]]); in the RDF representations, this member maps to the predicate + `aggr:deploymentCatalog` ([[#deploymentCatalog]]). : **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 ([[#service-collection-endpoint]]); in the RDF representations, this member maps to the predicate @@ -1850,27 +1591,25 @@ that case this document **MUST** be an RDF document that conforms to the WebID P "created_at": "2025-12-17T17:20:00Z", "login_status": true, "token_expiry": "2025-12-17T18:20:00Z", - "transformation_catalog": "https://aggregator.example/aggregators/agg-7890/transformations", + "deployment_catalog": "https://aggregator.example/aggregators/agg-7890/deployments", "service_collection_endpoint": "https://aggregator.example/aggregators/agg-7890/services", "oidcIssuer": "https://issuer.example/" } ```
      -Instance-level Transformation Catalog {#instance-level-transformation-catalog} ------------------------------------------------------------------------------- +Instance-level Deployment Catalog {#instance-level-deployment-catalog} +--------------------------------------------------------------------- -This endpoint is the instance-level extension of the server-level Transformation Catalog defined in -[[#server-level-transformation-catalog]]. It allows the Aggregator Server to make certain transformations available -only to specific Aggregator instances, by curating the catalog's contents per instance. This Instance-Level -Transformation Catalog also includes all Applied Transformations used by the Aggregator's deployed Services, -as well as all client-defined pipelines (further explained in [[#service-deployment]]). +This endpoint is the instance-level extension of the server-level Deployment Catalog defined in +[[#server-level-deployment-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 [[#aggregator-description]] via the `instance_transformation_catalog` field. The endpoint -**MUST** follow the same content negotiation rules, and other requirements, as the server-level Transformation -Catalog. Resources referenced by this Instance-Level Transformation Catalog **MAY** either be included directly in -the RDF document or hosted by the Aggregator Server in separate documents. This Instance-Level Transformation +be advertised in the [[#aggregator-description]] via the `deployment_catalog` field. The endpoint +**MUST** follow the same content negotiation rules, and other requirements, as the server-level Deployment +Catalog. Resources referenced by this Instance-Level Deployment Catalog **MAY** either be included directly in +the RDF document or hosted by the Aggregator Server in separate documents. This Instance-Level Deployment Catalog, along with each resource referenced by it, **MUST** be protected using the [[#aggregator-security-model]]. @@ -1914,7 +1653,7 @@ least the predefined JSON-LD context `https://w3id.org/aggregator/contexts/aggre The `aggr:ServiceRequest`: - **MUST** be the only `aggr:ServiceRequest` described in the request body. - **MUST** be identified using either a unique URI or a blank node. -- **MUST** declare a Transformation using `performs`. +- **MUST** identify a deployment function using `deploymentFunction`. - **MUST** provide inputs for at least all required parameters, using the parameter predicates defined using `fno:predicate` in the function description. - **MAY** specify an implementation to use with `implements`. @@ -1926,12 +1665,10 @@ the server **MUST** respond with `409 Conflict`. Upon successful processing, the Aggregator **MUST**: -1. Include an Applied Transformation representing the performed Transformation with the given inputs to the - Instance-Level Transformation Catalog. This resource **MUST** be referenced using `aggr:applies` and protected - using the [[#aggregator-security-model]]. -2. Deploy a new Service that performs the transformation indicated by `performs` (and, if present, the implementation - indicated by `implements`), and expose a Service Description Endpoint [[#service-endpoint]] describing it according - to the data model in [[#data-model-service]]. +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 [[#service-endpoint]], describing it according + to the data model in [[#data-model-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. @@ -1943,11 +1680,11 @@ Error Responses: - **MUST** respond with `400 Bad Request` if the requested URI is syntactically invalid or not permitted. - **MUST** respond with `409 Conflict` if the requested URI is valid but already in use. - **MUST** respond with `400 Bad Request` if the request body is syntactically malformed or semantically invalid - (e.g., missing required parameter bindings or referencing an unknown transformation). + (e.g., missing required parameter values or referencing an unknown deployment function). - **MUST** respond with `500 Internal Server Error` if the request is valid but the Aggregator fails to deploy the Service. -The following example depicts a request that deploys a service performing the `QueryView` Transformation. +The following example depicts a request that invokes the `QueryViewDeployment` deployment function.
      ```http @@ -1959,126 +1696,20 @@ Content-Type: application/ld+json "@context": [ "https://w3id.org/aggregator/contexts/aggregator.jsonld", { - "query": "https://aggregator.example/transformations#query", - "source": "https://aggregator.example/transformations#source" + "query": "https://aggregator.example/deployments#query", + "source": "https://aggregator.example/deployments#source" } ], "@id": "https://aggregator.example/agg1/services/query-view-service/", "@type": "ServiceRequest", - "performs": "https://aggregator.example/transformations#QueryView", - "implements": "https://aggregator.example/transformations#QueryViewIncremunica", + "deploymentFunction": "https://aggregator.example/deployments#QueryViewDeployment", + "implements": "https://aggregator.example/deployments#QueryViewIncremunica", "query": "SELECT * WHERE { ?s ?p ?o }", "source": "http://example.org/source" } ```
      -### Deploying Pipelines ### {#pipeline-deployment} - -Deploying a service that performs a composite transformation **MUST** use the same request format as any other -transformation service. Only a single Service Description Endpoint, for the top-level (composite) transformation, -**MUST** be exposed; its Service Output Endpoints serve the datasets produced by the composite transformation's -declared outputs, which are in turn populated from the mapped outputs of the internally deployed constituent -services. A composite transformation **MAY** either be predefined in a Transformation Catalog, or defined by the -client as a pipeline inline in the request. - -When a client defines a pipeline inline in the request: - - Constituent functions **MUST** be reused from a Transformation Catalog - - Any of the parameters or outputs, **MAY** be reused from a Transformation Catalog, - using their existing identifiers and predicates. - - All newly introduced identifiers, namely the composite function itself and any parameters, outputs, or predicates - that cannot be reused from a Transformation Catalog, **MUST** be scoped to the Instance-Level Transformation - Catalog. - - The Aggregator **MUST** add the composite transformation, together with any newly introduced parameters and - outputs, to the Instance-Level Transformation Catalog, so that it can subsequently be referenced using - `aggr:performs` in the resulting Service description. - - If a client-proposed identifier is already in use in the Instance-Level Transformation Catalog, the Aggregator - **MUST** respond with `409 Conflict`. - -
      -```http -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", - { - "server-catalog": "https://aggregator.example/transformations#", - "inst-catalog": "https://aggregator.example/agg1/transformations#", - "query": "server-catalog:query", - "mapping": "server-catalog:mapping" - } - ], - "@graph": [ - { - "@id": "https://aggregator.example/agg1/services/pipeline-service/", - "@type": "ServiceRequest", - "performs": "inst-catalog:RMLQueryPipeline", - "mapping": "...", - "query": "SELECT * WHERE { ?s ?p ?o }" - }, - { - "@id": "inst-catalog:RMLQueryPipeline", - "@type": "Function", - "expects": [ - { "@id": "server-catalog:RMLMapping" }, - { "@id": "server-catalog:QueryString" } - ], - "returns": [ - { "@id": "server-catalog:ViewOutput" } - ], - "composition": { - "composedOf": [ - { - "mapFrom": { - "constituentFunction": "inst-catalog:RMLQueryPipeline", - "functionParameter": "server-catalog:RMLMapping" - }, - "mapTo": { - "constituentFunction": "server-catalog:RMLMapper", - "functionParameter": "server-catalog:RMLMapping" - } - }, - { - "mapFrom": { - "constituentFunction": "inst-catalog:RMLQueryPipeline", - "functionParameter": "server-catalog:QueryString" - }, - "mapTo": { - "constituentFunction": "server-catalog:QueryView", - "functionParameter": "server-catalog:QueryString" - } - }, - { - "mapFrom": { - "constituentFunction": "server-catalog:RMLMapper", - "functionOutput": "server-catalog:KGOutput" - }, - "mapTo": { - "constituentFunction": "server-catalog:QueryView", - "functionParameter": "server-catalog:QuerySource", - } - }, - { - "mapFrom": { - "constituentFunction": "server-catalog:QueryView", - "functionOutput": "server-catalog:ViewOutput" - }, - "mapTo": { - "constituentFunction": "inst-catalog:RMLQueryPipeline", - "functionParameter": "server-catalog:ViewOutput" - } - } - ] - } - } - ] -} -``` -
      - ### Service Discovery ### {#service-discovery} The Service Collection Endpoint **MUST** expose an RDF document whose base resource, identified by the document's @@ -2118,7 +1749,7 @@ service. This endpoint **SHOULD** support HTTP content negotiation as defined in 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 the the `GET` and `DELETE` methods, the server **MAY** support: +Next to the `GET` and `DELETE` methods, the server **MAY** support: : `PATCH` :: Updates the service description (as defined in [[#data-model-service]]). @@ -2140,7 +1771,7 @@ Next the the `GET` and `DELETE` methods, the server **MAY** support: 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`, `dcat:distribution`, and `aggr:provenanceLog`. If a `PATCH` or +`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`. @@ -2151,142 +1782,6 @@ corresponding service `dcat:Distribution`. Each Service Output Endpoint is the a It is distinct from the `dcat:Dataset` resource identified in the service description and **MUST NOT** itself be interpreted as the dataset. -Service Provenance {#service-provenance} ----------------------------------------- - -This section describes how an Aggregator **SHOULD** store, expose, and maintain provenance metadata of service outputs. -An Aggregator is not required to manage provenance data. However, if it does, it **MUST** conform to this specification. -A service’s `aggr:ProvenanceLog` **MUST** reference **AT LEAST** the most recent `fno:Execution` -([[#data-model-service-execution]]). - -Aggregators **MAY** publish a services' Provenance Log as an RDF Document whose base resource, identified by the document's -own retrieval URL, **MUST** be described as an `aggr:ProvenanceLog` ([[#data-model-provenance-log]]). Aggregators **MUST** -publish this document, at any deployment-specific URL of their choosing using the `GET` method. The endpoint **MUST** -be advertised in the Service Description through the `aggr:provenanceLog` predicate. The endpoint **SHOULD** support HTTP -content negotiation, allowing clients to request different RDF serializations (e.g., Turtle, JSON-LD). The executions that -are defined in the provenance log **MAY** be embedded in the Provenance Log document or **MAY** be hosted on separate endpoints -as individual RDF documents. - -If the Provenance Log keeps a history log of multiple executions, it **SHOULD** be subject to a retention policy -defining how long execution records remain included in the log. This prevents unbounded growth of the log over time -and ensures manageable storage and query performance. If the Provenance Log only retains the most recent execution, versioning -**MAY** be omitted and the execution can directly reference the dataset from the Service Description. - -
      -This example shows a Service Description for a service that updates its dataset on a daily basis. -In this example, the retained executions produce new versions of the logical service dataset, so that dataset is modeled -as a versioned dataset and references concrete dataset versions that are described in the Provenance Log. -```turtle -@base . -@prefix dcat: . -@prefix dct: . -@prefix freq: . -@prefix aggr: . -@prefix prov: . -@prefix xsd: . - -<#dataset> - a dcat:Dataset ; - aggr:forOutput <#result> ; - dcat:distribution <#distribution> ; - dcat:hasCurrentVersion ; - dcat:hasVersion - , - ; - dct:accrualPeriodicity freq:daily ; - dct:modified "2025-01-02T12:02:00Z"^^xsd:dateTime . - -<> - a aggr:Service ; - a dcat:DataService ; - a prov:SoftwareAgent ; - dcat:servesDataset <#dataset> ; - aggr:provenanceLog ; - aggr:performs . - -<#distribution> - a dcat:Distribution ; - dcat:accessURL ; - dcat:accessService <> . -``` -
      - -
      -The Provenance Log below illustrates two executions of a service that each produce a new version of the logical service dataset. -```turtle -@base . -@prefix aggr: . -@prefix fno: . -@prefix prov: . -@prefix dcat: . -@prefix xsd: . -@prefix trans: . - -<> - a aggr:ProvenanceLog ; - aggr:hasActivity <#execution-0>, <#execution-1> . - -<#execution-0> - a fno:Execution ; - a prov:Activity ; - fno:executes trans:QueryView ; - trans:query "SELECT * WHERE { ?s ?p ?o }" ; - trans:source "http://example.org/source1" ; - trans:result <#dataset-0> ; - prov:wasAssociatedWith ; - prov:qualifiedAssociation [ - a prov:Association ; - prov:agent ; - prov:hadPlan trans:QueryView . - ] ; - prov:used trans:QueryView ; - prov:startedAtTime "2025-01-01T12:00:00Z"^^xsd:dateTime ; - prov:endedAtTime "2025-01-01T12:02:00Z"^^xsd:dateTime . - -<#execution-1> - a fno:Execution ; - a prov:Activity ; - fno:executes transQueryView ; - trans:query "SELECT * WHERE { ?s ?p ?o }" ; - trans:source "http://example.org/source1" ; - trans:result <#dataset-1> ; - prov:wasAssociatedWith ; - prov:qualifiedAssociation [ - a prov:Association ; - prov:agent ; - prov:hadPlan . - ] ; - prov:used ; - prov:invalidated <#dataset-0> ; - prov:startedAtTime "2025-01-02T12:00:00Z"^^xsd:dateTime ; - prov:endedAtTime "2025-01-02T12:02:00Z"^^xsd:dateTime . - -<#dataset-0> - a dcat:Dataset ; - prov:wasGeneratedBy <#execution-0> ; - prov:wasInvalidatedBy <#execution-1> ; - dcat:isVersionOf . - -<#dataset-1> - a dcat:Dataset ; - prov:wasGeneratedBy <#execution-1> ; - dcat:isVersionOf ; - dcat:previousVersion <#dataset-0> . -``` -
      - -### Continuous updates ### {#continuous-updates} - -For services that continuously update their data (e.g., event-driven or streaming updates) the execution **MUST** omit -`prov:endedAtTime`. All newly generated datasets **MUST** reference the same ongoing `prov:Activity`. Creating a new -`dcat:Dataset` for every minor change may lead to excessive provenance granularity and operational overhead. -Therefore, an Aggregator Server **MUST** determine an appropriate provenance granularity level based on its use case, -performance constraints, and retention policy. The server **MAY** choose, for example, to: -- Apply time-based grouping (e.g., hourly or daily snapshots) -- Only materialize provenance when used externally (e.g., when dataset was requested) - -The chosen strategy **SHOULD** be documented and consistently applied to ensure predictable provenance semantics. - Vocabulary {#vocabulary} @@ -2307,7 +1802,7 @@ Describes an Aggregator Instance (its base URL is the Aggregator Description res **subClassOf:** [foaf:Agent](https://xmlns.com/foaf/0.1/Agent) ### aggr:Service ### {#Service} -Represents a configured Aggregator pipeline that can be created, inspected, and removed via the 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](https://www.w3.org/TR/rdf-schema/#ch_class)
      @@ -2327,16 +1822,16 @@ Describes the service collection resource (e.g., `/services`). **subClassOf:** [schema:Collection](https://schema.org/Collection), [hydra:Collection](https://www.hydra-cg.com/spec/latest/core/#collections) -### aggr:TransformationCatalog ### {#TransformationCatalog} -Describes a transformation catalog resource that lists the transformations supported by an Aggregator Server -(and optionally instance-specific transformations). +### aggr:DeploymentCatalog ### {#DeploymentCatalog} +Describes a deployment catalog resource that lists the deployment functions supported by an Aggregator Server +(and optionally instance-specific deployment functions). **type:** [rdfs:Class](https://www.w3.org/TR/rdf-schema/#ch_class)
      **subClassOf:** [schema:Collection](https://schema.org/Collection), [hydra:Collection](https://www.hydra-cg.com/spec/latest/core/#collections) ### aggr:ProvenanceLog ### {#ProvenanceLog} -Describes the provenance of generated entities and performed executions of a running Aggregator Service +Describes a collection of provenance activities associated with a running Aggregator Service. **type:** [rdfs:Class](https://www.w3.org/TR/rdf-schema/#ch_class)
      **subClassOf:** [schema:Collection](https://schema.org/Collection), @@ -2419,42 +1914,27 @@ Links an `aggr:ServiceCollection` to the `aggr:Service` instances it advertises. **domain:** [aggr:ServiceCollection](https://w3id.org/aggregator#ServiceCollection)
      **range:** [aggr:Service](https://w3id.org/aggregator#Service) -### aggr:hasTransformation ### {#hasTransformation} -Links an `aggr:TransformationCatalog` to a supported `fno:Function`. Composite transformations are also linked -with this property because they remain `fno:Function` resources. +### aggr:hasDeploymentFunction ### {#hasDeploymentFunction} +Links an `aggr:DeploymentCatalog` to a supported `fno:Function` that deploys one or more Aggregator Services. **type:** [rdf:Property](https://www.w3.org/TR/rdf-schema/#ch_property)
      -**domain:** [aggr:TransformationCatalog](https://w3id.org/aggregator#TransformationCatalog)
      +**domain:** [aggr:DeploymentCatalog](https://w3id.org/aggregator#DeploymentCatalog)
      **range:** [fno:Function](https://w3id.org/function/spec/#Function) -### aggr:hasAppliedTransformation ### {#hasAppliedTransformation} -Links an `aggr:TransformationCatalog` to a reusable `fno:AppliedFunction` template it advertises. - -**type:** [rdf:Property](https://www.w3.org/TR/rdf-schema/#ch_property)
      -**domain:** [aggr:TransformationCatalog](https://w3id.org/aggregator#TransformationCatalog)
      -**range:** [fno:AppliedFunction](https://w3id.org/function/spec/#AppliedFunction) - ### aggr:hasAlgorithm ### {#hasAlgorithm} -Links an `aggr:TransformationCatalog` to an algorithm it supports. +Links an `aggr:DeploymentCatalog` to an algorithm it supports. **type:** [rdf:Property](https://www.w3.org/TR/rdf-schema/#ch_property)
      -**domain:** [aggr:TransformationCatalog](https://w3id.org/aggregator#TransformationCatalog)
      +**domain:** [aggr:DeploymentCatalog](https://w3id.org/aggregator#DeploymentCatalog)
      **range:** [fno:Algorithm](https://w3id.org/function/spec/#Algorithm) ### aggr:hasMapping ### {#hasMapping} -Links an `aggr:TransformationCatalog` to a mapping it supports. +Links an `aggr:DeploymentCatalog` to a mapping it supports. **type:** [rdf:Property](https://www.w3.org/TR/rdf-schema/#ch_property)
      -**domain:** [aggr:TransformationCatalog](https://w3id.org/aggregator#TransformationCatalog)
      +**domain:** [aggr:DeploymentCatalog](https://w3id.org/aggregator#DeploymentCatalog)
      **range:** [fno:Mapping](https://w3id.org/function/spec/#Mapping) -### aggr:hasComposition ### {#hasComposition} -Links an `aggr:TransformationCatalog` to a composition it supports. - -**type:** [rdf:Property](https://www.w3.org/TR/rdf-schema/#ch_property)
      -**domain:** [aggr:TransformationCatalog](https://w3id.org/aggregator#TransformationCatalog)
      -**range:** [fno:Function](https://w3id.org/function/spec/#Composition) - ### aggr:status ### {#status} Provides the lifecycle phase of an `aggr:Service` (values such as `running`, `stopped`, or `error`). @@ -2469,21 +1949,15 @@ Provides a human-readable explanation of the current `aggr:Service` status (for **domain:** [aggr:Service](https://w3id.org/aggregator#Service)
      **range:** [xsd:string](https://www.w3.org/TR/xmlschema11-2/#string) -### aggr:performs ### {#performs} -Provides the transformation an `aggr:Service` performs. +### aggr:deploymentFunction ### {#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](https://www.w3.org/TR/rdf-schema/#ch_property)
      **domain:** [aggr:Service](https://w3id.org/aggregator#Service), [aggr:ServiceRequest](https://w3id.org/aggregator#ServiceRequest)
      **range:** [fno:Function](https://w3id.org/function/spec/#Function) -### aggr:applies ### {#applies} -Links an `aggr:Service` to the `fno:AppliedFunction` that captures the configured parameter bindings for that service. - -**type:** [rdf:Property](https://www.w3.org/TR/rdf-schema/#ch_property)
      -**domain:** [aggr:Service](https://w3id.org/aggregator#Service)
      -**range:** [fno:AppliedFunction](https://w3id.org/function/spec/#AppliedFunction) - ### aggr:implements ### {#implements} Provides the implementation used by an `aggr:Service` to perform its transformation. @@ -2492,13 +1966,6 @@ Provides the implementation used by an `aggr:Service` to perform its transformat [aggr:ServiceRequest](https://w3id.org/aggregator#Service)
      **range:** [fno:Implementation](https://w3id.org/function/spec/#Implementation) -### aggr:forOutput ### {#forOutput} -Links a `dcat:Dataset` exposed by an `aggr:Service` to the `fno:Output` it represents. - -**type:** [rdf:Property](https://www.w3.org/TR/rdf-schema/#ch_property)
      -**domain:** [dcat:Dataset](https://www.w3.org/TR/vocab-dcat-3/#Class:Dataset)
      -**range:** [fno:Output](https://w3id.org/function/spec/#Output) - ### aggr:fromAggregator ### {#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. @@ -2536,7 +2003,7 @@ Links an `aggr:ProvenanceLog` to an activity it includes. **type:** [rdf:Property](https://www.w3.org/TR/rdf-schema/#ch_property)
      **domain:** [aggr:ProvenanceLog](https://w3id.org/aggregator#ProvenanceLog)
      -**range:** [fno:Execution](https://w3id.org/function/spec/#Execution) +**range:** [prov:Activity](https://www.w3.org/TR/prov-o/#Activity) ### aggr:managementEndpoint ### {#managementEndpoint} Links an `aggr:AggregatorServer` to its management endpoint. @@ -2573,13 +2040,13 @@ Links an `aggr:AggregatorServer` to its Client ID Document. **domain:** [aggr:AggregatorServer](https://w3id.org/aggregator#AggregatorServer)
      **range:** [xsd:anyURI](https://www.w3.org/TR/xmlschema11-2/#anyURI) -### aggr:transformationCatalog ### {#transformationCatalog} -References the transformation catalog of an `aggr:Aggregator` (its instance-level transformation catalog) or an -`aggr:AggregatorServer` (its server-level transformation catalog). +### aggr:deploymentCatalog ### {#deploymentCatalog} +References the deployment catalog of an `aggr:Aggregator` (its instance-level deployment catalog) or an +`aggr:AggregatorServer` (its server-level deployment catalog). **type:** [rdf:Property](https://www.w3.org/TR/rdf-schema/#ch_property)
      **domain:** [aggr:Aggregator](https://w3id.org/aggregator#Aggregator), [aggr:AggregatorServer](https://w3id.org/aggregator#AggregatorServer)
      -**range:** [aggr:TransformationCatalog](https://w3id.org/aggregator#TransformationCatalog) +**range:** [aggr:DeploymentCatalog](https://w3id.org/aggregator#DeploymentCatalog) Claim Types {#vocabulary-claim-types} --------------------------- @@ -2590,7 +2057,7 @@ Identifier for the UMA `claim_type` used to request or provide a transformation **type:** [rdfs:Resource](https://www.w3.org/TR/rdf-schema/#ch_resource) Claim tokens of this type **MUST** be RDF descriptions of the intended transformation (for example an `fno:Execution` or a -reference to a transformation catalog entry). Acceptable `claim_token_format` values are URIs identifying RDF +reference to a deployment 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`). ### aggr:derivation-access ### {#derivation-access} diff --git a/provenance-detailed-draft.bs b/provenance-detailed-draft.bs new file mode 100644 index 0000000..7570f4d --- /dev/null +++ b/provenance-detailed-draft.bs @@ -0,0 +1,244 @@ +Provenance Draft +================ + +Data-model draft +---------------- + +Activity {#data-model-service-activity} +--------------------------------------- + +An Activity represents service output provenance information. Each activity: + - **MUST** be a `prov:Activity`. + - **MUST** be associated with the service using `prov:associatedWith`. + - **MUST** include a start time using `prov:startedAtTime`. + - **MAY** include an end time using `prov:endedAtTime`. + +The activity **MAY** provide additional metadata such as `prov:qualifiedAssociation`, or any other relevant provenance +information. An activity **MAY** additionally be described as an `fno:Execution` when FnO accurately describes the +service's activity, but this specification does not require that modeling choice. + +The generated dataset produced by an activity either *is* the logical dataset served by the +service, or it is a distinct version of that logical dataset, depending on whether the service +retains version history. + +In either case, the generated dataset: + - **MUST** be typed as a `dcat:Dataset`. + - **MUST** be typed as a `prov:Entity`. + - **MUST** link to the activity using `prov:wasGeneratedBy`. + - **SHOULD** include `prov:wasGeneratedAtTime`. + +If the service retains version history, the generated dataset additionally: + - **MUST** specify it is a version of the service dataset using `dcat:isVersionOf`. + +If the service retains version history, the logical dataset: + - **MUST** declare the latest known version using `dcat:hasCurrentVersion`. + - **MUST** declare other known versions using `dcat:hasVersion`. + +The following example shows an activity that produces a new version of a service dataset. + +
      +```turtle +@base . +@prefix svc: . +@prefix dcat: . +@prefix prov: . +@prefix xsd: . + + + a prov:Activity ; + prov:associatedWith ; + prov:startedAtTime "2025-01-02T12:00:00Z"^^xsd:dateTime ; + prov:endedAtTime "2025-01-02T12:02:00Z"^^xsd:dateTime . + + + a dcat:Dataset ; + a prov:Entity ; + dcat:isVersionOf svc:dataset ; + prov:wasGeneratedBy ; + prov:wasGeneratedAtTime "2025-01-02T12:02:00Z"^^xsd:dateTime . +``` +
      + +With the logical dataset referencing the generated datasets. + +
      +```turtle +@base : . +@prefix provlog: . +@prefix dcat: . +@prefix prov: . +@prefix xsd: . + +<#dataset> + a dcat:Dataset ; + dcat:distribution <#distribution-xml> , + <#distribution-json> ; + dcat:hasCurrentVersion provlog:dataset-1 ; + dcat:hasVersion provlog:dataset-0 , + provlog:dataset-1 . +``` +
      + +Provenance Log {#data-model-provenance-log} +------------------------------------------- + +A Provenance Log consolidates service output provenance information by referencing activities. + +The Provenance Log: + - **MUST** be described as an `aggr:ProvenanceLog`. + - **MUST** reference one or more activities using `aggr:hasActivity`. + +The Service: + - **MUST** link its provenance log using `aggr:provenanceLog`. + + +
      +```turtle +@base +@prefix aggr: . + +<> + a aggr:ProvenanceLog ; + aggr:hasActivity :activity-0 . +``` +
      + +Service-management draft +------------------------ + +Service Provenance {#service-provenance} +---------------------------------------- + +This section describes how an Aggregator **SHOULD** store, expose, and maintain provenance metadata of service outputs. +An Aggregator is not required to manage provenance data. However, if it does, it **MUST** conform to this specification. +A service’s `aggr:ProvenanceLog` **MUST** reference **AT LEAST** the most recent `prov:Activity` +([[#data-model-service-activity]]). + +Aggregators **MAY** publish a services' Provenance Log as an RDF Document whose base resource, identified by the document's +own retrieval URL, **MUST** be described as an `aggr:ProvenanceLog` ([[#data-model-provenance-log]]). Aggregators **MUST** +publish this document, at any deployment-specific URL of their choosing using the `GET` method. The endpoint **MUST** +be advertised in the Service Description through the `aggr:provenanceLog` predicate. The endpoint **SHOULD** support HTTP +content negotiation, allowing clients to request different RDF serializations (e.g., Turtle, JSON-LD). The activities that +are defined in the provenance log **MAY** be embedded in the Provenance Log document or **MAY** be hosted on separate endpoints +as individual RDF documents. + +If the Provenance Log keeps a history log of multiple executions, it **SHOULD** be subject to a retention policy +defining how long execution records remain included in the log. This prevents unbounded growth of the log over time +and ensures manageable storage and query performance. If the Provenance Log only retains the most recent execution, versioning +**MAY** be omitted and the execution can directly reference the dataset from the Service Description. + +
      +This example shows a Service Description for a service that updates its dataset on a daily basis. +In this example, the retained executions produce new versions of the logical service dataset, so that dataset is modeled +as a versioned dataset and references concrete dataset versions that are described in the Provenance Log. +```turtle +@base . +@prefix dcat: . +@prefix dct: . +@prefix freq: . +@prefix aggr: . +@prefix prov: . +@prefix xsd: . + +<#dataset> + a dcat:Dataset ; + dcat:distribution <#distribution> ; + dcat:hasCurrentVersion ; + dcat:hasVersion + , + ; + dct:accrualPeriodicity freq:daily ; + dct:modified "2025-01-02T12:02:00Z"^^xsd:dateTime . + +<> + a aggr:Service ; + a dcat:DataService ; + a prov:SoftwareAgent ; + dcat:servesDataset <#dataset> ; + aggr:provenanceLog ; + aggr:deploymentFunction . + +<#distribution> + a dcat:Distribution ; + dcat:accessURL ; + dcat:accessService <> . +``` +
      + +
      +The Provenance Log below illustrates two activities that each produce a new version of the logical service dataset. In this +non-normative example, the activities are additionally modeled as `fno:Execution` resources; this is optional. +```turtle +@base . +@prefix aggr: . +@prefix fno: . +@prefix prov: . +@prefix dcat: . +@prefix xsd: . +@prefix trans: . + +<> + a aggr:ProvenanceLog ; + aggr:hasActivity <#execution-0>, <#execution-1> . + +<#execution-0> + a fno:Execution ; + a prov:Activity ; + fno:executes trans:QueryView ; + trans:query "SELECT * WHERE { ?s ?p ?o }" ; + trans:source "http://example.org/source1" ; + trans:result <#dataset-0> ; + prov:wasAssociatedWith ; + prov:qualifiedAssociation [ + a prov:Association ; + prov:agent ; + prov:hadPlan trans:QueryView . + ] ; + prov:used trans:QueryView ; + prov:startedAtTime "2025-01-01T12:00:00Z"^^xsd:dateTime ; + prov:endedAtTime "2025-01-01T12:02:00Z"^^xsd:dateTime . + +<#execution-1> + a fno:Execution ; + a prov:Activity ; + fno:executes transQueryView ; + trans:query "SELECT * WHERE { ?s ?p ?o }" ; + trans:source "http://example.org/source1" ; + trans:result <#dataset-1> ; + prov:wasAssociatedWith ; + prov:qualifiedAssociation [ + a prov:Association ; + prov:agent ; + prov:hadPlan . + ] ; + prov:used ; + prov:invalidated <#dataset-0> ; + prov:startedAtTime "2025-01-02T12:00:00Z"^^xsd:dateTime ; + prov:endedAtTime "2025-01-02T12:02:00Z"^^xsd:dateTime . + +<#dataset-0> + a dcat:Dataset ; + prov:wasGeneratedBy <#execution-0> ; + prov:wasInvalidatedBy <#execution-1> ; + dcat:isVersionOf . + +<#dataset-1> + a dcat:Dataset ; + prov:wasGeneratedBy <#execution-1> ; + dcat:isVersionOf ; + dcat:previousVersion <#dataset-0> . +``` +
      + +### Continuous updates ### {#continuous-updates} + +For services that continuously update their data (e.g., event-driven or streaming updates) the execution **MUST** omit +`prov:endedAtTime`. All newly generated datasets **MUST** reference the same ongoing `prov:Activity`. Creating a new +`dcat:Dataset` for every minor change may lead to excessive provenance granularity and operational overhead. +Therefore, an Aggregator Server **MUST** determine an appropriate provenance granularity level based on its use case, +performance constraints, and retention policy. The server **MAY** choose, for example, to: +- Apply time-based grouping (e.g., hourly or daily snapshots) +- Only materialize provenance when used externally (e.g., when dataset was requested) + +The chosen strategy **SHOULD** be documented and consistently applied to ensure predictable provenance semantics. + diff --git a/sections/01-introduction.bs b/sections/01-introduction.bs index 2343312..a8d8b4e 100644 --- a/sections/01-introduction.bs +++ b/sections/01-introduction.bs @@ -1,16 +1,15 @@ Introduction {#introduction} ==================== -This specification defines the Aggregator Protocol, an HTTP-based interface that lets a client create and manage Aggregator -Instances and configure Aggregator Services that execute data transformations. Transformations are described and discovered -using the Function Ontology (FnO) [[!FNO]]; a service is configured by referencing a transformation (a `fno:Function`) and -providing its parameters (using an `fno:AppliedFunction`), after which the client can retrieve the derived result from the -output defined by that function. +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 transformation catalog ([[#aggregator-server-metadata]]). Using the management +management flows, and the server’s deployment catalog ([[#aggregator-server-metadata]]). Using the management endpoint, a client creates (or manages) an Aggregator Instance ([[#aggregator-management]]) and then follows the -instance’s Aggregator Description to find the instance’s service collection and transformations endpoint +instance’s Aggregator Description to find the instance’s service collection and deployment catalog ([[#aggregator-description]] and [[#aggregator-service-management]]). Management operations are authenticated and authorized unless a specific management flow explicitly allows unauthenticated diff --git a/sections/02-definitions.bs b/sections/02-definitions.bs index 16d2861..5f01bbb 100644 --- a/sections/02-definitions.bs +++ b/sections/02-definitions.bs @@ -16,12 +16,12 @@ Core Roles and Components {#definitions-core} - **Aggregator Instance** (or “Aggregator”): A user- or tenant-scoped logical instance created via the management endpoint. An instance exposes an Aggregator Description and an authenticated management API for configuring services. -- **Aggregator Service** (or “Service”): A configured data processing pipeline inside an Aggregator Instance. A service is - represented as an FnO Implementation (`fno:Implementation`) that implements an FnO AppliedFunction (`fno:AppliedFunction`), - which defines inputs and outputs (see [[#aggregator-service-management]]). +- **Aggregator Service** (or “Service”): A deployed `dcat:DataService` and `prov:SoftwareAgent` inside an Aggregator + Instance. It serves one or more datasets and links to the FnO deployment function used to create it (see + [[#aggregator-service-management]]). -- **Transformation Catalog:** A catalog that describes the FnO Functions supported by the Aggregator Server and the FnO AppliedFunctions hosted on an Aggregator - Instance (see [[#server-level-transformation-catalog]] and [[#instance-level-transformation-catalog]]). +- **Deployment Catalog:** A catalog of FnO deployment functions supported by an Aggregator Server or Aggregator + Instance (see [[#server-level-deployment-catalog]] and [[#instance-level-deployment-catalog]]). Identity, Authorization, and Tokens {#definitions-security} ---------------------------------------------------------- @@ -63,7 +63,6 @@ The following namespace prefixes are used throughout this specification and **SH - `aggr:` → `https://w3id.org/aggregator#` - `dct:` → `http://purl.org/dc/terms/` - `fno:` → `https://w3id.org/function/ontology#` -- `fnoc:` → `https://fno.io/vocabulary/composition/0.1.0/` - `dcat:` → `http://www.w3.org/ns/dcat#` - `rdf:` → `http://www.w3.org/1999/02/22-rdf-syntax-ns#` - `rdfs:` → `http://www.w3.org/2000/01/rdf-schema#` diff --git a/sections/03-architecture-and-resource-model.bs b/sections/03-architecture-and-resource-model.bs index 06d4941..21c9561 100644 --- a/sections/03-architecture-and-resource-model.bs +++ b/sections/03-architecture-and-resource-model.bs @@ -14,7 +14,7 @@ This specification defines HTTP resources at three levels: - **Aggregator Instance resources:** instance metadata and service management (see [[#aggregator-metadata]] and [[#aggregator-service-management]]). - **Aggregator Service resources:** a service collection and individual services managed under the instance (see - [[#service-discovery]] and service resource and provenance). + [[#service-discovery]] and the service resource). 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: @@ -49,7 +49,7 @@ Security Boundaries {#security-boundaries} All security requirements are defined in [[#aggregator-security-model]]. At a high level: - **Server-level discovery resources:** deployments **MAY** expose the server description (see [[#server-description]]) and - the server-level transformation catalog (see [[#server-level-transformation-catalog]]) without authentication, or **MAY** + the server-level deployment catalog (see [[#server-level-deployment-catalog]]) without authentication, or **MAY** protect them using an OpenID Connect (OIDC) ID Token. The Client ID Document (see [[#client-id-document]]) is typically accessible without authentication. - **Management endpoint:** deployments **MAY** protect the management endpoint (see [[#aggregator-management]]) using OIDC. @@ -74,9 +74,9 @@ Service in a path-based deployment: - Server description: `https://aggregator.example/` - Aggregator Management: `https://aggregator.example/registration` - Client ID Document: `https://aggregator.example/client.jsonld` -- Transformation catalog: `https://aggregator.example/transformations` +- Deployment catalog: `https://aggregator.example/deployments` - Instance description: `https://aggregator.example/agg1/` -- Instance Transformation catalog: `https://aggregator.example/agg1/transformations` +- Instance Deployment catalog: `https://aggregator.example/agg1/deployments` - Service collection: `https://aggregator.example/agg1/services` - Service description: `https://aggregator.example/agg1/services/service1/` - Service output: `https://aggregator.example/agg1/services/service1/output` diff --git a/sections/04-aggregator-data-model.bs b/sections/04-aggregator-data-model.bs index d63389d..ff4047f 100644 --- a/sections/04-aggregator-data-model.bs +++ b/sections/04-aggregator-data-model.bs @@ -1,9 +1,9 @@ Aggregator Data Model {#data-model} ============================================== -This section specifies the data model used to describe the aggregator components like running aggregator services -and the transformations they implement as well as the outputs they generate. By describing them as linked data the -model enables interoperable publication, discovery, execution, and provenance tracking of aggregator services. +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 @@ -14,47 +14,54 @@ specialized member names: `https://w3id.org/aggregator/contexts/aggregator-serve [[#server-description]] and `https://w3id.org/aggregator/contexts/aggregator-description.jsonld` for the [[#aggregator-description]]. -Transformation {#data-model-transformation} -------------------------------------------- - -An aggregator transformation defines a well-described functional interface using the Function Ontology [[!FNO]]. -Each transformation **MUST** be described as an `fno:Function` that **SHOULD** use `dct:description` to provide a -human-readable description of the transformation. Each transformation **MAY** use a `fno:name` to provide a short name for -the transformation, but clients **SHOULD NOT** rely on this property for unique identification. The transformation **MAY** -describe zero or more `fno:Parameters` and `fno:Outputs` using the `fno:expects` and `fno:returns` properties respectively. -Each parameter and output: - - **MUST** be a `fno:Parameter` or `fno:Output` respectively. - - **MUST** use `fno:predicate` to specify the predicate that will be used to signify its - value used by an `fno:Execution` and `aggr:ServiceRequest`. - - **MUST** define the `fno:type` of the output as a `dcat:Dataset`. - - **SHOULD** use `fno:type` to describe the parameter types. - - **MAY** use `dct:format` to describe the format of the parameter. - - **MAY** use `dct:conformsTo` to signify the parameter follows a certain specification/protocol. - - **MAY** use `dct:conformsTo` to signify the output follows a certain shape. If such a shape is defined, the dataset - generated for that output and the distributions referenced from that dataset **MUST** conform to it. - - **MAY** use `fno:required` to indicate whether the parameter is required or optional. If not specified, clients **MUST** - assume the parameter is optional. - -Additional metadata **MAY** be linked to a transformation, such as an `fno:Implementation` using an `fno:Mapping`, or the -algorithm it implements using `fno:Algorithm` as specified by [[!FNO]]. +Deployment Function {#data-model-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: + - **MUST** be described as an `fno:Function`. + - **SHOULD** use `dct:description` to provide a human-readable description. + - **MAY** use `fno:name` to provide a short name, but clients **SHOULD NOT** rely on this property for unique + identification. + - **MAY** describe zero or more `fno:Parameter` resources using `fno:expects`. + - **MUST** describe exactly one `fno:Output` using `fno:returns`. + +Each parameter: + - **MUST** be an `fno:Parameter`. + - **MUST** use `fno:predicate` to specify the predicate used to provide its value in an `aggr:ServiceRequest`. + - **SHOULD** use `fno:type` to describe the parameter type. + - **MAY** use `dct:format` to describe the parameter format. + - **MAY** use `dct:conformsTo` to indicate that the parameter follows a specification or protocol. + - **MAY** use `fno:required` to indicate whether the parameter is required or optional. If this property is absent, + clients **MUST** assume the parameter is optional. + +The output: + - **MUST** be an `fno:Output`. + - **MUST** have `aggr:Service` as its `fno:type`. + - **MUST** use `fno:predicate` to specify the output predicate. + - **MAY** use `dct:conformsTo` to further describe the kind of service produced by the deployment function. This + specification does not prescribe the referenced description or profile. + +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]].
      ```turtle -@base . -@prefix dcat: . +@base . +@prefix aggr: . @prefix fno: . -@prefix rr: . -@prefix sh: . @prefix xsd: . @prefix dct: . -@prefix rdf: . - + a fno:Function ; fno:name "The SPARQL QueryView function"^^xsd:string ; - dct:description "Performs a query on a source and materializes view as a SPARQL endpoint"^^xsd:string ; + dct:description "Deploys a service that exposes a materialized SPARQL query view"^^xsd:string ; fno:expects ( ) ; - fno:returns ( ) . + fno:returns ( ) . a fno:Parameter ; @@ -69,118 +76,41 @@ algorithm it implements using `fno:Algorithm` as specified by [[!FNO]]. dct:conformsTo ; fno:required "true"^^xsd:boolean . - - a fno:Output ; - fno:type dcat:Dataset ; - dct:conformsTo ex:SPARQLResultDatasetShape . - fno:predicate . - - - a sh:NodeShape ; - sh:targetClass dcat:Dataset ; - sh:property [ - sh:path dcat:distribution ; - sh:minCount 1 ; - sh:node - ] ; - sh:property [ - sh:path dcat:distribution ; - sh:minCount 1 ; - sh:node - ] . - - - a sh:NodeShape ; - sh:property [ - sh:path dcat:mediaType ; - sh:hasValue - ] . - - - a sh:NodeShape ; - sh:property [ - sh:path dcat:mediaType ; - sh:hasValue - ] . - - - a fno:Function ; - fno:name "The RML Mapper Function"^^xsd:string ; - dct:description "Performs RML mappings on a source and materializes results as a SPARQL endpoint"^^xsd:string ; - fno:expects ( ) ; - fno:returns ( ) . - - - a fno:Parameter ; - fno:type rr:TriplesMap ; - dct:format ; - fno:predicate ; - fno:required "true"^^xsd:boolean . - - + a fno:Output ; - fno:type dcat:Dataset ; - fno:predicate . -``` -
      - -An Applied Transformation is a Transformation in which one or more parameters are bound to concrete values and is -represented using an `fno:AppliedFunction` from [[!FNO]]. - -
      -```turtle -@base . -@prefix fno: . -@prefix fnoc: . -@prefix xsd: . - - - a fno:AppliedFunction ; - fnoc:applies ; - fnoc:parameterBindings ( - [ - fnoc:boundParameter ; - fnoc:boundToTerm "http://example.org/source" - ] - [ - fnoc:boundParameter ; - fnoc:boundToTerm "SELECT * WHERE { ?person foaf:givenName ?name }"^^xsd:string - ] - ) . + fno:type aggr:Service ; + fno:predicate ; + dct:conformsTo . ```
      -Transformation Catalog {#data-model-tf-catalog} ------------------------------------------------ +Deployment Catalog {#data-model-deployment-catalog} +--------------------------------------------------- -A Transformation Catalog references all transformations made available on an Aggregator Server including any metadata -mentioned earlier. +A Deployment Catalog references all deployment functions made available on an Aggregator Server. -The Transformation Catalog: - - **MUST** be described as an `aggr:TransformationCatalog`. - - **MUST** reference all supported (applied) transformations using `aggr:hasTransformation`. +The Deployment Catalog: + - **MUST** be described as an `aggr:DeploymentCatalog`. + - **MUST** reference all supported deployment functions using `aggr:hasDeploymentFunction`. - **MAY** reference a supported algorithm using `aggr:hasAlgorithm`. - **MAY** reference a supported mapping using `aggr:hasMapping`. - **MUST** reference all resources not hosted by the Aggregator Server using `rdfs:seeAlso`.
      ```turtle -@base . +@base . @prefix aggr: . @prefix dcat: . @prefix dct: . @prefix rdfs: . @prefix fno: . -@prefix fnoc: . @prefix rdf: . @prefix xsd: . @prefix foaf: -<> a aggr:TransformationCatalog ; - aggr:hasTransformation - , - , - , +<> a aggr:DeploymentCatalog ; + aggr:hasDeploymentFunction + , ; rdfs:seeAlso . ``` @@ -192,22 +122,19 @@ Service {#data-model-service} A deployed aggregator service is the running resource created from a service request and **MUST** be modelled as: - an `aggr:Service` - a `dcat:DataService` ([[!Data-Catalog]]) - - a `prov:SoftwareAgent` ([[!PROV-O]]) Furthermore, the service: - - **MUST** serve exactly one dataset for each output of the transformation identified by `aggr:performs`. - - **MUST** link using `aggr:performs` to the underlying `fno:Function`. - - **MUST** link using `dcat:servesDataset` to the corresponding dataset described as a `dcat:Dataset`. + - **MUST** link using `aggr:deploymentFunction` to the `fno:Function` used to deploy it. + - **MUST** link using `dcat:servesDataset` to one or more datasets described as `dcat:Dataset` resources. - **SHOULD** declare operational metadata such as status and creation time. - **SHOULD** indicate it adheres to the aggregator protocol using `dct:conformsTo`. - - **MAY** link using `aggr:applies` to an applied transformation that applies the performed function - with a set of input values when the usecase allows these to be disclosed. - - **MAY** specify the exact implementation using a link to an `fno:Implementation` with `aggr:implements`. -The corresponding dataset: +Each corresponding dataset: - **MUST** be described as a `dcat:Dataset`. - - **MUST** link to exactly one `fno:Output` of that transformation using `aggr:forOutput`. - - **MUST** reference a `dcat:distribution`. + - **MAY** reference one or more `dcat:Distribution` resources using `dcat:distribution`. + +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: - **MUST** reference the corresponding output endpoint using `dcat:accessURL`. @@ -225,8 +152,7 @@ or describe the service API using the Hydra Core Ontology ([[!Hydra]]).
      ```turtle @base . -@prefix inst-trans: . -@prefix server-trans: . +@prefix server-deploy: . @prefix aggr: . @prefix dcat: . @prefix prov: . @@ -239,14 +165,12 @@ or describe the service API using the Hydra Core Ontology ([[!Hydra]]). a prov:SoftwareAgent ; aggr:status "running" ; aggr:createdAt "2024-01-01T12:00:00Z"^^xsd:dateTime ; - aggr:performs server-trans:QueryView ; - aggr:applies inst-trans:QueryViewApplied ; + aggr:deploymentFunction server-deploy:QueryViewDeployment ; dct:conformsTo ; dcat:servesDataset <#dataset> . <#dataset> a dcat:Dataset ; - aggr:forOutput server-trans:ViewOutput ; dcat:distribution <#distribution-xml> , <#distribution-json> . @@ -285,118 +209,9 @@ The Service Collection: ```
      -Execution {#data-model-service-execution} ------------------------------------------ - -An Execution represents the service output provenance information. Each execution: - - **MUST** be a `fno:Execution`. - - **MUST** link to the executed transformation using `fno:executes`. - - **MUST** link to the generated datasets using the output predicates defined in [[#data-model-transformation]]. - - **MUST** link to the used parameter values using the parameter predicates defined in [[#data-model-transformation]]. - - **MAY** link to the used mapping using `fno:uses` to indicate the used implementation - - **MUST** be a `prov:Activity`. - - **MUST** be associated with the service using `prov:associatedWith`. - - **MUST** include a start time using `prov:startedAtTime`. - - **MAY** include an end time using `prov:endedAtTime`. - -The execution **MAY** provide additional metadata such as `prov:qualifiedAssociation`, or any other -relevant provenance information. The executed transformation **MUST** be the same as the transformation declared in the -service description using `aggr:performs`. - -The generated dataset produced by an execution either *is* the logical dataset served by the -service, or it is a distinct version of that logical dataset, depending on whether the service -retains version history. - -In either case, the generated dataset: - - **MUST** be typed as a `dcat:Dataset`. - - **MUST** be typed as a `prov:Entity`. - - **MUST** link to the execution using `prov:wasGeneratedBy`. - - **SHOULD** include `prov:wasGeneratedAtTime`. - -If the service retains version history, the generated dataset additionally: - - **MUST** specify it is a version of the service dataset using `dcat:isVersionOf`. - -If the service retains version history, the logical dataset: - - **MUST** declare the latest known version using `dcat:hasCurrentVersion`. - - **MUST** declare other known versions using `dcat:hasVersion`. - -The following example shows an execution that produces a new version of a service dataset. - -
      -```turtle -@base . -@prefix svc: . -@prefix server-trans: . -@prefix aggr: . -@prefix fno: . -@prefix dcat: . -@prefix prov: . -@prefix xsd: . - - - a fno:Execution ; - a prov:Activity ; - fno:executes server-trans:sparql-query-view ; - server-trans:query "SELECT * WHERE { ?s ?p ?o }" ; - server-trans:source "http://example.org/source1" ; - server-trans:view ; - prov:associatedWith ; - prov:startedAtTime "2025-01-02T12:00:00Z"^^xsd:dateTime ; - prov:endedAtTime "2025-01-02T12:02:00Z"^^xsd:dateTime . - - - a dcat:Dataset ; - a prov:Entity ; - dcat:isVersionOf svc:dataset ; - prov:wasGeneratedBy ; - prov:wasGeneratedAtTime "2025-01-02T12:02:00Z"^^xsd:dateTime . -``` -
      - -With the logical dataset referencing the generated datasets. - -
      -```turtle -@base : . -@prefix provlog: . -@prefix server-trans: . -@prefix aggr: . -@prefix fno: . -@prefix dcat: . -@prefix prov: . -@prefix xsd: . - -<#dataset> - a dcat:Dataset ; - aggr:forOutput server-trans:view-output ; - dcat:distribution <#distribution-xml> , - <#distribution-json> ; - dcat:hasCurrentVersion provlog:dataset-1 ; - dcat:hasVersion provlog:dataset-0 , - provlog:dataset-1 . -``` -
      - Provenance Log {#data-model-provenance-log} ------------------------------------------- -A Provenance Log consolidates all service output provenance information by referencing executions. - -The Provenance Log: - - **MUST** be described as an `aggr:ProvenanceLog`. - - **MUST** reference one or more execution activities using `aggr:hasActivity`. - -The Service: - - **MUST** link its provenance log using `aggr:provenanceLog`. - - -
      -```turtle -@base -@prefix aggr: . - -<> - a aggr:ProvenanceLog ; - aggr:hasActivity :execution-0 . -``` -
      +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`. diff --git a/sections/05-aggregator-server-metadata.bs b/sections/05-aggregator-server-metadata.bs index e8a5d4d..333bd23 100644 --- a/sections/05-aggregator-server-metadata.bs +++ b/sections/05-aggregator-server-metadata.bs @@ -45,10 +45,10 @@ in Turtle). Clients **MAY** rely on this type statement when consuming semantic :: The value is a string containing the absolute URL of the Client ID Document ([[#client-id-document]]); in the RDF representations, this member maps to the predicate `aggr:clientIdentifier` ([[#clientIdentifier]]). -: **transformation_catalog** (REQUIRED): -:: The value is a string containing the absolute URL of the server-level Transformation Catalog - ([[#server-level-transformation-catalog]]); in the RDF representations, this member maps to the predicate - `aggr:transformationCatalog` ([[#transformationCatalog]]). +: **deployment_catalog** (REQUIRED): +:: The value is a string containing the absolute URL of the server-level Deployment Catalog + ([[#server-level-deployment-catalog]]); in the RDF representations, this member maps to the predicate + `aggr:deploymentCatalog` ([[#deploymentCatalog]]).
      ```json @@ -67,7 +67,7 @@ in Turtle). Clients **MAY** rely on this type statement when consuming semantic ], "version": "1.0.0", "client_identifier": "https://aggregator.example/client.jsonld", - "transformation_catalog": "https://aggregator.example/transformations" + "deployment_catalog": "https://aggregator.example/deployments" } ```
      @@ -83,87 +83,15 @@ aggregator, the `redirect_uris` property is **OPTIONAL** instead of **REQUIRED** 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. -Server-level Transformation Catalog {#server-level-transformation-catalog} --------------------------------------------------------------------------- +Server-level Deployment Catalog {#server-level-deployment-catalog} +------------------------------------------------------------------ -The Transformation Catalog is an RDF document whose base resource, identified by the document's -own retrieval URL, **MUST** be described as an `aggr:TransformationCatalog` ([[#data-model-tf-catalog]]). -Resources referenced by the Transformation Catalog **MAY** either be included directly in the RDF document or +The Deployment Catalog is an RDF document whose base resource, identified by the document's +own retrieval URL, **MUST** be described as an `aggr:DeploymentCatalog` ([[#data-model-deployment-catalog]]). +Resources referenced by the Deployment 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 [[#server-description]] via the `transformation_catalog` field. +The URL **MUST** be advertised in the [[#server-description]] via the `deployment_catalog` field. The catalog **SHOULD** support HTTP content negotiation, allowing clients to request different RDF serializations (e.g., Turtle, JSON-LD). - -A transformation **MAY** be linked to an `fnoc:Composition` using `fnoc:composition`. This **MAY** be done -solely to describe the internal structure of a transformation. In this case, the composition serves as descriptive metadata -to provide additional transparency. Composite transformations remain `fno:Function` resources and therefore **MUST** be -advertised using `aggr:hasTransformation`. If all transformations referenced within the `fnoc:Composition` are also -included in the catalog, each of them represents a deployable service. This enables an Aggregator to expose a pipeline as a -single service while internally orchestrating multiple individual services. - -
      -The following example describes a pipeline that: - 1. Uses RML to map a non-RDF source. - 2. Executes a query over the generated RDF. - 3. Exposes the resulting query output. - -```turtle -@base . -@prefix aggr: . -@prefix dct: . -@prefix fno: . -@prefix fnoc: . - -<> a aggr:TransformationCatalog ; - dct:title "Aggregator transformations" ; - aggr:hasTransformation ; - aggr:hasTransformation ; - aggr:hasTransformation ; - - - a fno:Function ; - fno:expects ( ) ; - fno:returns ( ) ; - fno:composition [ - fnoc:composedOf [ - fnoc:mapFrom [ - fnoc:constituentFunction ; - fnoc:functionParameter . - ] ; - fnoc:mapTo [ - fnoc:constituentFunction ; - fnoc:functionParameter . - ] . - ],[ - fnoc:mapFrom [ - fnoc:constituentFunction ; - fnoc:functionParameter . - ] ; - fnoc:mapTo [ - fnoc:constituentFunction ; - fnoc:functionParameter . - ] . - ],[ - fnoc:mapFrom [ - fnoc:constituentFunction ; - fnoc:functionParameter . - ] ; - fnoc:mapTo [ - fnoc:constituentFunction ; - fnoc:functionParameter ; - ] . - ],[ - fnoc:mapFrom [ - fnoc:constituentFunction ; - fnoc:functionOutput . - ] ; - fnoc:mapTo [ - fnoc:constituentFunction ; - fnoc:functionParameter . - ] . - ] . - ] . -``` -
      diff --git a/sections/08-aggregator-metadata.bs b/sections/08-aggregator-metadata.bs index 25eb4af..6ddeb67 100644 --- a/sections/08-aggregator-metadata.bs +++ b/sections/08-aggregator-metadata.bs @@ -3,7 +3,7 @@ Aggregator Metadata {#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 -`transformation_catalog` and `service_collection_endpoint` fields) so clients can discover the deployment-specific layout. +`deployment_catalog` and `service_collection_endpoint` fields) so clients can discover the deployment-specific layout. Aggregator Description {#aggregator-description} ---------------------------------------------------------- @@ -36,10 +36,10 @@ that the described resource has RDF type `aggr:Aggregator` ([[#Aggregator]]) (e. :: 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` ([[#tokenExpiry]]). -: **transformation_catalog** (**REQUIRED**): -:: The value is a string containing the absolute URL of the instance’s Transformations Endpoint - ([[#instance-level-transformation-catalog]]); in the RDF representations, this member maps to the predicate - `aggr:transformationCatalog` ([[#transformationCatalog]]). +: **deployment_catalog** (**REQUIRED**): +:: The value is a string containing the absolute URL of the instance’s Deployment Catalog + ([[#instance-level-deployment-catalog]]); in the RDF representations, this member maps to the predicate + `aggr:deploymentCatalog` ([[#deploymentCatalog]]). : **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 ([[#service-collection-endpoint]]); in the RDF representations, this member maps to the predicate @@ -57,25 +57,23 @@ that case this document **MUST** be an RDF document that conforms to the WebID P "created_at": "2025-12-17T17:20:00Z", "login_status": true, "token_expiry": "2025-12-17T18:20:00Z", - "transformation_catalog": "https://aggregator.example/aggregators/agg-7890/transformations", + "deployment_catalog": "https://aggregator.example/aggregators/agg-7890/deployments", "service_collection_endpoint": "https://aggregator.example/aggregators/agg-7890/services", "oidcIssuer": "https://issuer.example/" } ```
      -Instance-level Transformation Catalog {#instance-level-transformation-catalog} ------------------------------------------------------------------------------- +Instance-level Deployment Catalog {#instance-level-deployment-catalog} +--------------------------------------------------------------------- -This endpoint is the instance-level extension of the server-level Transformation Catalog defined in -[[#server-level-transformation-catalog]]. It allows the Aggregator Server to make certain transformations available -only to specific Aggregator instances, by curating the catalog's contents per instance. This Instance-Level -Transformation Catalog also includes all Applied Transformations used by the Aggregator's deployed Services, -as well as all client-defined pipelines (further explained in [[#service-deployment]]). +This endpoint is the instance-level extension of the server-level Deployment Catalog defined in +[[#server-level-deployment-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 [[#aggregator-description]] via the `instance_transformation_catalog` field. The endpoint -**MUST** follow the same content negotiation rules, and other requirements, as the server-level Transformation -Catalog. Resources referenced by this Instance-Level Transformation Catalog **MAY** either be included directly in -the RDF document or hosted by the Aggregator Server in separate documents. This Instance-Level Transformation +be advertised in the [[#aggregator-description]] via the `deployment_catalog` field. The endpoint +**MUST** follow the same content negotiation rules, and other requirements, as the server-level Deployment +Catalog. Resources referenced by this Instance-Level Deployment Catalog **MAY** either be included directly in +the RDF document or hosted by the Aggregator Server in separate documents. This Instance-Level Deployment Catalog, along with each resource referenced by it, **MUST** be protected using the [[#aggregator-security-model]]. diff --git a/sections/09-aggregator-service-management.bs b/sections/09-aggregator-service-management.bs index 9d8b861..4c07488 100644 --- a/sections/09-aggregator-service-management.bs +++ b/sections/09-aggregator-service-management.bs @@ -37,7 +37,7 @@ least the predefined JSON-LD context `https://w3id.org/aggregator/contexts/aggre The `aggr:ServiceRequest`: - **MUST** be the only `aggr:ServiceRequest` described in the request body. - **MUST** be identified using either a unique URI or a blank node. -- **MUST** declare a Transformation using `performs`. +- **MUST** identify a deployment function using `deploymentFunction`. - **MUST** provide inputs for at least all required parameters, using the parameter predicates defined using `fno:predicate` in the function description. - **MAY** specify an implementation to use with `implements`. @@ -49,12 +49,10 @@ the server **MUST** respond with `409 Conflict`. Upon successful processing, the Aggregator **MUST**: -1. Include an Applied Transformation representing the performed Transformation with the given inputs to the - Instance-Level Transformation Catalog. This resource **MUST** be referenced using `aggr:applies` and protected - using the [[#aggregator-security-model]]. -2. Deploy a new Service that performs the transformation indicated by `performs` (and, if present, the implementation - indicated by `implements`), and expose a Service Description Endpoint [[#service-endpoint]] describing it according - to the data model in [[#data-model-service]]. +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 [[#service-endpoint]], describing it according + to the data model in [[#data-model-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. @@ -66,11 +64,11 @@ Error Responses: - **MUST** respond with `400 Bad Request` if the requested URI is syntactically invalid or not permitted. - **MUST** respond with `409 Conflict` if the requested URI is valid but already in use. - **MUST** respond with `400 Bad Request` if the request body is syntactically malformed or semantically invalid - (e.g., missing required parameter bindings or referencing an unknown transformation). + (e.g., missing required parameter values or referencing an unknown deployment function). - **MUST** respond with `500 Internal Server Error` if the request is valid but the Aggregator fails to deploy the Service. -The following example depicts a request that deploys a service performing the `QueryView` Transformation. +The following example depicts a request that invokes the `QueryViewDeployment` deployment function.
      ```http @@ -82,126 +80,20 @@ Content-Type: application/ld+json "@context": [ "https://w3id.org/aggregator/contexts/aggregator.jsonld", { - "query": "https://aggregator.example/transformations#query", - "source": "https://aggregator.example/transformations#source" + "query": "https://aggregator.example/deployments#query", + "source": "https://aggregator.example/deployments#source" } ], "@id": "https://aggregator.example/agg1/services/query-view-service/", "@type": "ServiceRequest", - "performs": "https://aggregator.example/transformations#QueryView", - "implements": "https://aggregator.example/transformations#QueryViewIncremunica", + "deploymentFunction": "https://aggregator.example/deployments#QueryViewDeployment", + "implements": "https://aggregator.example/deployments#QueryViewIncremunica", "query": "SELECT * WHERE { ?s ?p ?o }", "source": "http://example.org/source" } ```
      -### Deploying Pipelines ### {#pipeline-deployment} - -Deploying a service that performs a composite transformation **MUST** use the same request format as any other -transformation service. Only a single Service Description Endpoint, for the top-level (composite) transformation, -**MUST** be exposed; its Service Output Endpoints serve the datasets produced by the composite transformation's -declared outputs, which are in turn populated from the mapped outputs of the internally deployed constituent -services. A composite transformation **MAY** either be predefined in a Transformation Catalog, or defined by the -client as a pipeline inline in the request. - -When a client defines a pipeline inline in the request: - - Constituent functions **MUST** be reused from a Transformation Catalog - - Any of the parameters or outputs, **MAY** be reused from a Transformation Catalog, - using their existing identifiers and predicates. - - All newly introduced identifiers, namely the composite function itself and any parameters, outputs, or predicates - that cannot be reused from a Transformation Catalog, **MUST** be scoped to the Instance-Level Transformation - Catalog. - - The Aggregator **MUST** add the composite transformation, together with any newly introduced parameters and - outputs, to the Instance-Level Transformation Catalog, so that it can subsequently be referenced using - `aggr:performs` in the resulting Service description. - - If a client-proposed identifier is already in use in the Instance-Level Transformation Catalog, the Aggregator - **MUST** respond with `409 Conflict`. - -
      -```http -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", - { - "server-catalog": "https://aggregator.example/transformations#", - "inst-catalog": "https://aggregator.example/agg1/transformations#", - "query": "server-catalog:query", - "mapping": "server-catalog:mapping" - } - ], - "@graph": [ - { - "@id": "https://aggregator.example/agg1/services/pipeline-service/", - "@type": "ServiceRequest", - "performs": "inst-catalog:RMLQueryPipeline", - "mapping": "...", - "query": "SELECT * WHERE { ?s ?p ?o }" - }, - { - "@id": "inst-catalog:RMLQueryPipeline", - "@type": "Function", - "expects": [ - { "@id": "server-catalog:RMLMapping" }, - { "@id": "server-catalog:QueryString" } - ], - "returns": [ - { "@id": "server-catalog:ViewOutput" } - ], - "composition": { - "composedOf": [ - { - "mapFrom": { - "constituentFunction": "inst-catalog:RMLQueryPipeline", - "functionParameter": "server-catalog:RMLMapping" - }, - "mapTo": { - "constituentFunction": "server-catalog:RMLMapper", - "functionParameter": "server-catalog:RMLMapping" - } - }, - { - "mapFrom": { - "constituentFunction": "inst-catalog:RMLQueryPipeline", - "functionParameter": "server-catalog:QueryString" - }, - "mapTo": { - "constituentFunction": "server-catalog:QueryView", - "functionParameter": "server-catalog:QueryString" - } - }, - { - "mapFrom": { - "constituentFunction": "server-catalog:RMLMapper", - "functionOutput": "server-catalog:KGOutput" - }, - "mapTo": { - "constituentFunction": "server-catalog:QueryView", - "functionParameter": "server-catalog:QuerySource", - } - }, - { - "mapFrom": { - "constituentFunction": "server-catalog:QueryView", - "functionOutput": "server-catalog:ViewOutput" - }, - "mapTo": { - "constituentFunction": "inst-catalog:RMLQueryPipeline", - "functionParameter": "server-catalog:ViewOutput" - } - } - ] - } - } - ] -} -``` -
      - ### Service Discovery ### {#service-discovery} The Service Collection Endpoint **MUST** expose an RDF document whose base resource, identified by the document's @@ -241,7 +133,7 @@ service. This endpoint **SHOULD** support HTTP content negotiation as defined in 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 the the `GET` and `DELETE` methods, the server **MAY** support: +Next to the `GET` and `DELETE` methods, the server **MAY** support: : `PATCH` :: Updates the service description (as defined in [[#data-model-service]]). @@ -263,7 +155,7 @@ Next the the `GET` and `DELETE` methods, the server **MAY** support: 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`, `dcat:distribution`, and `aggr:provenanceLog`. If a `PATCH` or +`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`. @@ -273,139 +165,3 @@ Each Service Output Endpoint **MUST** be hosted at the same URL as the one refer 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. - -Service Provenance {#service-provenance} ----------------------------------------- - -This section describes how an Aggregator **SHOULD** store, expose, and maintain provenance metadata of service outputs. -An Aggregator is not required to manage provenance data. However, if it does, it **MUST** conform to this specification. -A service’s `aggr:ProvenanceLog` **MUST** reference **AT LEAST** the most recent `fno:Execution` -([[#data-model-service-execution]]). - -Aggregators **MAY** publish a services' Provenance Log as an RDF Document whose base resource, identified by the document's -own retrieval URL, **MUST** be described as an `aggr:ProvenanceLog` ([[#data-model-provenance-log]]). Aggregators **MUST** -publish this document, at any deployment-specific URL of their choosing using the `GET` method. The endpoint **MUST** -be advertised in the Service Description through the `aggr:provenanceLog` predicate. The endpoint **SHOULD** support HTTP -content negotiation, allowing clients to request different RDF serializations (e.g., Turtle, JSON-LD). The executions that -are defined in the provenance log **MAY** be embedded in the Provenance Log document or **MAY** be hosted on separate endpoints -as individual RDF documents. - -If the Provenance Log keeps a history log of multiple executions, it **SHOULD** be subject to a retention policy -defining how long execution records remain included in the log. This prevents unbounded growth of the log over time -and ensures manageable storage and query performance. If the Provenance Log only retains the most recent execution, versioning -**MAY** be omitted and the execution can directly reference the dataset from the Service Description. - -
      -This example shows a Service Description for a service that updates its dataset on a daily basis. -In this example, the retained executions produce new versions of the logical service dataset, so that dataset is modeled -as a versioned dataset and references concrete dataset versions that are described in the Provenance Log. -```turtle -@base . -@prefix dcat: . -@prefix dct: . -@prefix freq: . -@prefix aggr: . -@prefix prov: . -@prefix xsd: . - -<#dataset> - a dcat:Dataset ; - aggr:forOutput <#result> ; - dcat:distribution <#distribution> ; - dcat:hasCurrentVersion ; - dcat:hasVersion - , - ; - dct:accrualPeriodicity freq:daily ; - dct:modified "2025-01-02T12:02:00Z"^^xsd:dateTime . - -<> - a aggr:Service ; - a dcat:DataService ; - a prov:SoftwareAgent ; - dcat:servesDataset <#dataset> ; - aggr:provenanceLog ; - aggr:performs . - -<#distribution> - a dcat:Distribution ; - dcat:accessURL ; - dcat:accessService <> . -``` -
      - -
      -The Provenance Log below illustrates two executions of a service that each produce a new version of the logical service dataset. -```turtle -@base . -@prefix aggr: . -@prefix fno: . -@prefix prov: . -@prefix dcat: . -@prefix xsd: . -@prefix trans: . - -<> - a aggr:ProvenanceLog ; - aggr:hasActivity <#execution-0>, <#execution-1> . - -<#execution-0> - a fno:Execution ; - a prov:Activity ; - fno:executes trans:QueryView ; - trans:query "SELECT * WHERE { ?s ?p ?o }" ; - trans:source "http://example.org/source1" ; - trans:result <#dataset-0> ; - prov:wasAssociatedWith ; - prov:qualifiedAssociation [ - a prov:Association ; - prov:agent ; - prov:hadPlan trans:QueryView . - ] ; - prov:used trans:QueryView ; - prov:startedAtTime "2025-01-01T12:00:00Z"^^xsd:dateTime ; - prov:endedAtTime "2025-01-01T12:02:00Z"^^xsd:dateTime . - -<#execution-1> - a fno:Execution ; - a prov:Activity ; - fno:executes transQueryView ; - trans:query "SELECT * WHERE { ?s ?p ?o }" ; - trans:source "http://example.org/source1" ; - trans:result <#dataset-1> ; - prov:wasAssociatedWith ; - prov:qualifiedAssociation [ - a prov:Association ; - prov:agent ; - prov:hadPlan . - ] ; - prov:used ; - prov:invalidated <#dataset-0> ; - prov:startedAtTime "2025-01-02T12:00:00Z"^^xsd:dateTime ; - prov:endedAtTime "2025-01-02T12:02:00Z"^^xsd:dateTime . - -<#dataset-0> - a dcat:Dataset ; - prov:wasGeneratedBy <#execution-0> ; - prov:wasInvalidatedBy <#execution-1> ; - dcat:isVersionOf . - -<#dataset-1> - a dcat:Dataset ; - prov:wasGeneratedBy <#execution-1> ; - dcat:isVersionOf ; - dcat:previousVersion <#dataset-0> . -``` -
      - -### Continuous updates ### {#continuous-updates} - -For services that continuously update their data (e.g., event-driven or streaming updates) the execution **MUST** omit -`prov:endedAtTime`. All newly generated datasets **MUST** reference the same ongoing `prov:Activity`. Creating a new -`dcat:Dataset` for every minor change may lead to excessive provenance granularity and operational overhead. -Therefore, an Aggregator Server **MUST** determine an appropriate provenance granularity level based on its use case, -performance constraints, and retention policy. The server **MAY** choose, for example, to: -- Apply time-based grouping (e.g., hourly or daily snapshots) -- Only materialize provenance when used externally (e.g., when dataset was requested) - -The chosen strategy **SHOULD** be documented and consistently applied to ensure predictable provenance semantics. diff --git a/sections/11-vocabulary.bs b/sections/11-vocabulary.bs index 5c3db63..d98aa26 100644 --- a/sections/11-vocabulary.bs +++ b/sections/11-vocabulary.bs @@ -16,7 +16,7 @@ Describes an Aggregator Instance (its base URL is the Aggregator Description res **subClassOf:** [foaf:Agent](https://xmlns.com/foaf/0.1/Agent) ### aggr:Service ### {#Service} -Represents a configured Aggregator pipeline that can be created, inspected, and removed via the 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](https://www.w3.org/TR/rdf-schema/#ch_class)
      @@ -36,16 +36,16 @@ Describes the service collection resource (e.g., `/services`). **subClassOf:** [schema:Collection](https://schema.org/Collection), [hydra:Collection](https://www.hydra-cg.com/spec/latest/core/#collections) -### aggr:TransformationCatalog ### {#TransformationCatalog} -Describes a transformation catalog resource that lists the transformations supported by an Aggregator Server -(and optionally instance-specific transformations). +### aggr:DeploymentCatalog ### {#DeploymentCatalog} +Describes a deployment catalog resource that lists the deployment functions supported by an Aggregator Server +(and optionally instance-specific deployment functions). **type:** [rdfs:Class](https://www.w3.org/TR/rdf-schema/#ch_class)
      **subClassOf:** [schema:Collection](https://schema.org/Collection), [hydra:Collection](https://www.hydra-cg.com/spec/latest/core/#collections) ### aggr:ProvenanceLog ### {#ProvenanceLog} -Describes the provenance of generated entities and performed executions of a running Aggregator Service +Describes a collection of provenance activities associated with a running Aggregator Service. **type:** [rdfs:Class](https://www.w3.org/TR/rdf-schema/#ch_class)
      **subClassOf:** [schema:Collection](https://schema.org/Collection), @@ -128,42 +128,27 @@ Links an `aggr:ServiceCollection` to the `aggr:Service` instances it advertises. **domain:** [aggr:ServiceCollection](https://w3id.org/aggregator#ServiceCollection)
      **range:** [aggr:Service](https://w3id.org/aggregator#Service) -### aggr:hasTransformation ### {#hasTransformation} -Links an `aggr:TransformationCatalog` to a supported `fno:Function`. Composite transformations are also linked -with this property because they remain `fno:Function` resources. +### aggr:hasDeploymentFunction ### {#hasDeploymentFunction} +Links an `aggr:DeploymentCatalog` to a supported `fno:Function` that deploys one or more Aggregator Services. **type:** [rdf:Property](https://www.w3.org/TR/rdf-schema/#ch_property)
      -**domain:** [aggr:TransformationCatalog](https://w3id.org/aggregator#TransformationCatalog)
      +**domain:** [aggr:DeploymentCatalog](https://w3id.org/aggregator#DeploymentCatalog)
      **range:** [fno:Function](https://w3id.org/function/spec/#Function) -### aggr:hasAppliedTransformation ### {#hasAppliedTransformation} -Links an `aggr:TransformationCatalog` to a reusable `fno:AppliedFunction` template it advertises. - -**type:** [rdf:Property](https://www.w3.org/TR/rdf-schema/#ch_property)
      -**domain:** [aggr:TransformationCatalog](https://w3id.org/aggregator#TransformationCatalog)
      -**range:** [fno:AppliedFunction](https://w3id.org/function/spec/#AppliedFunction) - ### aggr:hasAlgorithm ### {#hasAlgorithm} -Links an `aggr:TransformationCatalog` to an algorithm it supports. +Links an `aggr:DeploymentCatalog` to an algorithm it supports. **type:** [rdf:Property](https://www.w3.org/TR/rdf-schema/#ch_property)
      -**domain:** [aggr:TransformationCatalog](https://w3id.org/aggregator#TransformationCatalog)
      +**domain:** [aggr:DeploymentCatalog](https://w3id.org/aggregator#DeploymentCatalog)
      **range:** [fno:Algorithm](https://w3id.org/function/spec/#Algorithm) ### aggr:hasMapping ### {#hasMapping} -Links an `aggr:TransformationCatalog` to a mapping it supports. +Links an `aggr:DeploymentCatalog` to a mapping it supports. **type:** [rdf:Property](https://www.w3.org/TR/rdf-schema/#ch_property)
      -**domain:** [aggr:TransformationCatalog](https://w3id.org/aggregator#TransformationCatalog)
      +**domain:** [aggr:DeploymentCatalog](https://w3id.org/aggregator#DeploymentCatalog)
      **range:** [fno:Mapping](https://w3id.org/function/spec/#Mapping) -### aggr:hasComposition ### {#hasComposition} -Links an `aggr:TransformationCatalog` to a composition it supports. - -**type:** [rdf:Property](https://www.w3.org/TR/rdf-schema/#ch_property)
      -**domain:** [aggr:TransformationCatalog](https://w3id.org/aggregator#TransformationCatalog)
      -**range:** [fno:Function](https://w3id.org/function/spec/#Composition) - ### aggr:status ### {#status} Provides the lifecycle phase of an `aggr:Service` (values such as `running`, `stopped`, or `error`). @@ -178,21 +163,15 @@ Provides a human-readable explanation of the current `aggr:Service` status (for **domain:** [aggr:Service](https://w3id.org/aggregator#Service)
      **range:** [xsd:string](https://www.w3.org/TR/xmlschema11-2/#string) -### aggr:performs ### {#performs} -Provides the transformation an `aggr:Service` performs. +### aggr:deploymentFunction ### {#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](https://www.w3.org/TR/rdf-schema/#ch_property)
      **domain:** [aggr:Service](https://w3id.org/aggregator#Service), [aggr:ServiceRequest](https://w3id.org/aggregator#ServiceRequest)
      **range:** [fno:Function](https://w3id.org/function/spec/#Function) -### aggr:applies ### {#applies} -Links an `aggr:Service` to the `fno:AppliedFunction` that captures the configured parameter bindings for that service. - -**type:** [rdf:Property](https://www.w3.org/TR/rdf-schema/#ch_property)
      -**domain:** [aggr:Service](https://w3id.org/aggregator#Service)
      -**range:** [fno:AppliedFunction](https://w3id.org/function/spec/#AppliedFunction) - ### aggr:implements ### {#implements} Provides the implementation used by an `aggr:Service` to perform its transformation. @@ -201,13 +180,6 @@ Provides the implementation used by an `aggr:Service` to perform its transformat [aggr:ServiceRequest](https://w3id.org/aggregator#Service)
      **range:** [fno:Implementation](https://w3id.org/function/spec/#Implementation) -### aggr:forOutput ### {#forOutput} -Links a `dcat:Dataset` exposed by an `aggr:Service` to the `fno:Output` it represents. - -**type:** [rdf:Property](https://www.w3.org/TR/rdf-schema/#ch_property)
      -**domain:** [dcat:Dataset](https://www.w3.org/TR/vocab-dcat-3/#Class:Dataset)
      -**range:** [fno:Output](https://w3id.org/function/spec/#Output) - ### aggr:fromAggregator ### {#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. @@ -245,7 +217,7 @@ Links an `aggr:ProvenanceLog` to an activity it includes. **type:** [rdf:Property](https://www.w3.org/TR/rdf-schema/#ch_property)
      **domain:** [aggr:ProvenanceLog](https://w3id.org/aggregator#ProvenanceLog)
      -**range:** [fno:Execution](https://w3id.org/function/spec/#Execution) +**range:** [prov:Activity](https://www.w3.org/TR/prov-o/#Activity) ### aggr:managementEndpoint ### {#managementEndpoint} Links an `aggr:AggregatorServer` to its management endpoint. @@ -282,13 +254,13 @@ Links an `aggr:AggregatorServer` to its Client ID Document. **domain:** [aggr:AggregatorServer](https://w3id.org/aggregator#AggregatorServer)
      **range:** [xsd:anyURI](https://www.w3.org/TR/xmlschema11-2/#anyURI) -### aggr:transformationCatalog ### {#transformationCatalog} -References the transformation catalog of an `aggr:Aggregator` (its instance-level transformation catalog) or an -`aggr:AggregatorServer` (its server-level transformation catalog). +### aggr:deploymentCatalog ### {#deploymentCatalog} +References the deployment catalog of an `aggr:Aggregator` (its instance-level deployment catalog) or an +`aggr:AggregatorServer` (its server-level deployment catalog). **type:** [rdf:Property](https://www.w3.org/TR/rdf-schema/#ch_property)
      **domain:** [aggr:Aggregator](https://w3id.org/aggregator#Aggregator), [aggr:AggregatorServer](https://w3id.org/aggregator#AggregatorServer)
      -**range:** [aggr:TransformationCatalog](https://w3id.org/aggregator#TransformationCatalog) +**range:** [aggr:DeploymentCatalog](https://w3id.org/aggregator#DeploymentCatalog) Claim Types {#vocabulary-claim-types} --------------------------- @@ -299,7 +271,7 @@ Identifier for the UMA `claim_type` used to request or provide a transformation **type:** [rdfs:Resource](https://www.w3.org/TR/rdf-schema/#ch_resource) Claim tokens of this type **MUST** be RDF descriptions of the intended transformation (for example an `fno:Execution` or a -reference to a transformation catalog entry). Acceptable `claim_token_format` values are URIs identifying RDF +reference to a deployment 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`). ### aggr:derivation-access ### {#derivation-access} From a2e7749bf51fa22d812d7905a5a3bc784755ec9f Mon Sep 17 00:00:00 2001 From: ponachte Date: Mon, 3 Aug 2026 17:35:23 +0200 Subject: [PATCH 2/2] add service profile NOTE --- dist/index.html | 4 ++++ dist/spec.bs | 5 +++++ sections/04-aggregator-data-model.bs | 5 +++++ 3 files changed, 14 insertions(+) diff --git a/dist/index.html b/dist/index.html index 6001c51..cbd0dab 100644 --- a/dist/index.html +++ b/dist/index.html @@ -2484,6 +2484,10 @@

      MAY use dct:conformsTo to further describe the kind of service produced by the deployment function. This specification does not prescribe the referenced description or profile.

      +
      +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].

      diff --git a/dist/spec.bs b/dist/spec.bs index 3e05409..026c107 100644 --- a/dist/spec.bs +++ b/dist/spec.bs @@ -314,6 +314,11 @@ The output: - **MAY** use `dct:conformsTo` to further describe the kind of service produced by the deployment function. This specification does not prescribe the referenced description or profile. +
      +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]]. diff --git a/sections/04-aggregator-data-model.bs b/sections/04-aggregator-data-model.bs index ff4047f..e0e1a29 100644 --- a/sections/04-aggregator-data-model.bs +++ b/sections/04-aggregator-data-model.bs @@ -45,6 +45,11 @@ The output: - **MAY** use `dct:conformsTo` to further describe the kind of service produced by the deployment function. This specification does not prescribe the referenced description or profile. +
      +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]].