commit 1ac4612848c2d8ffd6cb43e9dbeaa4df5b45c508
parent 1137d466d4fb093b1f721e543230bc7a1cd71329
Author: Florian Dold <florian@dold.me>
Date: Sun, 16 Aug 2026 19:32:36 +0200
DD101
Diffstat:
1 file changed, 12 insertions(+), 13 deletions(-)
diff --git a/design-documents/101-semantic-token-families.rst b/design-documents/101-semantic-token-families.rst
@@ -1,5 +1,5 @@
-DD 101: Semantic Token Families
-###############################
+DD 101: Semantic Token Families MVP
+###################################
:Status: Experimental
:DD shepherd: Florian Dold
@@ -15,6 +15,9 @@ description into v1 order choices and token outputs. The metadata is
experimental and uses the top-level keys ``experimental_subscription`` and
``experimental_discount``.
+The idea for the semantic token MVP is to implement them client-side, so we can
+evaluate them against the need of actual merchants and then iterate.
+
Motivation
==========
@@ -24,14 +27,9 @@ they aren't expected to manually apply the token effect every sale.
Requirements
============
-* Both family kinds support exact percentage and capped-flat benefits;
- discounts additionally support one free item from selected categories.
-* Benefits and issuance can be limited to product categories.
-* A subscription consumes and replaces one token.
-* A discount consumes a configured positive number of tokens and earns one
- token for each qualifying paid order.
-* Automatic issuance must work for full-price and alternative choices without
- stacking benefits.
+* easy to use for merchants
+* easy to prototype for further evaluation
+* applies both to earning and redeeming tokens
Proposed Solution
=================
@@ -215,9 +213,10 @@ output cannot provide automatic loyalty issuance.
Drawbacks
=========
-The WebUI must have trustworthy line items for category rules. Category names
-are snapshots and are not localized. The experimental schema may change
-without migration.
+* Interpretation is client-only, different implementations might diverge
+* Performance isn't great, as client needs
+ to download all tokenfamilies to evaluate
+ their rules.
Discussion / Q&A
================
