A vision on algebraic flows for declarative resource descriptions

Introduction

Decentralized data ecosystems [1, 2, 3] are reshaping how data is stored, accessed, and governed. Rather than centralizing data around data consumers, these ecosystems center around data producers, empowering individuals and organizations to maintain agency and control while facilitating collaboration. This shift brings clear benefits: 1. it facilitates collaboration across organizational boundaries despite differing data models and objectives, 2. it reduces data duplication through fine-grained access policies, and 3. it enables diverse applications to reuse shared data sources. These properties are particularly beneficial in the re-emerging age of agentic AI wherein autonomous systems act on behalf of individuals, since the agents could better understand the individual after consuming their personal data store.

However, agentic systems – whether powered by stochastic language models or deterministic query engines – require a precise understanding of both the semantics and the consequences of the actions they perform. When these systems interact with decentralized data sources, they need to know: 1. What does it mean to write data here? 2. What state changes will this action trigger? 3. How do the endpoints of interface reflect those changes after completion? In practice, today’s interfaces rarely answer these questions fully. Descriptions are often partial, human-readable, and inconsistently maintained. As a result, autonomous agents operate with brittle assumptions and incomplete models of the systems they interact with.

One key insight from previous research is that simple interfaces (e.g. LDP [4]) – where the manipulation of one resource does not have effects on the manipulation of another, and where CRUD operations happen on the same resource, meaning updates are not performed on some intermediate resource (e.g. a database) have difficulty supporting complex access policies required in these ecosystems [5]. Asymmetric interfaces, in which interfaces depend on intermediate resources, the manipulation of one resource can have consequences on the manipulation of another, and data manipulation methods can be used to enact consistency boundaries, are a more promising fit. Unfortunately, the inclusion of intermediate resources introduces a new challenge, as write semantics become opaque, agents no longer know what resources are manipulated and how when performing a single write. This semantic gap prevents agents from reliably reasoning over their own actions. At the same time, the same resources can be exposed in different ways, such as through different fragmentations or interaction methods, each having their own benefits and drawbacks [6, 7]. Moreover, in dynamic environments these choices of fragmentation and interaction methods can change [8], mirroring the elasticity of cloud infrastructure.

To manage these complexities, we propose a framework that algebraically describes (e.g. relational or SPARQL algebra) the relationship between write operations, resource manipulations, and the exposed resource representations using shape descriptions (e.g. ShEx [9]).

Throughout this paper we will use Fig. 1 as an example use case to motivate our approach. Our use case is an interface around a pet doctors database registering pet-owners and their pets. We include four endpoint families: 1. <post-owner>: registers a new owner and their pets in the system. 2. <change-owner>: transfers a pet from one registered owner to another. 3. <get-owners>: retrieves a list of URIs representing all registered owners. 4. <get-owner>: fetches an individual owner along with their associated pets + pet data. Important to note is that our system explicitly models the <database> information resource, meaning other systems can now reference the resource ‘all owners and their pets registered in the system’, and deduce what endpoints manipulate and expose it.

This paper presents a vision for a future in which interfaces formally describe their underlying resources and how to manipulate them, creating rich, composable, and formal interface semantics. Our goal is to stimulate discussion on how such descriptions can support autonomous operation, improve agent reliability, and pave the way for more interoperable and adaptive knowledge infrastructures. While the proposed direction remains conceptual, we offer initial ideas and mappings that illustrate how this approach could be realized in practice. In the next section we review related work, discussing various existing ways to describe data interfaces. In Section 3 we detail our vision, and we conclude our paper in Section 4.

Related work

Existing web interface description frameworks fall into several distinct families, each optimized for different usage scenarios. However, most fall short in their ability to formally and completely describe how data flows from write operations to corresponding reads or how internal state transitions occur within the system, across endpoints.

