Documentation for ERSys 1.0.0-rc.1 (MVP)

.gitignore

@@ -15,4 +15,7 @@ docs/build/
 AGENTS.md
 .pycharm_plugin
 .gitnexus
-.idea
+.idea
+.ers-clone/
+.openapi-generator/
+.openapi-generator-ignore

CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [unreleased]
+
+## [1.0.0-rc.1] - 2026-04-21
+
+### Added
+* documentation site: Antora-based setup with CI build and GitHub Pages deployment
+* architecture: system scope, actors, core capabilities, behaviour spines, conceptual model, and deployment architecture
+* ERS-ERE contract: message-based interface specification, normative response ordering rules, and singleton cluster score semantics
+* ERE developer guide: integration checklist, implementation guidelines, and compliance requirements
+* ERE reference implementation page: online greedy clustering, Redis messaging, and configurable RDF parsing
+* API reference: auto-generated documentation for ERS and Curation REST APIs; `make` target for regeneration
+* user guide: curation app guide covering decision review, action history, and user management, with annotated screenshots
+* use cases catalogue: worker and back-office workflows
+* ADRs documenting key architectural decisions
+* glossary of domain terms and abbreviations

Makefile

@@ -15,6 +15,31 @@ NPX ?= $(shell command -v npx)
 DOC_BUILD_DIR=docs/build
 ANTORA_PLAYBOOK := $(shell pwd)/docs/antora-playbook.local.yml
 
+# ERS repo settings for API docs generation
+ERS_REPO_URL ?= https://github.com/OP-TED/entity-resolution-service.git
+ERS_REPO_BRANCH ?= develop
+ERS_CLONE_DIR = .ers-clone
+DOCS_API_PATH ?= $(shell pwd)/docs/modules/ROOT/pages/api-docs
+
+#-----------------------------------------------------------------------------
+# API docs generation
+#-----------------------------------------------------------------------------
+.PHONY: update-api-docs
+
+update-api-docs: ## Regenerate API reference docs from the ERS repo (override: DOCS_API_PATH=<abs>)
+	@ echo -e "$(BUILD_PRINT)$(ICON_PROGRESS) Cloning ERS repo ($(ERS_REPO_BRANCH))$(END_BUILD_PRINT)"
+	@ rm -rf $(ERS_CLONE_DIR)
+	@ git clone --depth 1 --branch $(ERS_REPO_BRANCH) $(ERS_REPO_URL) $(ERS_CLONE_DIR)
+	@ echo -e "$(BUILD_PRINT)$(ICON_PROGRESS) Installing ERS dependencies$(END_BUILD_PRINT)"
+	@ $(MAKE) -C $(ERS_CLONE_DIR) install
+	@ echo -e "$(BUILD_PRINT)$(ICON_PROGRESS) Generating API docs to $(DOCS_API_PATH)$(END_BUILD_PRINT)"
+	@ $(MAKE) -C $(ERS_CLONE_DIR) api-docs DOCS_API_PATH=$(DOCS_API_PATH) DOCS_API_REL=$(DOCS_API_PATH)
+	@ echo -e "$(BUILD_PRINT)$(ICON_PROGRESS) Cleaning up$(END_BUILD_PRINT)"
+	@ rm -rf $(ERS_CLONE_DIR)
+	@ rm -rf "$(DOCS_API_PATH)/ers/.openapi-generator" "$(DOCS_API_PATH)/curation/.openapi-generator" \
+		"$(DOCS_API_PATH)/ers/.openapi-generator-ignore" "$(DOCS_API_PATH)/curation/.openapi-generator-ignore"
+	@ echo -e "$(BUILD_PRINT)$(ICON_DONE) API docs updated at $(DOCS_API_PATH)/$(END_BUILD_PRINT)"
+
 #-----------------------------------------------------------------------------
 # Documentation commands
 #-----------------------------------------------------------------------------

docs/antora-playbook.local.yml

@@ -1,5 +1,5 @@
 site:
