From 88a3e66ce2998e82d4790a62dacfba4b40210914 Mon Sep 17 00:00:00 2001 From: Jeffrey Yasskin Date: Fri, 7 Mar 2025 00:46:50 +0000 Subject: [PATCH 1/3] Principle: Write only one algorithm to accomplish a task. This explains why and when "polyglot" formats are a bad idea. --- index.bs | 63 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) diff --git a/index.bs b/index.bs index cf87ad01..63712641 100644 --- a/index.bs +++ b/index.bs @@ -24,6 +24,23 @@ Required IDs: using-http Link Defaults: html (dfn) queue a task/in parallel/reflect +
+{
+    "draft-ietf-oauth-sd-jwt-vc": {
+        "href": "https://datatracker.ietf.org/doc/html/draft-ietf-oauth-sd-jwt-vc",
+        "title": "SD-JWT-based Verifiable Credentials (SD-JWT VC)",
+        "status": "Internet-Draft",
+        "publisher": "IETF"
+    },
+    "vc-data-model-1.1": {
+        "href": "https://www.w3.org/TR/vc-data-model-1.1/",
+        "title": "Verifiable Credentials Data Model v1.1",
+        "status": "REC",
+        "publisher": "W3C",
+        "deliveredBy": ["https://www.w3.org/groups/wg/vc"]
+    }
+}
+
 spec:css-cascade-5; type:dfn; text:inherit
 spec:css2; type: property; text: line-height
@@ -3488,6 +3505,52 @@ While the best path forward may be to choose not to specify the feature,
 there is the risk that some implementations
 may ship the feature as a nonstandard API.
 
+
Write only one algorithm to accomplish a task

+
+When specifying how to accomplish a task, write a single algorithm to do it,
+instead of letting implementers pick between multiple algorithms.
+It is very difficult to ensure that
+two different algorithms produce the same results in all cases,
+and doing so is rarely worth the cost.
+
+Multiple algorithms seem particularly tempting when defining
+how to parse file formats,
+but they are an equally bad idea in that context.
+
+

+
+[[html-polyglot inline]] was an attempt to define a common subset of both XHTML and HTML
+that could be parsed into equivalent DOM trees
+using either the [[HTML#the-xhtml-syntax|XHTML parsing]]
+or [[HTML#syntax|HTML parsing]] algorithm.
+Authors who tried to use this syntax tended to produce documents
+that actually only worked with one of the two parsers.
+
+

+
+

+
+The [[vc-data-model-1.1 inline obsolete]] and [[cid inline]] both endorse implementations
+that use either JSON or JSON-LD to parse bytes into their data models.
+Because JSON-LD provides many more ways
+to assign properties to particular objects than JSON does,
+these specifications had to add extra rules to both kinds of parsers
+in order to ensure that each input document had exactly one possible interpretation.
+[[vc-data-model-2.0 inline]] and [[draft-ietf-oauth-sd-jwt-vc inline]] fixed the problem
+by defining different media types for JSON-LD vs JSON,
+which means implementations are instructed to use exactly one of the algorithms.
+The authors of [[cid inline]] have decided the extra specification work and testing
+are acceptable prices to be able to allow both implementation strategies,
+and they have partially mitigated the risks by explicitly stating that
+if a single document can conformantly have multiple interpretations,
+it's a specification bug.
+
+

+
+Note: While [[rfc6838#section-6|structured suffixes]] define that
+a document can be parsed in two different ways,
+they do not violate this rule because the results have different data models.
+
 
Avoid monkey patching

 A monkey patch layers new functionality on top of an existing specification in a way that extends, overrides, or otherwise modifies the existing specification's behavior.
 Monkey patching is generally considered bad practice and should be avoided for the reasons listed below; but is sometimes unavoidable

From 647465600ac6abf43056d9a4fe19df2348361f00 Mon Sep 17 00:00:00 2001
From: Jeffrey Yasskin 
Date: Wed, 12 Mar 2025 03:37:59 +0000
Subject: [PATCH 2/3] Goal instead of task.

---
 index.bs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/index.bs b/index.bs
index 63712641..5cfb3ebf 100644
--- a/index.bs
+++ b/index.bs
@@ -3505,9 +3505,9 @@ While the best path forward may be to choose not to specify the feature,
 there is the risk that some implementations
 may ship the feature as a nonstandard API.
 
-
Write only one algorithm to accomplish a task

+
Write only one algorithm to accomplish a goal

 
-When specifying how to accomplish a task, write a single algorithm to do it,
+When specifying how to accomplish a goal, write a single algorithm to do it,
 instead of letting implementers pick between multiple algorithms.
 It is very difficult to ensure that
 two different algorithms produce the same results in all cases,

From d414b303447f8871d82988cccf9a5008d4601069 Mon Sep 17 00:00:00 2001
From: Jeffrey Yasskin 
Date: Wed, 12 Mar 2025 03:39:21 +0000
Subject: [PATCH 3/3] Take Martin's suggestions.

---
 index.bs | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/index.bs b/index.bs
index 5cfb3ebf..38ec3f2b 100644
--- a/index.bs
+++ b/index.bs
@@ -3509,14 +3509,11 @@ may ship the feature as a nonstandard API.
 
 When specifying how to accomplish a goal, write a single algorithm to do it,
 instead of letting implementers pick between multiple algorithms.
+
 It is very difficult to ensure that
 two different algorithms produce the same results in all cases,
 and doing so is rarely worth the cost.
 
-Multiple algorithms seem particularly tempting when defining
-how to parse file formats,
-but they are an equally bad idea in that context.
-
 

 
 [[html-polyglot inline]] was an attempt to define a common subset of both XHTML and HTML
@@ -3524,7 +3521,7 @@ that could be parsed into equivalent DOM trees
 using either the [[HTML#the-xhtml-syntax|XHTML parsing]]
 or [[HTML#syntax|HTML parsing]] algorithm.
 Authors who tried to use this syntax tended to produce documents
-that actually only worked with one of the two parsers.
+that only worked with one of the two parsers.