RPC and Syntactic Interface Specifications - Remote Procedure Call (RPC) style specification languages such as WADL [10] and OpenAPI/Swagger [11] primarily offer syntactic descriptions of web APIs. These specifications define endpoints, parameters, and payload schemas in formats like XML (WADL) or JSON/YAML (OpenAPI). Although they support URI templates [12] and detail input-output structures, they do not capture semantic relationships between operations, nor do they support hypermedia or model the consequences of state modifications. OpenAPI is widely used for generating documentation and client code, but it only supports syntactic interoperability, requiring human developers or intelligent agents to infer the meaning of operations.

Similarly, AsyncAPI [13] extends the RPC-style description model to event-based APIs, offering a syntax for defining message-driven architectures. It describes publish/subscribe channels, message schemas, and communication protocols (e.g., MQTT, WebSocket), which makes it well-suited for heterogeneous environments. However, like OpenAPI, AsyncAPI lacks the ability to model how emitted messages impact application state. Messages are specified structurally, but not semantically; the relationship between an event and the resulting system state is left implicit.

Our solution will convey how the underlying system resources are modified by describing the interaction between write operations, dereferenceable information resources and non-accessible resources (e.g. an underlying database).

Tool Invocation and Agent-Oriented APIs - The Model Context Protocol (MCP) [14] represents a newer class of interface which is self-descriptive and aimed at AI agent interoperability. Since MCP allows external tools to advertise available resources (readable data) and tools (invokable operations) to large language models (LLMs), enabling structured interaction via natural language, MCP could be used as a data interface. While this model does conceptually align reads and writes with corresponding resources and tools, it lacks formal semantics. Descriptions in MCP are purely textual, and while this enables flexible reasoning by LLMs, it does not guarantee unambiguous interpretations of system behavior or consequences of actions. As a result, agents cannot reliably infer the downstream effects of invoking a particular tool. The solution we present tackles the reliability problem by algebraically describing the relationship.

Semantic Web Descriptions - In the context of the Semantic Web, interface description languages aim to embed operational semantics into Linked Data. The Hydra Core Vocabulary [15] allows API providers to annotate resources with affordances - like descriptions of possible state transitions. This enables clients to discover valid actions dynamically through hypermedia controls. While Hydra provides an elegant model for describing RESTful interactions, it fundamentally assumes symmetry between inputs and outputs. It does not support asymmetric interfaces, for example for changing the owner of a pet in Fig. 1. Therefore, while Hydra enables simple autonomous interactions (e.g., resource creation or deletion), it cannot express the full semantics of data flows [16].

OWL-S [17] provides a semantically rich framework for describing Web services, including preconditions, effects, and complex process models. It supports abstract reasoning about resource modifications, making it theoretically capable of modeling service composition.

RESTdesc [18] extends ideas similar to Hydra ideas using Notation3 (N3) [19], enabling interface contracts through logical implications. Although more expressive than Hydra, RESTdesc similarly lacks a formal model of the data lifecycle; it does not provide mechanisms for tracing how data flows through write-to-read transitions across interfaces.

To our knowledge all semantic web descriptions thus lack direct mechanisms for describing concrete modifications to intermediate resources (e.g., <database> in Fig. 1). As such, they are not well-suited to applications requiring fine-grained reasoning about how specific API calls alter intermediate resources.

Query-Based Interfaces - Interfaces like SPARQL Protocol [20] and GraphQL [21] expose an underlying dataset as an HTTP-based query endpoint allowing clients to select the specific data they require at run-time. GraphQL will allow you to describe different available resources and manipulations, but similar to syntactic interface descriptions, the description of the resources is done through natural language leaving room for interpretation error. The SPARQL protocol on the other hand, is, in the absence of further policies, inherently symmetrical, meaning the shape of the data one can read matches that which can be written. This limits their use when determinism is needed, or when multiple or intermediate resources are required, additionally their interaction method comes at significant costs for the data provider [22]. Our solution enables (and encourages) the semantic definition of multiple resources and additionally allows you to use multiple interaction methods.

Algebraic resource descriptions

