docs(sdk): document Yivi attribute disjunctions by rubenhensen · Pull Request #113 · encryption4all/postguard-docs

rubenhensen · 2026-06-02T07:51:12Z

Summary

Adds an Attribute disjunctions subsection to the Yivi Web section of the Authentication Methods page
Documents the AttrReq / AttrDiscon / AttrConItem type hierarchy introduced in encryption4all/postguard-js#78
Shows the optional-name-from-any-ID example (gemeente fullname OR passport OR ID card OR driving licence, with [] to make the group skippable)
Shows the mandatory variant (same shape, no empty alternative)
Includes the raw PKG wire-format JSON so integrators understand what gets sent to POST /v2/request/start
Updates the attributes parameter table entry to reflect the new AttrConItem type

Dependencies

Depends on encryption4all/postguard-js#78 (condiscon support) and encryption4all/postguard#198 (PKG ConItem wire format). The feature requires @e4a/pg-js ≥ 1.11.0.

Test plan

npm run docs:build passes with no errors
Verify the new section renders correctly on the Authentication Methods page
Code blocks are readable and the wire-format JSON matches the actual PKG body

dobby-coder · 2026-06-02T07:51:16Z

Dobby has received the request! Routing to the right specialist now...

dobby-coder

Code review

Docs-only PR; new AttrReq/AttrDiscon/AttrConItem types and the wire-format JSON match postguard-js buildStartRequestBody and the merged types in src/types.ts. One internal inconsistency: the wire-format JSON example drops an attribute that appears in the TS example above it. Companion PKG PR encryption4all/postguard#198 is still open, so no deployed PKG accepts the nested con shape yet.

Rule compliance

One style-budget violation against the postguard-docs/CLAUDE.md writing rules (target zero, hard max 1 per 1,000 words for both em dashes and bold). The new section is ~290 words and contains 3 em dashes in prose (lines 83×2, 144) and 2 bold spans (lines 83, 93) — both well over budget. PR title, cross-repo references, and docs: scope are all fine.

dobby-coder · 2026-06-02T07:59:49Z

+      [{ "t": "pbdf.pbdf.idcard.firstName" },   { "t": "pbdf.pbdf.idcard.lastName" }],
+      [{ "t": "pbdf.pbdf.drivinglicence.firstName" }, { "t": "pbdf.pbdf.drivinglicence.lastName" }]
+    ],
+    { "t": "pbdf.sidn-pbdf.mobilenumber.mobilenumber", "optional": true }


[Code review] The TS example above (lines 99-121) sets attributes to discon + mobilenumber + dateofbirth, but this wire-format JSON shows only email + discon + mobilenumber — dateofbirth is missing. Add the third entry so the JSON visibly matches the TS example, or shrink the TS example to two entries.

dobby-coder · 2026-06-02T07:59:49Z

