Release/1.5.0 (#379)

## [1.5.0] - 2025-02-04

The ARF is aligned with the adopted Implementing Acts, covering articles 5a and 5c of the eIDAS Regulation. 

The ARF also includes changes in response to comments provided on Github and by other stakeholders. Over more than 275 comments lead to changes in the ARF.

-----

Co-authored-by: David Bakker <75264147+david-bakker@users.noreply.github.com>
Co-authored-by: JoranAF <jfrik@deloitte.com>
Co-authored-by: Nikos Fotiou <nikosft@gmail.com>
Co-authored-by: Paolo De Rosa <paolo.de.rosa@linux.com>
Co-authored-by: Kristina <52878547+Sakurann@users.noreply.github.com>
Co-authored-by: Paul Hin <phin@scytales.com>
Co-authored-by: duviner <59258606+duviner@users.noreply.github.com>
Co-authored-by: José Miranda <pinamiranda@users.noreply.github.com>

.github/workflows/pages.yml

@@ -22,7 +22,7 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/setup-python@v4
         with:
           python-version: 3.x
@@ -34,11 +34,19 @@ jobs:
           restore-keys: |
             mkdocs-material-
       - run: pip install mkdocs-material mike
+      - uses: r-lib/actions/setup-pandoc@v2
+        with:
+          pandoc-version: latest
+      - run: sudo apt update -y
+      - run: sudo apt install -y texlive-full texlive-xetex
       - run: |
           git config --local user.email "github-actions[bot]@users.noreply.github.com"
           git config --local user.name "github-actions[bot]"
       - run: git pull
-      - run: mike deploy --push --update-aliases 1.4.0 latest
+      - run: make
+      - run: mike deploy --push --update-aliases latest
       - run: mike set-default --push latest
-      # - run: mike deploy --push 1.4.0
-
+      - uses: actions/upload-artifact@v4
+        with:
+          name: architecture-and-reference-framework
+          path: build/pdf

.gitignore

@@ -4,3 +4,7 @@ node_modules
 dist
 build
 site
+docs/arf.html
+docs/arf.jpeg
+docs/arf.pdf
+docs/arf.png

CHANGELOG

@@ -6,7 +6,20 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semverdoc.org/).
 
 ## [1.0.0] - 2023-02-10
-Initial release
+
+Initial release.
 
 ## [1.4.0] - 2024-05-20
-- The Annex structure has been updated. Each Annex is now located in a separate folder. 
+
+The Annex structure has been updated. Each Annex is now located in a separate folder.
+
+## [1.4.1] - 2024-09-11
+
+Editorial corrections.  
+
+## [1.5.0] - 2025-02-04
+
+The ARF is aligned with the adopted Implementing Acts, covering articles 5a and 5c of the eIDAS Regulation. 
+
+The ARF also includes changes in response to comments provided on Github and by other stakeholders. Over more than 275 comments lead to changes in the ARF.
+

CONTRIBUTING.md

@@ -1,24 +1,31 @@
 # Contributing to The European Digital Identity Wallet Architecture and Reference Framework
 
-We welcome contributions to [The European Digital Identity Wallet Architecture and Reference Framework](README.md) (ARF) Whether it's fixing a bug, proposing a new feature, or improving documentation, we appreciate any and all contributions that can help make the ARF better.
+We welcome contributions to [The European Digital Identity Wallet
+Architecture and Reference Framework](README.md) (ARF). Whether you are
+fixing a bug, proposing a new feature, or improving documentation, we
+appreciate any contributions that help improve the ARF.
 
-## How to contribute
+## How to Contribute
 
-1. Fork the repository and make your changes in a separate branch.
-3. Submit a pull request to the `main` branch.
-4. The pull request will be reviewed and potentially merged.
+1. Fork the repository and create your changes on a separate branch.
+2. Submit a pull request targeting the `main` branch.
+3. Your pull request will be reviewed and, if approved, merged.
 
 ## Guidelines
 