In this section we will explain our vision by walking through the pet doctor example (Fig. 1). Within our example definitions we use SPARQL algebra [23] over RDF [24] - due to RDF’s strengths in representing linked, web-native data using IRIs - the broader approach is algebra-agnostic. Any algebra that can express data transformations in a way that preserves semantic meaning and exposes IRIs as first-class citizens could be used (e.g. RML algebra [25] seems particularly useful).

We also emphasize that the description is there to help clients and should only be correct in regard to the behaviour of the described system, it is thus decoupled from the underlying implementation. For example, an RDF-based description may describe a JSON API backed by a relational database. Despite this abstraction, the algebraic description is sufficient to generate a server implementation, illustrating the expressive power of the model.

Pet registration - We start by focussing on Bob, the proud owner of two cats. To protect his cats, he requests his agent to register them to the local pet doctor. Since Bob just moved to a new city, the interface of the local pet doctor’s database is not yet known to Bob’s agent. To make Bob agent discover the capabilities of the local pet doctor’s database, the agent first request a description of the interface of the local doctor. Within this description the agent finds how the <post-owners> endpoint manipulates the doctors’ database. The agent discovers the interaction method (e.g. a POST to /owners), the resource representation (e.g. Turtle [26]), and the expected data shape (e.g. a ShEx [9] description see Fig. 2). The interaction method and resource representation allow for out of band communication, since the agent either supports them or does not - meaning the agent knows their own capabilities. The shape description allows the agent to infer what information it should provide to the endpoint to facilitate a successful interaction. The description also provides the agent with knowledge on the consequences of a successful interaction by providing an algebraic relationship between the endpoint and, among others, the database resource (e.g. using SPARQL Update, see Fig. 3). By utilizing this interface description, the agent can 1. infer that it should POST Bob’s data and that of the cats, according to the shape to /owners in Turtle format. 2. infer that the consequences are what is expected and that Bob’s cat won’t suddenly appear up for sale.

Requesting pet information - Next in our use case, disaster strikes and one of the cats get sick, to make matters worse our doctor is on holiday. Bob visits another doctor, and now that doctor requires the medical history of Bob’s cat stored on the system of our doctor. The other doctor thus tasks their agent to retrieve the files of Bob’s sick cat. Since this agent needs to read data, it would technically be feasible to query all data of our doctors system blindly, and filter on what applies to Bobs cat. This approach is currently often taken but comes with significant client and server overhead - our agent is smart and requests the interface description of our doctor their system. From this description it notices the existence of our database, containing owners and pets. Since the database resource is not directly exposed, it looks at other, derived resources, finding 1. <get-owners>: list of IRIs of the owner in the system, and 2. <get-owner>: parameterized resources containing the info of owner X and their pets. Each of those resources algebraically describes how they are derived from the database using for example SPARQL CONSTRUCT queries (Fig. 4 and Fig. 5). When describing parameterized resources, one could use a tentative variable in the query that will be bound at a later point. Since the resources are exposed, the description contains just like before the interaction method and representation. Using the interaction methods you can link the resource parameters to parts of the interaction method, as such using the URI template [12] /owners/{id} we can bind the ‘id’ variable to a variable in the query. Next, we hypothesize that the agent can use the algebraic descriptions and the input shapes from the manipulation endpoints to compute the shape of the data they can expect when calling the read-endpoints. Using the expected shapes and parameter definitions, the agent will infer that it can request both Bob’s data and that of his cats when Bob provides his identifier.

Pet transfer - Now to end our story in a positive note, Bob decides to buy a third cat. He buys the cat from Alice who is already registered at the same doctor, and asks his agent to register this change of ownership. Once again, the agent requests the description, this time discovering the <change-owners> endpoint. Like before, the endpoint has a required shape description (Fig. 6), a resource representation, an interaction method, and a query that updates the database (Fig. 7). Similar to the parameterized resource before, the update query of <change-owner> contains variables that will be bound at a later stage, the variable in question being ‘id’ and ‘pet-id’ from the URI template /owner/{id}/{pet-id}/change-owner. It is essential to note that the explicit modeling of the <database> plays an essential role in our ability to describe this operation. The change ownership modification shows the definition of a consistency boundary that would not be possible to model with symmetric interface.