-  title: Entity Resolution Service Documentation
+  title: Entity Resolution System Documentation
 #  url: https://entity-resolution-service.readthedocs.io
   start_page: entity-resolution-docs::index.adoc
 

docs/antora-playbook.yml

@@ -1,10 +1,10 @@
 site:
-  title: Entity Resolution Service Documentation
+  title: Entity Resolution System Documentation
   start_page: entity-resolution-docs::index.adoc
 
 content:
   sources:
-    - url: https://github.com/meaningfy-ws/entity-resolution-docs.git
+    - url: https://github.com/OP-TED/entity-resolution-docs.git
       start_path: docs
       branches: [develop]
       tags: []

docs/antora.yml

@@ -1,5 +1,5 @@
 name: entity-resolution-docs
-title: Entity Resolution Service Documentation
+title: Entity Resolution System Documentation
 version: '~'
 start_page: ROOT:index.adoc
 asciidoc:

docs/modules/ROOT/nav.adoc

@@ -1,24 +1,34 @@
 * xref:index.adoc[Home]
 
 * xref:ERSArchitecture/index.adoc[ERS Architecture]
-** xref:ERSArchitecture/introduction.adoc[Introduction]
-** xref:ERSArchitecture/scope.adoc[Scope]
-** xref:ERSArchitecture/actors.adoc[Actors]
-** xref:ERSArchitecture/decissions.adoc[Decisions]
-** xref:ERSArchitecture/core-capabilities.adoc[Core Capabilities]
-** xref:ERSArchitecture/behaviour-spines.adoc[Behaviour Spines]
-** xref:ERSArchitecture/conceptual-model.adoc[Conceptual Model]
-** xref:ERSArchitecture/system-context.adoc[System Context]
-** xref:ERSArchitecture/deployment-architecture.adoc[Deployment Architecture]
 
-* xref:ERS-ERE-Contarct/index.adoc[ERS-ERE Technical Contract]
-** xref:ERS-ERE-Contarct/introduction.adoc[Introduction]
-** xref:ERS-ERE-Contarct/interface.adoc[Interface Specification]
-** xref:ERS-ERE-Contarct/suppliment.adoc[Supplement]
+* ERS
+** xref:ERSArchitecture/index.adoc[Architecture]
+*** xref:ERSArchitecture/introduction.adoc[Introduction]
+*** xref:ERSArchitecture/scope.adoc[Scope]
+*** xref:ERSArchitecture/actors.adoc[Actors]
+*** xref:ERSArchitecture/decissions.adoc[Decisions]
+*** xref:ERSArchitecture/core-capabilities.adoc[Core Capabilities]
+*** xref:ERSArchitecture/behaviour-spines.adoc[Behaviour Spines]
+*** xref:ERSArchitecture/conceptual-model.adoc[Conceptual Model]
+*** xref:ERSArchitecture/system-context.adoc[System Context]
+*** xref:ERSArchitecture/deployment-architecture.adoc[Deployment Architecture]
+** xref:AnnexeB-UseCases/index.adoc[Use Cases]
+** API Reference
+*** xref:api-docs/ers/index.adoc[ERS REST API]
+*** xref:api-docs/curation/index.adoc[Curation REST API]
 
-* xref:AnnexeA-Glossary/index.adoc[Annexe A: Glossary]
+* ERE
+** xref:ERS-ERE-Contarct/index.adoc[ERS-ERE Technical Contract]
+*** xref:ERS-ERE-Contarct/introduction.adoc[Introduction]
+*** xref:ERS-ERE-Contarct/interface.adoc[Interface Specification]
+*** xref:ERS-ERE-Contarct/suppliment.adoc[Supplement]
+** xref:ERE/ere-dev-guide.adoc[Developer Guide]
+** xref:ERE/ere-reference-impl.adoc[Basic ERE Reference Implementation]
 
-* xref:AnnexeB-UseCases/index.adoc[Annexe B: Use Cases]
-
-* xref:AnnexeC-ADRs/index.adoc[Annexe C: ADRs]
+* xref:UserGuide/curation-guide-overview.adoc[Curation App (User Guide)]
+** xref:UserGuide/curation-guide-decisions.adoc[Decisions Review]
+** xref:UserGuide/curation-guide-history.adoc[Action History]
+** xref:UserGuide/curation-guide-admin.adoc[User Management]
 
+* xref:AnnexeA-Glossary/index.adoc[Glossary]

docs/modules/ROOT/pages/AnnexeA-Glossary/glossary-1.adoc

@@ -22,7 +22,7 @@ It must remain stable for traceability but carries no identity semantics beyond
 record identifier, mention identifier
 Entity Mention Representation
 The descriptive payload of an entity mention, expressed in a specific serialised form.
-Supplied externally as part of a mention submission. Used for transport, parsing, validation, and extraction. It is not an identity construct. It includes both the payload and the indication of its format (e.g. JSON, XML, RDF).
+Supplied externally as part of a mention submission. Used for transport, parsing, validation, and extraction. It is not an identity construct. It includes both the payload and the indication of its format (e.g. RDF).
 mention payload, input payload, source payload
 Entity Representation
 A descriptive information artefact that conveys information about an entity without asserting or carrying identity.
@@ -53,7 +53,7 @@ Similarity scores are engine-internal assessment signals exposed via the contrac
 Entity Type
 An ontological category that classifies real-world entities according to their nature or role within a domain.
 They define what kind of thing an entity is (e.g. Person, Organisation) and may constrain applicable properties, resolution rules, or matching strategies. Entity types are not tags or identifiers, they do not identify entities, and do not imply the existence of a canonical entity or cluster.
-class, entity category, entity class, reference type, canonical entity type (CET)
+class, entity category, entity class, reference type
 Resolution Decision
 
 A projection artefact maintained by ERS that records the latest authoritative clustering outcome received from the ERE for a single entity mention.

docs/modules/ROOT/pages/AnnexeB-UseCases/introduction.adoc

@@ -11,6 +11,7 @@ Two use case levels are used consistently:
 
 * White use cases (Summary level) describe the value ERSys provides to an actor and the guarantees that always hold, including under degraded conditions. They define stable behavioural expectations and system boundaries and are the primary reference for reviewers and stakeholders.
 * Blue use cases (User-goal level) refine a White use case into how the system fulfils that value through interactions between ERS responsibilities and supporting components. They remain technology-agnostic but make responsibility boundaries, idempotency rules, and failure paths explicit for implementers.
+
 White use cases define the contract; Blue use cases explain its realisation.
 
 === How to read this document

docs/modules/ROOT/pages/AnnexeB-UseCases/ucb11.adoc

@@ -3,41 +3,50 @@
 *Use Case Level:* Blue (User-goal) +
 *Primary Actor:* Originator (e.g. TED-SWS, Link Curation Backend, or any submitting system) +
 *Scope:* Entity Resolution System (ERSys)  Public API (ERS) +
+
 *Supporting Actors*
 
 * Request Registry (append-only store for request registration and idempotency)
 * Decision Store (latest Cluster Assignment per mention)
 * Messaging Middleware (asynchronous interaction with Entity Resolution Engine)
 * Entity Resolution Engine (ERE)
+
 *Stakeholders and Interests*
 
 * The Originator requires a canonical identifier for each submitted Entity Mention within the agreed client-facing timeout budget.
 * ERS operators require deterministic timeout handling, strict idempotency enforcement, and isolation between synchronous API guarantees and asynchronous engine processing.
 * Downstream consumers rely on cluster identifiers as canonical identity references and must reconcile later Cluster Assignment changes via refresh mechanisms.
+
 *Brief Description* +
 This use case describes the synchronous processing performed by ERS when an Originator submits a request to resolve one Entity Mention. +
 Canonical identity is defined as a cluster managed by ERE. Cluster identifiers are canonical identifiers. ERE is authoritative for clustering outcomes and its decisions are binding. +
 Two time budgets apply: Client ↔ ERS timeout budget and ERS ↔ ERE execution window (shorter). +
+
 Upon receiving a valid request, ERS:
 
 * registers the request in the Request Registry and enforces idempotency,
 * forwards the mention to ERE using the resolve interaction,
 * waits for an ERE response within the ERS–ERE execution window.
