Updated identification info

.github/workflows/deploy-preview.yml

@@ -0,0 +1,66 @@
+name: Deploy API Documentation Preview
+
+on:
+  pull_request:
+    types:
+      - opened
+      - synchronize
+      - reopened
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: docs-preview-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  deploy-preview:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Build docs
+        run: ./make.sh
+
+      - name: Stage preview files
+        run: |
+          mkdir -p preview/docs
+          cp index.html preview/index.html
+          cp -R docs/. preview/docs/
+
+      - name: Deploy preview to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./preview
+          destination_dir: previews/pr-${{ github.event.pull_request.number }}
+          keep_files: true
+          exclude_assets: '.github,openapi,redocly.yaml,LICENSE,README.md,make.sh'
+
+      - name: Add preview access note
+        run: |
+          preview_url="https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/previews/pr-${{ github.event.pull_request.number }}/"
+          {
+            echo "## Docs Preview"
+            echo
+            echo "Preview deployed successfully."
+            echo
+            echo "Access it here: ${preview_url}"
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Comment preview URL
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const previewUrl = `https://${context.repo.owner}.github.io/${context.repo.repo}/previews/pr-${context.issue.number}/`;
+            const body = `## Docs Preview\n\nPreview deployed successfully.\n\nAccess it here: ${previewUrl}`;
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              body
+            });

.github/workflows/deploy.yml

@@ -20,5 +20,5 @@ jobs:
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: .
-          force_orphan: true
+          keep_files: true
           exclude_assets: '.github,openapi,redocly.yaml,LICENSE,README.md,make.sh'

.github/workflows/remove-preview.yml

@@ -0,0 +1,40 @@
+name: Remove API Documentation Preview
+
+on:
+  pull_request:
+    types:
+      - closed
+
+permissions:
+  contents: write
+
+concurrency:
+  group: docs-preview-cleanup-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  remove-preview:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout GitHub Pages branch
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+          fetch-depth: 1
+
+      - name: Remove preview directory
+        run: |
+          rm -rf "previews/pr-${{ github.event.pull_request.number }}"
+
+      - name: Commit preview removal
+        run: |
+          if git diff --quiet; then
+            echo "No preview directory to remove."
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add -A
+          git commit -m "Remove docs preview for PR #${{ github.event.pull_request.number }}"
+          git push

openapi/components/schemas/ClaimsComparison.yaml

@@ -0,0 +1,41 @@
+type: object
+properties:
+  claims_matched:
+    type:
+      - boolean
+      - 'null'
+    description: |
+      Whether all non-blank required claims matched the authenticated user's data.
+
+      - `true` — all required claims matched (or no claims were provided for comparison).
+      - `false` — at least one required claim mismatched.
+      - `null` — the request is not yet completed; comparison has not run.
+    example: true
+  mismatched_claims:
+    type: object
+    description: |
+      Details of claims that did not match, keyed by claim type (for example `sub`, `name`, `birthdate`, `country`).
+      An empty object when all claims matched or the request is not yet completed.
+    additionalProperties:
+      type: object
+      properties:
+        expected:
+          type: string
+          description: The value provided when creating the identification request.
+        actual:
+          type: string
+          description: The value from the authenticated user's identity.
+      required:
+        - expected
+        - actual
+    example:
+      sub:
+        expected: "EE12345678901"
+        actual: "EE30303039914"
+  claims_comparison_errors:
+    type: array
+    description: Human-readable comparison error messages. An empty array when all claims matched or the request is not yet completed.
+    items:
+      type: string
+    example:
+      - "Value mismatch for claim 'sub', expected 'EE12345678901', got 'EE30303039914'"

openapi/components/schemas/IdentificationRequest.yaml

@@ -1,103 +1,77 @@
-type: object
-properties:
-  id:
-    type: string
-    format: uuid
-    description: The unique identifier for the identification request.
-  link:
-    type: string
-    format: uri
-    description: The link associated with the identification request.
-  link_expires_at:
-    type: string
-    format: date-time
-    description: The expiration date and time of the link.
-  claims_required:
-    type: array
-    description: A list of claims required for the identification request.
-    items:
-      type: object
-      properties:
-        type: 
-          type: string
-          description: The type of claim.
-          example: "sub"
-        value:
-          type: string
-          description: The value of the claim.
-          example: "EE30303039914"
-  completed_at:
-    type: string
-    format: date-time
-    description: The date and time when the request was completed.
-  status:
-    type: string
-    description: The current status of the identification request.
-    example: completed
-    enum:
-      - pending
-      - completed
-      - expired
-  created_at:
-    type: string
-    format: date-time
-    description: The date and time when the request was created.
-  result:
-    type: object
-    description: The result of the identification request.
+allOf:
+  - type: object
     properties:
-      acr:
+      id:
         type: string
-        example: "high"
-        description: The level of authentication based on the eIDAS LoA (level of assurance).
-      sub:
+        format: uuid
+        description: The unique identifier for the identification request.
+      link:
         type: string
-        example: "EE30303039914"
-        description: The national id or document number of the authenticated user.
-      auth_time:
-        type: integer
-        format: unix-timestamp
-        example: 1734432000
-      given_name:
+        format: uri
+        description: The link associated with the identification request.
+      link_expires_at:
         type: string
-        example: "OK"
-      family_name:
+        format: date-time
+        description: The expiration date and time of the link.
+      claims_required:
+        type: array
+        description: A list of claims required for the identification request.
+        items:
+          type: object
+          properties:
+            type:
+              type: string
+              description: The type of claim.
+              example: "sub"
+            value:
+              type: string
+              description: The value of the claim.
+              example: "EE30303039914"
+      completed_at:
         type: string
-        example: "TESTNUMBER"
-      date_of_birth:
+        format: date-time
+        description: The date and time when the request was completed.
+      status:
         type: string
-        format: date
-        example: "2000-01-01"
-      expiration_time:
-        type: integer
-        format: unix-timestamp
-        example: 1734432000
-        description: The expiration time of the identification result as a Unix timestamp (based on the document or certificate validity period).
-      authentication_type:
+        description: |
+          The current status of the identification request.
+
+          `completed` means the end-user successfully authenticated — not necessarily that all required claims matched.
+          Use `claims_matched` to determine whether the authenticated data matched your expectations.
+        example: completed
+        enum:
+          - pending
+          - completed
+          - expired
+      created_at:
         type: string
-        example: "ID_CARD"
-        description: The type of authentication used for the identification process.
-  client_id:
-    type: string
-    description: The client ID associated with the request.
-    example: "oidc-b8b8b8b8-c88f-1111-b11d-ecf190aa4982-72"
-  reference:
-    type: string
-    description: A reference string for the identification request.
-  reason:
-    type: string
-    description: The reason for the identification request.
-    example: "Test Reason"
-  reason_translations:
-    type: object
-    description: The translations of the reason for the identification request.
-    properties:
-      en:
+        format: date-time
+        description: The date and time when the request was created.
+      result:
+        description: The authenticated user's identity data. Present when the request is completed.
+        $ref: ./IdentificationResult.yaml
+      client_id:
         type: string
-        description: The translation of the reason for the identification request in English.
-      et:
+        description: The client ID associated with the request.
+        example: "oidc-b8b8b8b8-c88f-1111-b11d-ecf190aa4982-72"
+      reference:
         type: string
-        description: The translation of the reason for the identification request in Estonian.
-      ru:
+        description: A reference string for the identification request.
+      reason:
         type: string
-        description: The translation of the reason for the identification request in Russian.
+        description: The reason for the identification request.
+        example: "Test Reason"
+      reason_translations:
+        type: object
+        description: The translations of the reason for the identification request.
+        properties:
+          en:
+            type: string
+            description: The translation of the reason for the identification request in English.
+          et:
+            type: string
+            description: The translation of the reason for the identification request in Estonian.
+          ru:
+            type: string
+            description: The translation of the reason for the identification request in Russian.
+  - $ref: ./ClaimsComparison.yaml

openapi/components/schemas/IdentificationResult.yaml

@@ -0,0 +1,64 @@
+type: object
+description: |
+  The authenticated user's identity data from OIDC userinfo.
+
+  For document-based identification, `country`, `id_number`, and `document_number` may also be included
+  when available.
+
+  `sub` is always taken from OIDC userinfo and is not backfilled from document-based identification data.
+  For document-based identification, `sub` is typically the document country code followed by `id_number`
+  or `document_number`, depending on which value was used when the subject was constructed during authentication.
+properties:
+  acr:
+    type: string
+    example: "high"
+    description: The level of authentication based on the eIDAS LoA (level of assurance).
+  sub:
+    type: string
+    example: "EE30303039914"
+    description: |
+      Subject identifier for the authenticated user — typically a country-prefixed
+      document or national ID number.
+  auth_time:
+    type: integer
+    format: unix-timestamp
+    example: 1734432000
+  given_name:
+    type: string
+    example: "OK"
+  family_name:
+    type: string
+    example: "TESTNUMBER"
+  date_of_birth:
+    type: string
+    format: date
+    example: "2000-01-01"
+  expiration_time:
+    type: integer
+    format: unix-timestamp
+    example: 1734432000
+    description: |
+      The expiration time of the identification result as a Unix timestamp
+      (based on the document or certificate validity period).
+  authentication_type:
+    type: string
+    example: "ID_CARD"
+    description: |
+      The type of authentication used for the identification process
+      (for example `ID_CARD`, `SMART_ID`, `MOBILE_ID`).
+  country:
+    type: string
+    example: "GB"
+    description: |
+      Document country in ISO 3166-1 Alpha-2 format.
+      Present for document-based identification when available.
+  id_number:
+    type: string
+    example: "12345678901"
+    description: |
+      National identification number from document-based identification, when available.
+  document_number:
+    type: string
+    example: "AB123456"
+    description: |
+      Identity document number from document-based identification, when available.