-* Follow the existing style and conventions.
-* Document any addition or changes to existing text.
-* Proofread your copy thoroughly before submitting a pull request.
-* Keep your pull request focused on one specific change or fix.
+- Follow the existing style and conventions.
+- Document any additions or changes to the text.
+- Proofread your work thoroughly before submitting a pull request.
+- Keep each pull request focused on a single change or fix.
 
 ## Code of Conduct
 
-We expect all contributors to abide by our [Code of Conduct](link) (pending). Please make sure you are familiar with its contents before contributing.
+All contributors are expected to abide by our
+[Code of Conduct](link) (pending). Please ensure you are familiar with its
+contents before contributing.
 
 ## License
 
-By contributing to [The European Digital Identity Wallet Architecture and Reference Framework](README.md), you agree that your contributions will be licensed under the [Project's License](LICENSE).
+By contributing to [The European Digital Identity Wallet Architecture
+and Reference Framework](README.md), you agree that your contributions will
+be licensed under the [Project's License](LICENSE).

Makefile

@@ -1,68 +1,104 @@
 # Makefile
-# Converts Markdown to other formats (HTML, PDF, DOCX, EPUB) using Pandoc and MkDocs
+# -----------------------------------------------------------------------------
+# Converts Markdown to various formats (HTML via MkDocs, PDF, DOCX, EPUB)
+# using Pandoc and MkDocs.
 #
-# Run "make" (or "make all") to convert to all other formats
-# Run "make clean" to delete converted files
-
-# Prerequisites
-# Install pandoc, latex and mkdocs in your environment 
-#  - Ubuntu: `sudo apt-get install pandoc`
-#            `sudo apt install python3 python3-pip -y`
-#            `pip3 install mkdocs`
-#            `pip install mkdocs-material mike`
-#            `mkdocs --version`
+# Usage:
+#   make             - Convert Markdown files to PDF, DOCX, EPUB and build the MkDocs site.
+#   make mkdocs      - Build the MkDocs site.
+#   make serve       - Serve the MkDocs site locally.
+#   make copy-pdfs   - Copy all PDF files from the docs folder to build/pdf.
+#   make zip-pdfs    - Create a zip file of all files in the build/pdf folder.
+#   make clean       - Delete all generated files.
 #
-# Parameters and Variables
-# https://www.gnu.org/software/make/manual/html_node/Automatic-Variables.html#Automatic-Variables
+# Prerequisites:
+#   - pandoc (Ubuntu: `sudo apt-get install pandoc`)
+#   - a LaTeX distribution (for PDF conversion, e.g., xelatex)
+#   - mkdocs (and optionally, mkdocs-material and mike)
 #
-
-# Convert .docx to .md
-# pandoc --extract-media ./assets input.docx -o output.md
-
-SOURCE_DOCS := $(wildcard docs/*.md)
-BUILD_DIR :=./build
-SITE_DIR :=./site
-EXPORTED_DOCS=\
- $(SOURCE_DOCS:.md=.pdf) \
- $(SOURCE_DOCS:.md=.docx) \
- $(SOURCE_DOCS:.md=.epub)
-
-RM=/bin/rm
-PANDOC=pandoc
-MKDOCS=mkdocs
-
-PANDOC_OPTIONS=--toc --metadata title="The European Digital Identity Wallet Architecture and Reference Framework" --metadata lang="en" --data-dir docs/media
-PANDOC_PDF_OPTIONS= --pdf-engine=xelatex
-PANDOC_DOCX_OPTIONS=
-PANDOC_EPUB_OPTIONS=--to epub3
-
-# Pattern-matching Rules
-
+# -----------------------------------------------------------------------------
+
+# Source Files
+MAIN_DOC       := docs/architecture-and-reference-framework-main.md
+ANNEXES_DOCS   := $(wildcard docs/annexes/annex-[1-3]/*.md)
+SOURCE_DOCS    := $(MAIN_DOC) $(ANNEXES_DOCS)
+
+# Directories and Build Information
+BUILD_DIR      := ./build
+SITE_DIR       := ./site
+VERSION        := 1.5.0
+BUILD          := $(shell date +%Y%m%d.%H%M%S)
+
+# Pandoc configuration
+PANDOC_DATA_DIR  := ./pandoc
+PDF_TEMPLATE     := eisvogel
+
+# Exported Documents (the target names are based on the source file names)
+EXPORTED_DOCS  := \
+	$(SOURCE_DOCS:.md=.pdf) \
+	$(SOURCE_DOCS:.md=.docx) \
+	$(SOURCE_DOCS:.md=.epub)
+
+# Tools
+RM      := /bin/rm
+PANDOC  := pandoc
+MKDOCS  := mkdocs
+
+# Pandoc Options
+PANDOC_OPTIONS      := --toc --from markdown+gfm_auto_identifiers --data-dir $(PANDOC_DATA_DIR) --metadata date="v$(VERSION)  $(BUILD)"
+PANDOC_PDF_OPTIONS  := --pdf-engine=pdflatex --template=$(PDF_TEMPLATE) --listings $(PANDOC_DATA_DIR)/metadata.yml
+PANDOC_DOCX_OPTIONS :=
+PANDOC_EPUB_OPTIONS := --to epub3
+
+# Pattern Rules for Conversions
+# -----------------------------------------------------------------------------
+
+# Convert Markdown to PDF
 %.pdf : %.md
-	mkdir -p $(BUILD_DIR)/pdf
+	@mkdir -p $(BUILD_DIR)/pdf
 	$(PANDOC) $(PANDOC_OPTIONS) $(PANDOC_PDF_OPTIONS) -o $(BUILD_DIR)/pdf/$(notdir $@) $<
 
+# Convert Markdown to DOCX
 %.docx : %.md
-	mkdir -p $(BUILD_DIR)/docx
+	@mkdir -p $(BUILD_DIR)/docx
 	$(PANDOC) $(PANDOC_OPTIONS) $(PANDOC_DOCX_OPTIONS) -o $(BUILD_DIR)/docx/$(notdir $@) $<
 
+# Convert Markdown to EPUB
 %.epub : %.md
-	mkdir -p $(BUILD_DIR)/epub
+	@mkdir -p $(BUILD_DIR)/epub
 	$(PANDOC) $(PANDOC_OPTIONS) $(PANDOC_EPUB_OPTIONS) -o $(BUILD_DIR)/epub/$(notdir $@) $<
 
+# Targets
+# -----------------------------------------------------------------------------
 
-# Targets and dependencies
-
-.PHONY: all clean
+.PHONY: all mkdocs serve copy-pdfs zip-pdfs clean
 
-all : $(EXPORTED_DOCS) mkdocs
+# Default target: build all exported documents and the MkDocs site.
+all: $(EXPORTED_DOCS) zip-pdfs
 
+# Build the MkDocs site
 mkdocs:
 	$(MKDOCS) build
 
+# Serve the MkDocs site locally
 serve:
 	$(MKDOCS) serve
 
+# Copy all PDF files from the docs folder to the build/pdf directory.
+copy-pdfs:
+	@echo "Copying PDF files from docs/ to $(BUILD_DIR)/pdf/..."
+	@mkdir -p $(BUILD_DIR)/pdf
+	@find docs -maxdepth 3 -type f -iname "*.pdf" -exec cp {} $(BUILD_DIR)/pdf \;
+	@echo "PDF files have been copied."
+
+# Create a zip archive of all files in the build/pdf folder.
+zip-pdfs: copy-pdfs
+	@echo "Creating zip archive of PDFs in $(BUILD_DIR)/pdf..."
+	@cd $(BUILD_DIR) && zip -r arf-pdfs-v$(VERSION).zip pdf/*
+	@echo "Zip archive created at $(BUILD_DIR)/pdf.zip."
+
+# Clean generated files and directories.
 clean:
-	- $(RM) -rf $(BUILD_DIR) $(SITE_DIR)
+	@echo "Cleaning build and site directories..."
+	-$(RM) -rf $(BUILD_DIR) $(SITE_DIR)
 

README.md

@@ -10,44 +10,49 @@ Under the [Electronic Identification, Authentication and Trust Services (eIDAS)
 Regulation](https://digital-strategy.ec.europa.eu/en/policies/eidas-regulation),
 EU Member States may, on a voluntary basis, notify and recognise, national
 electronic identification schemes in their Member States. The recognition of
-notified electronic identification became mandatory in 2018.
-Yet, there is no requirement for Member States to develop a national electronic
-identification and to make it interoperable with those in other Member States.
-This has led to discrepancies between countries.
-The new Regulation on digital identity addresses shortcomings
-in eIDAS by improving the effectiveness of the framework and extending its
-benefits to the private sector.
-Member States will offer citizens and businesses digital wallets that will be
-able to link various aspects of their national digital identities. These may be
-provided by public authorities or the private sector, if they are recognized by
-the Member States.
+notified electronic identification became mandatory in 2018. Yet, there is no
+requirement for Member States to develop a national electronic identification
+and to make it interoperable with those in other Member States. This has led to
+discrepancies between countries. The new Regulation on digital identity
+addresses shortcomings in eIDAS by improving the effectiveness of the framework
+and extending its benefits to the private sector. Member States will offer
+citizens and businesses digital wallets that will be able to link various
+aspects of their national digital identities. These may be provided by public
+authorities or the private sector, if they are recognized by the Member States.
 
 The EU Digital Identity Wallet will be:
 
-* **made available to anyone who wants to use it**:  Any EU citizen, resident, and business in the EU who would like to make use of the EU Digital Identity will be able to do so.
-* **used widely**: EU Digital Identity Wallets will be used as a way to identify users when providing them with access to public and private digital services across the EU.
-* **controlled by users**: The EU Digital Identity Wallets will enable people to choose and keep track of their identity, data and certificates which they share with third parties. Anything which is not necessary to share will not be shared.
-
-Consumers should also be able to access services online without having to use private platforms or unnecessarily sharing personal data. They will have full control of the data they share.
+* **made available to anyone who wants to use it**:  Any EU citizen, resident,
+  and business in the EU who would like to make use of the EU Digital Identity
+  will be able to do so.
+* **used widely**: EU Digital Identity Wallets will be used as a way to
+  identify users when providing them with access to public and private digital
+  services across the EU.
+* **controlled by users**: The EU Digital Identity Wallets will enable people
+  to choose and keep track of their identity, data and certificates which they
+  share with third parties. Anything which is not necessary to share will not
+  be shared.
+
+Consumers should also be able to access services online without having to use
+private platforms or unnecessarily sharing personal data. They will have full
+control of the data they share.
 
 ## The Architecture and Reference Framework
 
-On 3 June 2021, the European Commission adopted a Recommendation
-calling on Member States to work towards the development of a Toolbox
-including a technical Architecture and Reference Framework
-a set of common standards and technical specifications and a
-set of common guidelines and best practices.
-
-The Recommendation specifies that these outcomes will serve as a basis
-for the implementation of the European Digital Identity
-Framework, without the process of developing the Toolbox interfering
-with, or prejudging the legislative process.
-
-The Recommendation foresees that the Toolbox is developed by Member
-States’ experts in the eIDAS Expert Group  in close coordination with
-the Commission and, where relevant for the functioning of the European
-Digital Identity (EUDI) Wallet infrastructure, other concerned public
-and private sector parties.
+On 3 June 2021, the European Commission adopted a Recommendation calling on
+Member States to work towards the development of a Toolbox including a
+technical Architecture and Reference Framework a set of common standards and
+technical specifications and a set of common guidelines and best practices.
+
+The Recommendation specifies that these outcomes will serve as a basis for the
+implementation of the European Digital Identity Framework, without the process
+of developing the Toolbox interfering with, or prejudging the legislative
+process.
+
+The Recommendation foresees that the Toolbox is developed by Member States’
+experts in the eIDAS Expert Group  in close coordination with the Commission
+and, where relevant for the functioning of the European Digital Identity (EUDI)
+Wallet infrastructure, other concerned public and private sector parties.
 
 This repository contains the "[Architecture and Reference Framework](docs/arf.md)"
 (hereinafter the [ARF](docs/arf.md)).