+
 If ERE responds within the execution window, ERS returns the cluster identifier produced by ERE and records the resulting Cluster Assignment (along with alternatives) in the Decision Store. +
 If ERE does not respond within the execution window but the client timeout budget has not expired, ERS:
 
 * deterministically derives a singleton cluster identifier (Draft Identifier),
 * returns the Draft Identifier to the Originator within the client timeout budget,
 * forwards the recommended Cluster Assignment to ERE using resolveConsideringRecommendation.
+
 ERE may subsequently confirm or replace the Cluster Assignment. ERS records and exposes the latest Cluster Assignment received from ERE in the Decision Store. +
 Bulk submission, if supported, is treated as a finite list of independent single-mention requests. The execution window applies per mention. Total processing time scales with the number of mentions submitted. +
+
 *Trigger* +
 The Originator submits a resolve request containing one Entity Mention. +
+
 *Preconditions*
 
 * The request contains the required entity mention identifiers (sourceId, requestId, entityType), the entity representation payload, and the declared payload format.
 * The request may include an optional opaque context object (e.g. notice identifier). Context is treated as correlation metadata and does not influence clustering outcomes.
 * ERS maintains a Request Registry and a Decision Store.
+
 *Success Guarantee (Postconditions)* +
 For every valid request received within the client timeout budget:
 
@@ -48,18 +57,21 @@ For every valid request received within the client timeout budget:
 .. a deterministically derived Draft Identifier.
 . ERS records the latest Cluster Assignment per mention in the Decision Store.
 . The returned identifier is a valid canonical identifier at the time of response.
+
 *Minimal Guarantees (On Failure)*
 
 * If the request is syntactically invalid or violates mandatory validation rules, ERS returns an explicit validation error.
 * If a critical dependency prevents request registration or response generation within the client timeout budget, ERS returns an explicit error.
 * Timeout of the ERS–ERE execution window alone does not result in an error if the client timeout budget has not expired; instead, a Draft Identifier is issued.
+
 *Main Success Scenario  Direct Engine Response*
 
 . The Originator submits a resolve request.
 . ERS validates and registers the request.
 . ERS forwards the mention to ERE.
 . ERE returns a cluster identifier within the execution window.
 . ERS returns that cluster identifier to the Originator and records the Cluster Assignment in the Decision Store.
+
 *Alternate Scenario  Draft Identifier Issuance*
 
 . The Originator submits a resolve request.
@@ -70,19 +82,23 @@ For every valid request received within the client timeout budget:
 . ERS forwards the recommended Cluster Assignment to ERE using resolveConsideringRecommendation.
 . ERE later confirms or replaces the Cluster Assignment.
 . ERS updates the Decision Store to reflect the latest Cluster Assignment.
+
 *Extensions* +
 1a. Invalid or malformed request  ERS rejects the request and returns a validation error. +
 1b. Unsupported entity type or payload format  ERS returns an explicit error indicating the unsupported type or format. +
 2a. Idempotency conflict  If the same (sourceId, requestId, entityType) is submitted with a different payload, ERS returns an IDEMPOTENCY_CONFLICT error and does not modify the Decision Store. +
 3a. Rate limit exceeded  ERS rejects the request with a rate-limit error. +
+
 *Special Requirements*
 
 * Singular semantics: each request processes exactly one Entity Mention.
 * Cluster identifiers are canonical identifiers and originate either from ERE clustering or deterministic singleton derivation.
 * ERE decisions are binding; ERS does not override clustering outcomes.
 * ERS stores only the latest Cluster Assignment per mention in the Decision Store and does not maintain canonical entity lineage.
 * Late or duplicate ERE responses update the Decision Store only if applicable under correlation rules.
+
 *Technology and Data Variations* +
 Supported payload formats and entity types are configuration-driven. Resolution interaction types and message formats are defined in the ERS–ERE contract. +
+
 *Frequency of Occurrence* +
 High; expected to be invoked repeatedly by ingestion and integration pipelines.