Need for algebraic descriptions - To conclude we hypothesize that our algebraic descriptions enable agents to: 1. Discover endpoints providing views over given resources, and how to query them, and 2. infer how modifications can be enacted to those resources, by tracing flows back to the corresponding write endpoints, 3. how these endpoints can be used (interaction methods, required shapes), and In this way, our model enables agents to reason not just about what data resources exist, but how they came to be, how they can be modified, and what such modifications would entail.

prefix xsd: <http://www.w3.org/2001/XMLSchema#>
prefix ex: <http://example.org/>
<owner-shape> {
  a  [ex:owner];
  ex:name xsd:string;
  ex:pet @<pet-shape>*;
}
<pet-shape> {
  a [ex:pet] ;
  ex:name xsd:string ;
  ex:age xsd:positiveInteger ;
}

PREFIX ex: <https://example.org/>
INSERT {
    ?ownerBound a ex:owner ;
        ex:name ?name ; ex:pet ?petBound .
    ?petBound a ex:pet ;
        ex:name ?petName ; ex:age ?age .
} WHERE {
    BIND( UUID() AS ?ownerUuid ). BIND( UUID(?pet) AS ?petUuid ).
    BIND( URI(CONCAT(ex:owners, '/', ?ownerUuid)) AS ?ownerBound ) .
    BIND( URI(CONCAT(?ownerBound, '/', ?petUuid)) AS ?petBound ) .
    ?resource ex:name ?name ;
        ex:pet ?pet .
    ?pet ex:name ?petName ;
        ex:age ?age ;
}

CONSTRUCT { [] ex:item ?owner . }
WHERE {
    <database> {
        ?owner a ex:owner .
    }
}

CONSTRUCT {
    ?id a ex:owner ;
        ?p ?o ;
    ?o ?p1 ?o1 ;
} WHERE {
    <database> {
        ?id a ex:owner ;
            ?p ?o ;
        OPTIONAL { ?o ?p1 ?o1 . }
    }
}

prefix ex: <http://example.org/>
<change-owner-shape> {
  ex:new-owner IRI
}

PREFIX ex: <https://example.org/>
DELETE {
    ?origOwner ex:pet ?orig-pet .
    ?origPet a ex:pet ;
        ex:age ?age ;
        ex:name ?name .
} INSERT {
    ?newOwner ex:pet ?movedIri .
    ?movedIri a ex:pet ;
        ex:age ?age
        ex:name ?name
} WHERE {
    BIND( URI( CONCAT(ex:owners, '/', ?id) ) AS ?origOwner ) .
    BIND( URI( CONCAT(?origOwner, '/', ?petId) ) AS ?origPet ) .
    ?o ex:new-owner ?newOwner .
    BIND( URI( CONCAT(?newOwner, '/', ?petId) ) AS ?movedIri ) .
    # Go look in the current state of the database for whether the owner and pet exist.
    GRAPH <database> {
        ?origOwner ex:pet ?origPet .
        ?origPet a ex:pet ;
            ex:age ?age ;
            ex:name ?name .
        ?newOwner a ex:owner ;
    }
}

Conclusion

We propose a new approach to data interface descriptions by formally linking reads and writes through algebraic flows and explicitly modeling intermediate resources. As autonomous agents become more prevalent, machine-understandable interface semantics are essential, especially for heterogeneous and asymmetric systems—something current approaches fail to provide.

By introducing algebraic data flows, we propose a foundation for explicitly modeling read and write operations over both exposed and intermediate resources. This shift enables agents to reason not only about what data is available, but also how it was derived and how it can be meaningfully modified. This approach builds on skills developers already use to write queries, requiring only a shift in mindset: modeling intermediate resources explicitly and exposing interface semantics.

Future work includes formalizing the system with a defined vocabulary and algorithms, exploring policy-aware semantics for fine-grained control, and developing privacy-preserving flows where interface descriptions can be selectively disclosed. The authors next step will be to tackle the first point and create a proof-of-concept implementation.