112 create 2026 3 release

.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

.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

.gitignore

@@ -2,3 +2,5 @@ docs/_combined.md
 /body.pdf
 /frontmatter.pdf
 /IDS-RAM-latest.pdf
+__pycache__/
+*.pyc

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

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,42 +13,41 @@ 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.
 
 The Rulebook acts as the normative foundation of IDSA. It does not specify implementation technologies but clearly defines conditions for trust—usage control, contractual assurance, and transparent operations—thus linking data value creation with accountability.
 
 ## 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.

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.