+```
+
+::: info PKG requirement
+Attribute disjunctions require `@e4a/pg-js` ≥ 1.11.0 and a PKG running `postguard` with condiscon support. Earlier PKG versions only accept a flat `con` array.


[Code review] The companion PKG change encryption4all/postguard#198 is still open, so today no deployed PKG accepts the nested con shape. Consider holding this docs merge (or noting in-flight status) until the PKG side lands so users following the example don't hit serde errors.

dobby-coder · 2026-06-02T07:59:49Z


+### Attribute disjunctions
+
+By default each entry in `attributes` is a single attribute object (`AttrReq`). When you need to accept the same piece of information from multiple credential types — for example, a name that can come from a municipality credential, a passport, an ID card, or a driving licence — you can pass an **`AttrDiscon`** instead: a nested array where each inner array is one acceptable conjunction of attributes (an AND), and the outer array is the list of alternatives (an OR).


[Rule: postguard writing style] Two em dashes and one bold span in a single paragraph. Hard max is 1 per 1,000 words for each; this section is ~290 words. Rewrite the em-dash-flanked clause with commas or parentheses and drop the bold around AttrDiscon (the backticked code already carries the emphasis).

dobby-coder · 2026-06-02T07:59:49Z

+
+Narrow the union at runtime with `Array.isArray(item)`: `true` → `AttrDiscon`, `false` → `AttrReq`.
+
+**Making a disjunction optional** follows the Yivi convention: add an empty array `[]` as the first alternative. Yivi treats an empty conjunction as always-satisfiable, making the whole discon skippable.


[Rule: postguard writing style + writing-rules #48] Bold-sentence-opener (**Making a disjunction optional** followed by a colon and prose) is exactly the "inline header + colon + sentence" anti-pattern, and pushes the bold count over budget. Make this an #### subheading or plain prose.

dobby-coder · 2026-06-02T07:59:49Z

+
+#### How it maps to the PKG wire format
+
+The `attributes` array is forwarded verbatim as the `con` field in the `POST /v2/request/start` body. Single `AttrReq` objects serialise as `{"t":"..."}` objects; `AttrDiscon` entries serialise as nested arrays — exactly the shape the PKG's `ConItem` untagged enum expects:


[Rule: postguard writing style] Third prose em dash in the section. Replace with a comma or a colon: …nested arrays, exactly the shape the PKG's ConItem untagged enum expects:

rubenhensen · 2026-06-02T08:16:01Z

/dobby review

dobby-coder · 2026-06-02T08:16:05Z

Dobby has received the request! Routing to the right specialist now...

dobby-coder

Code review

All five prior findings resolved in fix commit ecab3b2. Docs build passes; no new issues.

Rule compliance

One minor style note (inline). Writing-rules, AI-slop, typo, conventional-commit, and cross-repo-link checks all pass.

dobby-coder · 2026-06-02T08:21:38Z

+
+To make a disjunction optional, add an empty array `[]` as the first alternative. Yivi treats an empty conjunction as always-satisfiable, making the whole discon skippable.
+
+#### Example: optional name from any government ID


[Rule: postguard-docs writing-rules] Heading contains a colon; PostGuard style guide says to avoid colons in titles. Consider #### Optional name from any government ID (the surrounding text already establishes this is an example). Non-blocking.

rubenhensen · 2026-06-02T08:22:54Z

/dobby if this is non blokcing, why did you not approve the PR?

dobby-coder · 2026-06-02T08:22:57Z

Dobby has received the request! Routing to the right specialist now...

dobby-coder

Fair call — you're right. The remaining note was explicitly non-blocking and every prior finding was resolved in ecab3b2. I should have approved on the re-review instead of leaving it as a comment. Approving now.

docs(sdk): document attribute disjunctions for Yivi sign step

c377cc1

dobby-coder Bot reviewed Jun 2, 2026

View reviewed changes

fix(docs): address dobby style and consistency comments

ecab3b2

dobby-coder Bot reviewed Jun 2, 2026

View reviewed changes

dobby-coder Bot approved these changes Jun 2, 2026

View reviewed changes

rubenhensen merged commit 66678f5 into main Jun 2, 2026
2 checks passed

rubenhensen deleted the docs/yivi-attribute-disjunctions branch June 2, 2026 08:24


		### Attribute disjunctions

		By default each entry in `attributes` is a single attribute object (`AttrReq`). When you need to accept the same piece of information from multiple credential types — for example, a name that can come from a municipality credential, a passport, an ID card, or a driving licence — you can pass an `AttrDiscon` instead: a nested array where each inner array is one acceptable conjunction of attributes (an AND), and the outer array is the list of alternatives (an OR).


		Narrow the union at runtime with `Array.isArray(item)`: `true` → `AttrDiscon`, `false` → `AttrReq`.

		Making a disjunction optional follows the Yivi convention: add an empty array `[]` as the first alternative. Yivi treats an empty conjunction as always-satisfiable, making the whole discon skippable.


		#### How it maps to the PKG wire format

		The `attributes` array is forwarded verbatim as the `con` field in the `POST /v2/request/start` body. Single `AttrReq` objects serialise as `{"t":"..."}` objects; `AttrDiscon` entries serialise as nested arrays — exactly the shape the PKG's `ConItem` untagged enum expects:


		To make a disjunction optional, add an empty array `[]` as the first alternative. Yivi treats an empty conjunction as always-satisfiable, making the whole discon skippable.

		#### Example: optional name from any government ID

Conversation

rubenhensen commented Jun 2, 2026

Summary

Dependencies

Test plan

Uh oh!

dobby-coder Bot commented Jun 2, 2026

Uh oh!

dobby-coder Bot left a comment

Choose a reason for hiding this comment

Code review

Rule compliance

Uh oh!

dobby-coder Bot Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

dobby-coder Bot Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

dobby-coder Bot Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

dobby-coder Bot Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

dobby-coder Bot Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

rubenhensen commented Jun 2, 2026

Uh oh!

dobby-coder Bot commented Jun 2, 2026

Uh oh!

dobby-coder Bot left a comment

Choose a reason for hiding this comment

Code review

Rule compliance

Uh oh!

dobby-coder Bot Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

rubenhensen commented Jun 2, 2026

Uh oh!

dobby-coder Bot commented Jun 2, 2026

Uh oh!

dobby-coder Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant