diff --git a/.github/scripts/__pycache__/assemble_from_summary.cpython-314.pyc b/.github/scripts/__pycache__/assemble_from_summary.cpython-314.pyc deleted file mode 100644 index 81eeb13..0000000 Binary files a/.github/scripts/__pycache__/assemble_from_summary.cpython-314.pyc and /dev/null differ diff --git a/.github/scripts/constrain_images.lua b/.github/scripts/constrain_images.lua new file mode 100644 index 0000000..9961c86 --- /dev/null +++ b/.github/scripts/constrain_images.lua @@ -0,0 +1,138 @@ +-- Pandoc Lua filter for the PDF export pipeline only. +-- +-- Some local source images are wider than the PDF page's text width (e.g. a +-- 836px screenshot against a ~6.3in printable width at 2.5cm margins on +-- A4), and pandoc's default LaTeX scaling (\pandocbounded) does not +-- reliably shrink them, so they bleed past the page margin with content +-- cut off. This filter reads each local image's real pixel size and DPI +-- and only caps the width (to 90% of the text width, aspect ratio kept) +-- when the image's native size actually exceeds the page. Images that +-- already fit (icons, small badges) are left untouched -- an earlier, +-- blunter version of this filter that forced width=90% on every image +-- blew up a small CC-license badge to near full-page width. +-- +-- Remote images (http/https, e.g. the CC badge pulled from +-- creativecommons.org) are left untouched entirely: we have no local file +-- to measure, and every remote image in this repo is a small icon/badge, +-- not a diagram. +-- +-- This only runs for the PDF export (release.yml); it is not applied to +-- the Markdown source files, so GitHub and the knowledge base keep +-- rendering images at native size. + +local MAX_WIDTH_IN = 6.0 -- a bit under the ~6.3in text width (A4, 2.5cm margins), as a safety margin + +local function read_file(path) + local f = io.open(path, "rb") + if not f then return nil end + local data = f:read("a") + f:close() + return data +end + +local function find_local_file(src) + if read_file(src) then return src end + local roots = (PANDOC_STATE and PANDOC_STATE.resource_path) or {} + for _, root in ipairs(roots) do + local candidate = pandoc.path.join({ tostring(root), src }) + if read_file(candidate) then return candidate end + end + return nil +end + +-- JPEG: walk markers to the first SOFn segment for width/height, and read +-- the JFIF APP0 segment (if present) for DPI. +local function jpeg_dimensions(data) + local len = #data + local dpi_x, dpi_y = 96, 96 + local pos = 3 -- skip SOI (FF D8) + while pos + 3 < len do + if data:byte(pos) ~= 0xFF then return nil end + local marker = data:byte(pos + 1) + if marker == 0xD8 or marker == 0x01 or (marker >= 0xD0 and marker <= 0xD7) then + pos = pos + 2 + else + local seglen = data:byte(pos + 2) * 256 + data:byte(pos + 3) + if marker == 0xE0 and seglen >= 14 and data:sub(pos + 4, pos + 8) == "JFIF\0" then + local units = data:byte(pos + 11) + local xd = data:byte(pos + 12) * 256 + data:byte(pos + 13) + local yd = data:byte(pos + 14) * 256 + data:byte(pos + 15) + if units == 1 and xd > 0 and yd > 0 then + dpi_x, dpi_y = xd, yd + elseif units == 2 and xd > 0 and yd > 0 then + dpi_x, dpi_y = xd * 2.54, yd * 2.54 + end + end + local is_sof = marker >= 0xC0 and marker <= 0xCF + and marker ~= 0xC4 and marker ~= 0xC8 and marker ~= 0xCC + if is_sof then + local h = data:byte(pos + 5) * 256 + data:byte(pos + 6) + local w = data:byte(pos + 7) * 256 + data:byte(pos + 8) + return w, h, dpi_x, dpi_y + end + if marker == 0xD9 or seglen < 2 then return nil end + pos = pos + 2 + seglen + end + end + return nil +end + +-- PNG: fixed-offset IHDR for width/height, optional pHYs chunk for DPI. +local function png_dimensions(data) + if data:sub(1, 8) ~= "\137PNG\r\n\26\n" then return nil end + local width = data:byte(17) * 16777216 + data:byte(18) * 65536 + data:byte(19) * 256 + data:byte(20) + local height = data:byte(21) * 16777216 + data:byte(22) * 65536 + data:byte(23) * 256 + data:byte(24) + local dpi_x, dpi_y = 96, 96 + local pos, len = 9, #data + while pos + 8 <= len do + local clen = data:byte(pos) * 16777216 + data:byte(pos + 1) * 65536 + data:byte(pos + 2) * 256 + data:byte(pos + 3) + local ctype = data:sub(pos + 4, pos + 7) + if ctype == "pHYs" and pos + 16 <= len then + local ppu_x = data:byte(pos + 8) * 16777216 + data:byte(pos + 9) * 65536 + data:byte(pos + 10) * 256 + data:byte(pos + 11) + local ppu_y = data:byte(pos + 12) * 16777216 + data:byte(pos + 13) * 65536 + data:byte(pos + 14) * 256 + data:byte(pos + 15) + local unit = data:byte(pos + 16) + if unit == 1 and ppu_x > 0 and ppu_y > 0 then + dpi_x, dpi_y = ppu_x * 0.0254, ppu_y * 0.0254 + end + break + end + if ctype == "IDAT" or clen < 0 then break end + pos = pos + 12 + clen + end + return width, height, dpi_x, dpi_y +end + +local function natural_width_inches(path) + local data = read_file(path) + if not data then return nil end + local w, _, dpi_x = nil, nil, nil + if path:lower():match("%.png$") then + w, _, dpi_x = png_dimensions(data) + elseif path:lower():match("%.jpe?g$") then + w, _, dpi_x = jpeg_dimensions(data) + end + if w and dpi_x and dpi_x > 0 then + return w / dpi_x + end + return nil +end + +function Image(img) + if img.attributes.width then + return img -- author already set an explicit width; respect it + end + if img.src:match("^https?://") then + return img -- remote images: nothing to measure, known to be small badges + end + + local path = find_local_file(img.src) + if not path then + return img -- can't find/read it; leave sizing to the LaTeX default + end + + local width_in = natural_width_inches(path) + if width_in and width_in > MAX_WIDTH_IN then + img.attributes.width = "90%" + end + return img +end diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index b31888e..991345b 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -37,6 +37,7 @@ jobs: args: >- docs/_combined.md --from=markdown + --lua-filter=.github/scripts/constrain_images.lua --standalone --toc --number-sections @@ -56,6 +57,7 @@ jobs: args: >- docs/FrontMatter.md --from=markdown-implicit_figures + --lua-filter=.github/scripts/constrain_images.lua --standalone --pdf-engine=xelatex -V papersize=a4 diff --git a/.gitignore b/.gitignore index 4a157f3..5a11df9 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,5 @@ docs/_combined.md /body.pdf /frontmatter.pdf /IDS-RAM-latest.pdf +__pycache__/ +*.pyc diff --git a/CHANGELOG.md b/CHANGELOG.md index 7eefc0b..c06e9e6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added ### -- Basic structure for the documentation +- none ### Changed ### @@ -30,3 +30,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Security ### - none + +## [2026-3] - 2026-10-08 ## + +### Added ### + +- Architectural Patterns for the Data Space Governance Authority (DSGA): central/federated and decentral realizations and their trade-offs. +- Architectural Patterns for Catalogs: central/federated and decentral discovery, including push/pull collection and reachability/authorization considerations. +- Architecture Principles chapter mapping IDS-RAM capabilities (Credentials & Claims, Cataloging, Contract Negotiation, Data Transfer, Observability) to the Dataspace Protocol (DSP) and Decentralized Claims Protocol (DCP), including a mapping table to technical specifications. +- Focus Paper: Value-Adding Services in Decentralized Data Spaces (matchmaking and billing as non-mandatory participant services). + +### Changed ### + +- Dropped the "working draft" framing and the stale "2026-1" version references; this edition is labeled IDS-RAM 2026-3. +- Updated `docs/SUMMARY.md` to include the new Principles, Pattern, and Focus Paper sub-pages so they appear in the published knowledge base navigation. +- Standardized terminology on "data space(s)" as two words throughout, and on "Data Space Governance Authority" for DSGA. + +### Removed ### + +- none + +### Deprecated ### + +- none + +### Fixed ### + +- Fixed a broken internal link from Credentials & Claims to the DSGA pattern page. +- Corrected typos and grammar across the Introduction, Context, Outlook, Pattern, and Principles chapters. +- Cleaned up markdown formatting (admonition indentation, stray whitespace, duplicate blank lines). + +### Security ### + +- none diff --git a/docs/Context/README.md b/docs/Context/README.md index 3382a29..6cb90de 100644 --- a/docs/Context/README.md +++ b/docs/Context/README.md @@ -1,9 +1,10 @@ # Relation to other IDSA Documents -The International Data Spaces Association (IDSA) provides a comprehensive body of documentation that serves as both a strategic compass and a practical guide for building interoperable, trusted dataspaces. IDSA documents follow a clear top-down structure: starting with vision and principles, moving to governance and requirements, narrowing into thematic clarity, and concluding with technical realization. This structure ensures coherence across conceptual, operational, and technical domains, enabling organizations to confidently adopt dataspace principles at scale. + +The International Data Spaces Association (IDSA) provides a comprehensive body of documentation that serves as both a strategic compass and a practical guide for building interoperable, trusted data spaces. IDSA documents follow a clear top-down structure: starting with vision and principles, moving to governance and requirements, narrowing into thematic clarity, and concluding with technical realization. This structure ensures coherence across conceptual, operational, and technical domains, enabling organizations to confidently adopt data space principles at scale. | Level | Document | Purpose | |-------|-------|-------| -|Vision | [Manifesto of Data Spaces](https://kb.internationaldataspaces.org/external/manifesto/manifesto) | Defines core principles and motivation | +|Vision | [Manifesto of Data Spaces](https://kb.internationaldataspaces.org/external/manifesto/manifesto) | Defines core principles and motivation | |Governance | [IDSA Rulebook](https://kb.internationaldataspaces.org/external/rulebook/001_Introduction) | Establish requirements and roles | |Thematic guidance | [IDSA Papers on Focus topics](https://kb.internationaldataspaces.org/external/ram/FocusPapers) | Explore evolving topics in depth | |Technical Architecture | [IDS-RAM](https://kb.internationaldataspaces.org/external/ram/) | Enables implementations | @@ -12,19 +13,18 @@ The International Data Spaces Association (IDSA) provides a comprehensive body o At the top of the IDSA document hierarchy stands the IDSA Manifesto, a concise yet powerful declaration of purpose. It describes IDSA’s ambition to shape a trusted global data economy founded on sovereignty, trust, and interoperability. The Manifesto serves three essential functions: -- Sets the shared aspiration: to enable data sharing ecosystems where organizations retain control over their data and use it responsibly for collective innovation. -- Establishes guiding values: trust, fairness, interoperability, and sovereignty, which frame all other IDSA documents. +- Sets the shared aspiration: to enable data sharing ecosystems where organizations retain control over their data and use it responsibly for collective innovation. +- Establishes guiding values: trust, fairness, interoperability, and sovereignty, which frame all other IDSA documents. - Calls for collective action: encouraging industry, research, and policymakers to collaborate toward Trusted Data Sharing based on open standards and decentralized architectures. -Unlike detailed guidance documents, the Manifesto is deliberately high level. It articulates “why” dataspaces matter and builds a shared identity and strategic direction for the IDSA community. All subsequent documents—including the Rulebook, Focus Topics, and the Reference Architecture Model (IDS-RAM)—are grounded in the principles laid out here. - +Unlike detailed guidance documents, the Manifesto is deliberately high level. It articulates “why” data spaces matter and builds a shared identity and strategic direction for the IDSA community. All subsequent documents—including the Rulebook, Focus Topics, and the Reference Architecture Model (IDS-RAM)—are grounded in the principles laid out here. ## IDSA Rulebook – From Principles into Practice Guided by the ideals of the Manifesto, the IDSA Rulebook answers **"WHAT"** needs to be done to translate vision into concrete requirements and governance models. It supports the creation, operation, and growth of data spaces by distinguishing mandatory requirements from optional, value-adding practices. Its scope spans technical, commercial, and legal dimensions: - Common technical guidance, including functional requirements and specifications. -- Recommendations for applying IDSA technical artefacts and for alignment with partner feworks. +- Recommendations for applying IDSA technical artefacts and for alignment with partner frameworks. - Operational guidance for collaboration, roles, and processes that enable data space ecosystems. - Perspectives on implementing and complying with international legal and regulatory obligations to facilitate trusted, cross-border data sharing. @@ -32,22 +32,22 @@ The Rulebook acts as the normative foundation of IDSA. It does not specify imple ## IDSA Papers on Focus Topics – Depth on Key Challenges -While the Manifesto inspires and the Rulebook governs, documents for individual focus topics dive deeper into specific adoption within dataspaces. These concise thematic modules ensure that the documentation can evolve with a fast-changing environment without overloading core documents. Current topics include: +While the Manifesto inspires and the Rulebook governs, documents for individual focus topics dive deeper into specific adoption within data spaces. These concise thematic modules ensure that the documentation can evolve with a fast-changing environment without overloading core documents. Current topics include: -- Identity & Trust – decentralized identity management and verifiable credentials. -- Interoperability – semantic, organizational, and technical interoperability models. -- Observability – monitoring dataspace operations while respecting sovereignty. -- Agentic AI and LLM – integration of MCP and dataspace in the context of agentic web +- Identity & Trust – decentralized identity management and verifiable credentials. +- Interoperability – semantic, organizational, and technical interoperability models. +- Observability – monitoring data space operations while respecting sovereignty. +- Agentic AI and LLM – integration of MCP and data space in the context of agentic web Each Focus Topic is anchored in the Rulebook and consistent with the Manifesto, providing reusable patterns and best practices. Their modular structure ensures efficient maintenance and allows new topics to be integrated as technology and regulation evolve. ## IDS Reference Architecture Model – Technical Realization -While previous documents define what to implement, the IDS Reference Architecture Model (IDS-RAM) explain **"HOW"** to build it. It is the central technical compendium that transforms more abstract governance concepts into implementable architecture. The IDS-RAM introduces: +While previous documents define what to implement, the IDS Reference Architecture Model (IDS-RAM) explains **"HOW"** to build it. It is the central technical compendium that transforms more abstract governance concepts into implementable architecture. The IDS-RAM introduces: -- Interaction models between logical components -- Protocol specifications like the Dataspace Protocol (DSP) and Decentralized Claims Protocol (DCP). -- Capabilities for identity, data discovery, policy enforcement, contract negotiation, and secure transfer. +- Interaction models between logical components +- Protocol specifications like the Dataspace Protocol (DSP) and Decentralized Claims Protocol (DCP). +- Capabilities for identity, data discovery, policy enforcement, contract negotiation, and secure transfer. - Integration patterns that support interoperability without imposing a single technology stack. The IDS-RAM is not prescriptive software architecture; it is a design framework that accommodates diverse implementation paths. It supports system architects and developers by connecting high-level requirements from the Rulebook with concrete deployment scenarios. Its two core sections—Capability Mapping and Architectural Best Practices—make it an indispensable engineering guide for building sovereign, trusted data ecosystems. diff --git a/docs/FocusPapers/README.md b/docs/FocusPapers/README.md index 518304d..95ad793 100644 --- a/docs/FocusPapers/README.md +++ b/docs/FocusPapers/README.md @@ -1,6 +1,6 @@ -## IDSA Papers on Focus Topics – In depth guidance on key challenges +# IDSA Papers on Focus Topics – In depth guidance on key challenges -The IDSA papers created by the IDSA working groups Architecture and Rulebook, providing guidance on individual focus topics dive deeper into specific adoption within dataspaces. +The IDSA papers created by the IDSA working groups Architecture and Rulebook, providing guidance on individual focus topics dive deeper into specific adoption within data spaces. These concise thematic modules ensure that the documentation can evolve with a fast-changing environment without overloading core documents such as the IDSA Rulebook and the IDS Reference Architecture Model. @@ -9,11 +9,11 @@ Current topics include: - **Observability** – monitoring data sharing transactions while respecting sovereignty: IDSA Position Paper [Observability in Data Spaces](https://internationaldataspaces.org/download/51606/?tmstv=1777284023) - **Identity & Trust** – decentralized identity management and verifiable credentials: Draft working paper [Identifiers in Data Spaces](https://github.com/International-Data-Spaces-Association/identity-in-data-spaces) - **Interoperability** – semantic, organizational, and technical interoperability models: IDSA Position Paper [Semantic Interoperability in Data Spaces](https://internationaldataspaces.org/download/52879/?tmstv=1777540498) -- **Agentic AI and LLM** – integration of MCP and dataspace in the context of agentic web: IDSA Rulebook page [AI Agents](https://kb.internationaldataspaces.org/external/rulebook/130_AI_Agents/) +- **Agentic AI and LLM** – integration of MCP and data space in the context of agentic web: IDSA Rulebook page [AI Agents](https://kb.internationaldataspaces.org/external/rulebook/130_AI_Agents/) - **IDSA Position Paper Data Spaces and AI Trustworthy Agentic Participation in Data Spaces** - This [position paper](https://internationaldataspaces.org/download/56028/?tmstv=1784794145) establishes a shared vocabulary for readers coming from either side of this convergence, sets out today’s AI challenges and how the building blocks of a data space address them, details the concrete value AI brings to operating a data space and grounds the discussion in pilots already underway. - **Value-Adding Services** – an architectural pattern for offering matchmaking and billing as competing, non-mandatory participant services in a decentralized data space, preserving sovereignty and avoiding centralized control points: Draft Focus Paper [Value-Adding Services in Decentralized Data Spaces](Value-Adding_Services_in_Decentralized_Dataspaces.md) -Each Focus Topic is anchored in the IDSA Rulebook and IDS Reference Archiecture Model and consistent with the Data Spaces Manifesto, providing reusable patterns and best practices. +Each Focus Topic is anchored in the IDSA Rulebook and IDS Reference Architecture Model and consistent with the Data Spaces Manifesto, providing reusable patterns and best practices. Their modular structure ensures efficient maintenance and allows new topics to be integrated as technology and regulation evolve. diff --git a/docs/FocusPapers/Value-Adding_Services_in_Decentralized_Dataspaces.md b/docs/FocusPapers/Value-Adding_Services_in_Decentralized_Dataspaces.md index 58cdda4..1e4e51c 100644 --- a/docs/FocusPapers/Value-Adding_Services_in_Decentralized_Dataspaces.md +++ b/docs/FocusPapers/Value-Adding_Services_in_Decentralized_Dataspaces.md @@ -2,7 +2,7 @@ While decentralized data spaces fundamentally rely on autonomous participants interacting through standardized protocols such as the Dataspace Protocol (DSP) and the Decentralized Claims Protocol (DCP), many real-world ecosystems require additional value-adding services to support discovery, coordination, trust and economic processes. Rather than introducing centralized platform components, these services must be implemented in a way that preserves the core principles of decentralization, sovereignty and participant autonomy, as set out in the Rulebook's chapter on [Decentralization](https://kb.internationaldataspaces.org/external/rulebook/007_Decentralization). In this section, we describe an architectural pattern for integrating value-adding services as specialized participants within the data space itself. We use a matchmaking service and a billing service as concrete examples and show how they can be realized using standard data space interactions. -Each service operates under the governance rules of the [Dataspace Governance Authority (DSGA)](https://kb.internationaldataspaces.org/external/rulebook/006_DSGA) and the accepted [Dataspace Trust Framework(s) (DTFs)](https://kb.internationaldataspaces.org/external/rulebook/009_Dataspace_Trust_Frameworks). Credential issuance and verification follow those DTFs and are exchanged using DCP, while contract negotiation and data exchange are governed by DSP. This keeps the services interoperable and avoids creating privileged, centralized control points. +Each service operates under the governance rules of the [Data Space Governance Authority (DSGA)](https://kb.internationaldataspaces.org/external/rulebook/006_DSGA) and the accepted [Dataspace Trust Framework(s) (DTFs)](https://kb.internationaldataspaces.org/external/rulebook/009_Dataspace_Trust_Frameworks). Credential issuance and verification follow those DTFs and are exchanged using DCP, while contract negotiation and data exchange are governed by DSP. This keeps the services interoperable and avoids creating privileged, centralized control points. ## Matchmaking Service diff --git a/docs/FrontMatter.md b/docs/FrontMatter.md index 78e206c..7af144f 100644 --- a/docs/FrontMatter.md +++ b/docs/FrontMatter.md @@ -1,4 +1,4 @@ -# IDS-RAM 2026-1 working draft # +# IDS-RAM 2026-3 # ## Publisher ## @@ -25,3 +25,15 @@ Dortmund, Germany, 2026 ![Creative Commons License](https://i.creativecommons.org/l/by/4.0/88x31.png) This work is licensed under a [Creative Commons Attribution 4.0 International License](http://creativecommons.org/licenses/by/4.0/). + +## Authors and Contributors ## + +* Sebastian Steinbuss, IDSA +* Ilknur Chulani, IDSA +* Petteri Kivimäki, Nordic Institute of Interoperability Solutions +* Markus Spiekermann, Fraunhofer ISST +* Peter Koen, Microsoft +* Andreas Krimbacher, nexyo +* Felix Larrinaga Barrenechea, Mondragon University +* Simon Lofthouse, Data Trust Company +* Achim Pascal Meyer, Sphin-X diff --git a/docs/Introduction/README.md b/docs/Introduction/README.md index 40e9dd0..6614b27 100644 --- a/docs/Introduction/README.md +++ b/docs/Introduction/README.md @@ -1,6 +1,6 @@ # Introduction -The emergence of dataspaces as a key enabler for trustworthy data sharing has introduced a new class of data +The emergence of data spaces as a key enabler for trustworthy data sharing has introduced a new class of data architecture principles. Within this landscape, the __International Data Spaces Association (IDSA)__ provides a foundational Rulebook that defines the core principles, roles, and capabilities required to establish and operate such environments. However, turning these high-level principles into actionable, technical guidance requires a dedicated @@ -11,10 +11,10 @@ abstract governance models, data usage policies, and protocol specifications int components, interfaces, and behavioral patterns. It does so with a clear focus: enabling interoperability, scalability, and conformance without prescribing a single implementation path. In other words, the IDS-RAM is not a blueprint but a design space—a structured but flexible guide that supports diverse requirements while preserving the integrity of the -IDSA dataspace model. +IDSA data space model. This document is for system architects, software engineers, and infrastructure designers who are tasked with building or -integrating components within a dataspace to enable business-driven data ecosystems. If you’re looking to understand +integrating components within a data space to enable business-driven data ecosystems. If you’re looking to understand what makes a connector IDSA-compliant, how to build interoperable and integrable services, or how to maintain trust and policies in a decentralized environment—this is your technical guidance. @@ -26,18 +26,18 @@ key capabilities like identity management, observability, data discovery, contra To support real-world applicability, the IDS-RAM organizes its content into two major sections: -__Capability Mapping:__ This section lists the essential capabilities enabled through dataspaces—such as data discovery, +__Capability Mapping:__ This section lists the essential capabilities enabled through data spaces—such as data discovery, policy enforcement, usage control, identity resolution, and observability. Each capability is analyzed from a technical -perspective, detailing how it can be implemented within a compliant dataspace. The descriptions are aligned with the +perspective, detailing how it can be implemented within a compliant data space. The descriptions are aligned with the IDSA Rulebook and maintains references to the foundational concepts to highlight the strong relation between the two -documents. The IDS-RAM content is however grounded in system-level detail, interactions pattern, documents expected +documents. The IDS-RAM content is however grounded in system-level detail, interaction patterns, documented expected behavior, and provides guidance on integration patterns of infrastructure and other technologies. __Architectural Best Practices:__ Recognizing the diversity of business and technical requirements across domains, the IDS-RAM does not enforce a singular architecture. Instead, it presents validated patterns and warns against known -anti-patterns, guiding implementers through the architectural decisions while setting up or operating a dataspace. +anti-patterns, guiding implementers through the architectural decisions while setting up or operating a data space. Whether the goal is to create a lightweight edge connector, operate a multi-tenant marketplace, or integrate with -existing enterprise systems, the IDS-RAM aims on outlining the architectural considerations and trade-offs—while maintaining +existing enterprise systems, the IDS-RAM aims to outline the architectural considerations and trade-offs—while maintaining compatibility with the IDSA model. The IDS-RAM is intentionally neutral with respect to implementations. It refrains from endorsing any specific codebase or @@ -51,11 +51,13 @@ behind decisions. Periodic release tags of the IDS-RAM document however will pro their work with a consistent snapshot of the evolving model. ## Contributions -The IDSA Working Group Architecure creates and maintains the IDS-RAM. Its mission is to guide architects and software engineers in designing and developing trusted, interoperable, and compliant data spaces. + +The IDSA Working Group Architecture creates and maintains the IDS-RAM. Its mission is to guide architects and software engineers in designing and developing trusted, interoperable, and compliant data spaces. To know more about the IDSA Working Group Architecture, please visit [our home page](https://internationaldataspaces.org/we/working-groups/). The [IDSA working groups brochure](https://internationaldataspaces.org/download/50753/?tmstv=1770728340) provides details on how to get involved and how to contribute. Please note: IDSA working group activities are reserved for members. Find more information about IDSA membership here: [Become a Member](https://internationaldataspaces.org/we/become-a-member/) ## Terminology -IDS-RAM uses terms as defined in the [IDSA Glossary](https://kb.internationaldataspaces.org/external/glossary/glossary/). + +IDS-RAM uses terms as defined in the [IDSA Glossary](https://kb.internationaldataspaces.org/external/glossary/glossary/). diff --git a/docs/Outlook/README.md b/docs/Outlook/README.md index 19e61d3..f3b52f9 100644 --- a/docs/Outlook/README.md +++ b/docs/Outlook/README.md @@ -1,5 +1,6 @@ # Outlook -IDSA Working Group Architecture has been looking at a wide range of topics in collaboration with other IDSA working groups such as the IDSA Working Group Rulebook. Some of the topics include but not limited to the following: + +IDSA Working Group Architecture has been looking at a wide range of topics in collaboration with other IDSA working groups such as the IDSA Working Group Rulebook. Some of the topics include, but are not limited to, the following: - Main technical concepts, architectural principles and patterns for data spaces @@ -21,4 +22,4 @@ IDSA Working Group Architecture has been looking at a wide range of topics in co - Patterns for value added services -Some of these items are already planned for the upcoming relase of IDS-RAM, while some would be considered in future roadmaps. +Some of these items are already planned for the upcoming release of IDS-RAM, while some would be considered in future roadmaps. diff --git a/docs/Pattern/Catalogs.md b/docs/Pattern/Catalogs.md index 8008dce..9960b6f 100644 --- a/docs/Pattern/Catalogs.md +++ b/docs/Pattern/Catalogs.md @@ -1,6 +1,6 @@ # Catalogs -This section provides architectural options for realizing dataset publication and discovery in a data space. For the underlying metadata model and discovery requirements, see the [IDSA Rulebook](https://kb.internationaldataspaces.org/external/rulebook/120_DataDiscoveryServices)'s data discovery guidance and the [Dataspace Protocol Catalog Protocol](https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/2025-1-err1/#catalog-protocol). This section does not repeat them but focuses on the architecture patterns and their trade-offs. +This section provides architectural options for realizing dataset publication and discovery in a data space. For the underlying metadata model and discovery requirements, see the [IDSA Rulebook](https://kb.internationaldataspaces.org/external/rulebook/120_DataDiscoveryServices)'s data discovery guidance and the [Dataspace Protocol Catalog Protocol](https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/2025-1-err1/#catalog-protocol). This section does not repeat them but focuses on the architecture patterns and their trade-offs. Some aspects of discovery are the same in every pattern and are treated here as a shared baseline. Metadata is expressed with DCAT: a Catalog contains Datasets, each with one or more Distributions and an associated DataService describing where and how the dataset can be obtained, and each Dataset carries one or more ODRL offers stating the policies under which it may be used. A catalog holds these descriptions and offers only — never the data itself. @@ -56,4 +56,4 @@ Decentral discovery maximizes autonomy, keeps metadata authoritative and fresh, The costs are the absence of a single searchable view: consumers must know or discover where to look, queries fan out across many endpoints, and building a global or ranked search is harder and pushed to the consumer side. Discovering endpoints in the first place needs at least a minimal shared directory or out-of-band knowledge, and consistency across independently served catalogs cannot be assumed. This pattern fits data spaces that prioritize autonomy, confidentiality of who offers what, and resilience over the convenience of centralized search. -A further constraint is network reachability. Because connectors may not be publicly reachable, full peer-to-peer discovery requires all-to-all connectivity. In practice this means that every provider must accept inbound discovery queries from every other participant — not only from the few it ends up transacting with. This is an allowlisting burden that grows with the square of the number of participants, enlarges each connector's attack surface, and must be reconfigured as the participant set changes. Mitigations exist — a shared relay or gateway that connectors reach outbound-only, or a governance-defined connectivity fabric (for example a shared mTLS trust domain or network overlay) where reachability follows from membership rather than per-peer allowlisting — but each of these reintroduces a shared component. Network reachability therefore pushes the decentral pattern back toward a federated or central arrangement — the mirror image of the caching argument in the DSGA pattern, where distributing governance data to participants pushes a central arrangement toward the decentral end of the spectrum. \ No newline at end of file +A further constraint is network reachability. Because connectors may not be publicly reachable, full peer-to-peer discovery requires all-to-all connectivity. In practice this means that every provider must accept inbound discovery queries from every other participant — not only from the few it ends up transacting with. This is an allowlisting burden that grows with the square of the number of participants, enlarges each connector's attack surface, and must be reconfigured as the participant set changes. Mitigations exist — a shared relay or gateway that connectors reach outbound-only, or a governance-defined connectivity fabric (for example a shared mTLS trust domain or network overlay) where reachability follows from membership rather than per-peer allowlisting — but each of these reintroduces a shared component. Network reachability therefore pushes the decentral pattern back toward a federated or central arrangement — the mirror image of the caching argument in the DSGA pattern, where distributing governance data to participants pushes a central arrangement toward the decentral end of the spectrum. diff --git a/docs/Pattern/DSGA.md b/docs/Pattern/DSGA.md index 5501a2f..82d5f7d 100644 --- a/docs/Pattern/DSGA.md +++ b/docs/Pattern/DSGA.md @@ -157,4 +157,4 @@ and greater overall architectural complexity. Achieving consistency and interoperability is more challenging without shared services and depends on shared semantics, such as a common claim vocabulary. Reconciliation and dispute resolution require well-defined governance rules, escalation paths, and -appropriate consensus thresholds. \ No newline at end of file +appropriate consensus thresholds. diff --git a/docs/Pattern/README.md b/docs/Pattern/README.md index 7b29c93..0a3b99a 100644 --- a/docs/Pattern/README.md +++ b/docs/Pattern/README.md @@ -1,23 +1,17 @@ # Architecture Pattern and Guidelines -*This chapter provides more concrete architecture guidelines on how to design different architecture patterns within a dataspace. Beside the introduction and explanation, trade-offs are highlighted.* - -*Please note the content on this page does not reflect the current developments yet, instead a preview of the upcoming release and an outline of what to expect is provided.* +*This chapter provides more concrete architecture guidelines on how to design different architecture patterns within a data space. Beside the introduction and explanation, trade-offs are highlighted.* ## Data Space Governance Authority (DSGA) -[The Data Space Governance Authority (DSGA) section](DSGA.md) provides architectural options for realizing a Data Space Governance Authority. The section covers central, federated and decentral approaches. +[The Data Space Governance Authority (DSGA) patterns article](DSGA.md) provides architectural options for realizing a Data Space Governance Authority. The section covers central, federated and decentral approaches. ## Catalogs -[The catalogs section](Catalogs.md) provides architectural options for realizing dataset publication and discovery in a data space. The section covers central, federated and decentral approaches. +[The Catalog patterns article](Catalogs.md) provides architectural options for realizing dataset publication and discovery in a data space. The section covers central, federated and decentral approaches. ## Observer -TODO: *Different architectural options for implementing Observer role. Please also refer to the IDSA Rulebook page [Observability](https://kb.internationaldataspaces.org/external/rulebook/121_Observability) and IDSA position paper [Observability in Data Spaces](https://internationaldataspaces.org/download/51606/?tmstv=1777284023)* - -### Federated or Central Escrow - -### Decentral observability +TODO: *Different architectural options for implementing Observer role, such as Federated or Central Escrow vs Decentral observability. Contributions are welcome.* -TODO: *Insights on decentral observability and corresponding trade-offs* +Please also refer to the IDSA Rulebook page [Observability](https://kb.internationaldataspaces.org/external/rulebook/121_Observability) and IDSA position paper [Observability in Data Spaces](https://internationaldataspaces.org/download/51606/?tmstv=1777284023) diff --git a/docs/Principles/Cataloging.md b/docs/Principles/Cataloging.md index 6ca940a..602f7c1 100644 --- a/docs/Principles/Cataloging.md +++ b/docs/Principles/Cataloging.md @@ -1,6 +1,6 @@ # Cataloging -Cataloging describes the architectural capability to **advertise data assets and data services** in a dataspace without exposing the data itself. +Cataloging describes the architectural capability to **advertise data assets and data services** in a data space without exposing the data itself. From a protocol perspective, cataloging is realized through **DSP catalog messages**, which allow participants to publish **machine-readable metadata** describing datasets, services, and associated usage policies. These catalogs form the basis for discovery and negotiation. diff --git a/docs/Principles/Credentials_and_Claims.md b/docs/Principles/Credentials_and_Claims.md index 4a41591..9ee7942 100644 --- a/docs/Principles/Credentials_and_Claims.md +++ b/docs/Principles/Credentials_and_Claims.md @@ -31,7 +31,7 @@ DCP: - **Technical specifications:** - [Decentralized Claims Protocol (DCP)](https://eclipse-dataspace-dcp.github.io/decentralized-claims-protocol/) - - [W3C Verified Credentials Data Model](https://www.w3.org/TR/vc-data-model-2.1/) + - [W3C Verifiable Credentials Data Model](https://www.w3.org/TR/vc-data-model-2.1/) - [Decentralized Identifiers (DIDs)](https://www.w3.org/TR/did-1.1/) - **Related Focus Papers:** diff --git a/docs/Principles/Data_Transfer.md b/docs/Principles/Data_Transfer.md index 116384a..53945ea 100644 --- a/docs/Principles/Data_Transfer.md +++ b/docs/Principles/Data_Transfer.md @@ -1,6 +1,6 @@ # Data Transfer (Transfer Process) -Data Transfer orchestrates the **actual exchange or access of data** between dataspace participants once a contract has been established. +Data Transfer orchestrates the **actual exchange or access of data** between data space participants once a contract has been established. This capability does **not** define how data is transferred; instead, it defines **transfer process messages** that coordinate *when* and *under which agreement* data transfer may occur. @@ -37,20 +37,20 @@ Architecturally: - It is implemented by participant-controlled data services - It may include data management systems, APIs, compute environments, or streaming infrastructures -The separation between control plane and data plane allows dataspaces to support **heterogeneous technologies and business models**, while preserving a common governance and interoperability layer. +The separation between control plane and data plane allows data spaces to support **heterogeneous technologies and business models**, while preserving a common governance and interoperability layer. ## Policy Enforcement -Policy Enforcement describes how **usage policies and contractual obligations** are applied across dataspace interactions. +Policy Enforcement describes how **usage policies and contractual obligations** are applied across data space interactions. From an architectural perspective, policy enforcement is a **shared responsibility**: -- The dataspace control plane evaluates policies during discovery, negotiation, and orchestration +- The data space control plane evaluates policies during discovery, negotiation, and orchestration - Data management services enforce policies during actual data access and use Policies are expressed in machine-readable form and referenced by DSP messages, but enforcement may occur both **technically** (e.g. access control, usage restrictions) and **organizationally** (e.g. contractual compliance). -This division ensures that dataspaces can scale without assuming control over participant infrastructure. +This division ensures that data spaces can scale without assuming control over participant infrastructure. ## Further Resources diff --git a/docs/Principles/Mapping_to_Specifications.md b/docs/Principles/Mapping_to_Specifications.md index 4acb632..18fceee 100644 --- a/docs/Principles/Mapping_to_Specifications.md +++ b/docs/Principles/Mapping_to_Specifications.md @@ -10,7 +10,7 @@ | Architectural Capability | Technical Specifications | | ------------------------- | -------------------------- | | [Credentials & Claims](Credentials_and_Claims.md) | [Decentralized Claims Protocol (DCP)](https://eclipse-dataspace-dcp.github.io/decentralized-claims-protocol/) | -| | [W3C Verified Credentials Data Model](https://www.w3.org/TR/vc-data-model-2.1/) | +| | [W3C Verifiable Credentials Data Model](https://www.w3.org/TR/vc-data-model-2.1/) | | | [Decentralized Identifiers (DIDs)](https://www.w3.org/TR/did-1.1/) | | | | | [Cataloging](Cataloging.md) | [Dataspace Protocol: Catalog](https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/2025-1-err2/#catalog-protocol) | diff --git a/docs/Principles/Observability.md b/docs/Principles/Observability.md index bd0ddb1..22539db 100644 --- a/docs/Principles/Observability.md +++ b/docs/Principles/Observability.md @@ -26,7 +26,7 @@ Observability is closely linked to other concepts such as Provenance and Traceab ![Figure 1: Scope: Observability of Data sharing contracts, not end-to-end observability in data ecosystems](../media/Observability_Scope.jpg) It is important to note that at the technical layer, this capability may be implemented by approaching the sharing of observability data just like another data sharing contract, however, setting up the necessary business processes and governance rules are the really necessary steps to truly achieve observability. -  + ![Figure 2: The need for Business and Governance Processes more than technical elements](../media/Observability_Business_Governance.jpg) ## Further Resources @@ -38,4 +38,4 @@ It is important to note that at the technical layer, this capability may be impl - [IDSA Position Paper: Observability in Data Spaces](https://internationaldataspaces.org/download/51606/?tmstv=1772198923) - **Specifications** - - [Dataspace Protocol](https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/) - See State Machines for what can be observed for each sub-protocol + - [Dataspace Protocol](https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/) - See State Machines for what can be observed for each sub-protocol diff --git a/docs/Principles/README.md b/docs/Principles/README.md index b60c002..5cad300 100644 --- a/docs/Principles/README.md +++ b/docs/Principles/README.md @@ -1,6 +1,6 @@ # Architecture Principles -This chapter provides architectural insights on the main technical concepts of dataspaces described in the [IDSA Knowledgebase](https://kb.internationaldataspaces.org/dataspace) and in the [IDSA Rulebook](https://kb.internationaldataspaces.org/external/rulebook/102_Foundational_concepts_of_a_data_space) and explains how to realize them using technical specifications such as the Dataspace Protocol (DSP) and the Decentralized Claims Protocol (DCP). +This chapter provides architectural insights on the main technical concepts of data spaces described in the [IDSA Knowledgebase](https://kb.internationaldataspaces.org/dataspace) and in the [IDSA Rulebook](https://kb.internationaldataspaces.org/external/rulebook/102_Foundational_concepts_of_a_data_space) and explains how to realize them using technical specifications such as the Dataspace Protocol (DSP) and the Decentralized Claims Protocol (DCP). ## Introduction - *Starting with the main concepts* @@ -65,7 +65,7 @@ Supports the discovery of data and services through metadata publication and con Cataloging capability is based on the DSP Catalog Protocol specification, which makes use of DCAT and application profiles. !!! tip "See also" - IDSA Rulebook page [Data Discovery Services](https://kb.internationaldataspaces.org/external/rulebook/120_DataDiscoveryServices) and and IDS-RAM [Architectural patterns for Catalogs](../Pattern/Catalogs.md). + IDSA Rulebook page [Data Discovery Services](https://kb.internationaldataspaces.org/external/rulebook/120_DataDiscoveryServices) and IDS-RAM [Architectural patterns for Catalogs](../Pattern/Catalogs.md). ### D. [Contract Negotiation](Contract_Negotiation.md) @@ -108,12 +108,12 @@ Provides evidence and accountability for actions taken during Contract negotiati ### H. Optional Services -Represents ecosystem represent ecosystem extensions (e.g., marketplaces, processing services, auditing services, escrow/confidential compute), which may be provided by participants subject to the dataspace governance framework. In the diagram, optional services “execute and enforce” the data plane and “provide inputs” into governance and framework elements. +Represents ecosystem extensions (e.g., marketplaces, processing services, auditing services, escrow/confidential compute), which may be provided by participants subject to the data space governance framework. In the diagram, optional services “execute and enforce” the data plane and “provide inputs” into governance and framework elements. >Optional services are out of scope for IDS-RAM, while still relevant for the overall landscape of data spaces. !!! tip "See also" - Focus paper [Value adding services](../FocusPapers/Value-Adding_Services_in_Decentralized_Dataspaces.md) + Focus paper [Value adding services](../FocusPapers/Value-Adding_Services_in_Decentralized_Dataspaces.md) ## Mapping to technical specifications diff --git a/docs/README.md b/docs/README.md index 40f7245..fb494bc 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,15 +8,13 @@ * [Front Matter](./FrontMatter.md) * [Focus Papers](FocusPapers/README.md) -## IDS-RAM 2026-1 working draft +## IDS-RAM 2026-3 -*We are preparing a new edition of the IDS Reference Architecture Model (IDS-RAM). Many key concepts and technical aspects of data spaces have advanced in recent months. These developments are not yet reflected in the current version, so the new edition will capture the latest results, including IDSA’s contributions to international standards and specifications.* +*This IDS-RAM 2026-3 edition of the IDS Reference Architecture Model (IDS-RAM) captures the latest results of key concepts and technical aspects of data spaces, including IDSA’s contributions to international standards and specifications.* -*The updated IDS-RAM will become the main reference for implementing the ideas defined in the IDSA Rulebook. It will translate governance models, data usage policies, and protocol specifications into clear logical components, defined interfaces, and consistent behavior patterns.* +*The IDS-RAM is the main reference for implementing the ideas defined in the IDSA Rulebook. It translates governance models, data usage policies, and protocol specifications into clear logical components, defined interfaces, and consistent behavior patterns.* -*The new version aims to support interoperability, scalability, and conformance across different environments. Instead of prescribing a single approach, it will offer a structured design space that adapts to diverse needs while preserving the core IDSA data space model.* - -*The content in the next pages aim to give a preview of the upcoming IDS-RAM 2026-1 release.* +*This version aims to support interoperability, scalability, and conformance across different environments. Instead of prescribing a single approach, it offers a structured design space that adapts to diverse needs while preserving the core IDSA data space model.* ## Join the IDS-RAM work diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index b9eacb0..21b98e5 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -6,10 +6,19 @@ * [Introduction](Introduction/README.md) * [Relation to other IDSA documents](Context/README.md) * [Architectural principles](Principles/README.md) + * [Credentials & Claims](Principles/Credentials_and_Claims.md) + * [Cataloging](Principles/Cataloging.md) + * [Contract Negotiation](Principles/Contract_Negotiation.md) + * [Data Transfer](Principles/Data_Transfer.md) + * [Observability](Principles/Observability.md) + * [Mapping to Specifications](Principles/Mapping_to_Specifications.md) * [Architectural Patterns](Pattern/README.md) + * [DSGA Patterns](Pattern/DSGA.md) + * [Catalog Patterns](Pattern/Catalogs.md) * [Outlook](Outlook/README.md) * [Front Matter](./FrontMatter.md) ## Focus Papers * [Focus Papers](FocusPapers/README.md) + * [Value-Adding Services in Decentralized Data Spaces](FocusPapers/Value-Adding_Services_in_Decentralized_Dataspaces.md)