From e357f4ca86e6f428d84dcc4896708c2c3ca3625e Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Sun, 21 Jul 2024 15:16:12 +0200 Subject: [PATCH 1/9] Add identifier syntax --- spec/Appendix A -- Persisted Documents.md | 29 +++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/spec/Appendix A -- Persisted Documents.md b/spec/Appendix A -- Persisted Documents.md index cfda7197..3c4d3f9a 100644 --- a/spec/Appendix A -- Persisted Documents.md +++ b/spec/Appendix A -- Persisted Documents.md @@ -95,6 +95,35 @@ implementation specific. Note: A 32 character hexadecimal _custom document identifier_ is likely to be an MD5 hash of the GraphQL document, as traditionally used by Relay. +### Document identifier syntax + +DocumentIdentifier :: + +- PrefixedDocumentIdentifier +- CustomDocumentIdentifier + +PrefixedDocumentIdentifier :: + +- Sha256HexDocumentIdentifier +- OtherPrefixedDocumentIdentifier + +Sha256HexDocumentIdentifier :: sha256 `:` Sha256Checksum + +Sha256Checksum :: 64 LowerCaseHexDigit + +LowerCaseHexDigit :: one of + +- `0` `1` `2` `3` `4` `5` `6` `7` `8` `9` +- `a` `b` `c` `d` `e` `f` + +OtherPrefixedDocumentIdentifier :: x- IdentifierCharacter+ `:` IdentifierCharacter+ + +CustomDocumentIdentifier :: SourceCharacter+ + +IdentifierCharacter :: SourceCharacter but not `:` + +SourceCharacter :: "Any Unicode scalar value" + ## Persisting a Document To utilize persisted documents for a request, the client must possess a unique From daa0becf380acba89c2242e5addda975dfde6065 Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Sun, 21 Jul 2024 15:52:48 +0200 Subject: [PATCH 2/9] Update spec/Appendix A -- Persisted Documents.md Co-authored-by: Shane Krueger --- spec/Appendix A -- Persisted Documents.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/Appendix A -- Persisted Documents.md b/spec/Appendix A -- Persisted Documents.md index 3c4d3f9a..a0752a0e 100644 --- a/spec/Appendix A -- Persisted Documents.md +++ b/spec/Appendix A -- Persisted Documents.md @@ -107,7 +107,7 @@ PrefixedDocumentIdentifier :: - Sha256HexDocumentIdentifier - OtherPrefixedDocumentIdentifier -Sha256HexDocumentIdentifier :: sha256 `:` Sha256Checksum +Sha256HexDocumentIdentifier : `sha256:` Sha256Checksum Sha256Checksum :: 64 LowerCaseHexDigit From 81fa52953cbafe0e3f9a8c41a39f707cd12b68fc Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Sun, 21 Jul 2024 16:38:28 +0200 Subject: [PATCH 3/9] more consistent quoting --- spec/Appendix A -- Persisted Documents.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/Appendix A -- Persisted Documents.md b/spec/Appendix A -- Persisted Documents.md index a0752a0e..d1ffef1a 100644 --- a/spec/Appendix A -- Persisted Documents.md +++ b/spec/Appendix A -- Persisted Documents.md @@ -116,13 +116,13 @@ LowerCaseHexDigit :: one of - `0` `1` `2` `3` `4` `5` `6` `7` `8` `9` - `a` `b` `c` `d` `e` `f` -OtherPrefixedDocumentIdentifier :: x- IdentifierCharacter+ `:` IdentifierCharacter+ +OtherPrefixedDocumentIdentifier :: `x-` IdentifierCharacter+ `:` IdentifierCharacter+ CustomDocumentIdentifier :: SourceCharacter+ IdentifierCharacter :: SourceCharacter but not `:` -SourceCharacter :: "Any Unicode scalar value" +SourceCharacter :: Any Unicode scalar value ## Persisting a Document From bba578df26ca8f5cda7679bb3ed474f2627754c4 Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Mon, 22 Jul 2024 10:40:17 +0200 Subject: [PATCH 4/9] Update spec/Appendix A -- Persisted Documents.md Co-authored-by: Benjie --- spec/Appendix A -- Persisted Documents.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/Appendix A -- Persisted Documents.md b/spec/Appendix A -- Persisted Documents.md index d1ffef1a..b0531356 100644 --- a/spec/Appendix A -- Persisted Documents.md +++ b/spec/Appendix A -- Persisted Documents.md @@ -107,7 +107,7 @@ PrefixedDocumentIdentifier :: - Sha256HexDocumentIdentifier - OtherPrefixedDocumentIdentifier -Sha256HexDocumentIdentifier : `sha256:` Sha256Checksum +Sha256HexDocumentIdentifier :: `sha256:` Sha256Checksum Sha256Checksum :: 64 LowerCaseHexDigit From 3fbc34c7dac239eaa6ec3778e13abfe34fd3e077 Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Mon, 22 Jul 2024 10:43:16 +0200 Subject: [PATCH 5/9] Remove the 64 chars requirement on sha256 from the parser --- spec/Appendix A -- Persisted Documents.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/Appendix A -- Persisted Documents.md b/spec/Appendix A -- Persisted Documents.md index b0531356..eaa2b4e1 100644 --- a/spec/Appendix A -- Persisted Documents.md +++ b/spec/Appendix A -- Persisted Documents.md @@ -109,7 +109,7 @@ PrefixedDocumentIdentifier :: Sha256HexDocumentIdentifier :: `sha256:` Sha256Checksum -Sha256Checksum :: 64 LowerCaseHexDigit +Sha256Checksum :: LowerCaseHexDigit+ LowerCaseHexDigit :: one of From 5d48e0e74abbe2cf6e5ef1eb74457e58f5b1670d Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Mon, 22 Jul 2024 10:56:06 +0200 Subject: [PATCH 6/9] Use UnreservedCharacter --- spec/Appendix A -- Persisted Documents.md | 28 +++++++++++++++++------ 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/spec/Appendix A -- Persisted Documents.md b/spec/Appendix A -- Persisted Documents.md index eaa2b4e1..8d54a0f2 100644 --- a/spec/Appendix A -- Persisted Documents.md +++ b/spec/Appendix A -- Persisted Documents.md @@ -107,22 +107,36 @@ PrefixedDocumentIdentifier :: - Sha256HexDocumentIdentifier - OtherPrefixedDocumentIdentifier -Sha256HexDocumentIdentifier :: `sha256:` Sha256Checksum - -Sha256Checksum :: LowerCaseHexDigit+ +Sha256HexDocumentIdentifier :: `sha256:` LowerCaseHexDigit+ LowerCaseHexDigit :: one of - `0` `1` `2` `3` `4` `5` `6` `7` `8` `9` - `a` `b` `c` `d` `e` `f` -OtherPrefixedDocumentIdentifier :: `x-` IdentifierCharacter+ `:` IdentifierCharacter+ +OtherPrefixedDocumentIdentifier :: `x-` UnreservedCharacter+ `:` UnreservedCharacter+ + +CustomDocumentIdentifier :: UnreservedCharacter+ + +UnreservedCharacter :: -CustomDocumentIdentifier :: SourceCharacter+ +- Letter +- Digit +- `-` +- `.` +- `_` +- `~` -IdentifierCharacter :: SourceCharacter but not `:` +Letter :: one of -SourceCharacter :: Any Unicode scalar value +- `A` `B` `C` `D` `E` `F` `G` `H` `I` `J` `K` `L` `M` +- `N` `O` `P` `Q` `R` `S` `T` `U` `V` `W` `X` `Y` `Z` +- `a` `b` `c` `d` `e` `f` `g` `h` `i` `j` `k` `l` `m` +- `n` `o` `p` `q` `r` `s` `t` `u` `v` `w` `x` `y` `z` + +Digit :: one of + +- `0` `1` `2` `3` `4` `5` `6` `7` `8` `9` ## Persisting a Document From 014506dcc0d9441e671ba9e8e837788cb29adbc0 Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Mon, 22 Jul 2024 11:35:34 +0200 Subject: [PATCH 7/9] format --- spec/Appendix A -- Persisted Documents.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/spec/Appendix A -- Persisted Documents.md b/spec/Appendix A -- Persisted Documents.md index 8d54a0f2..bb67af4e 100644 --- a/spec/Appendix A -- Persisted Documents.md +++ b/spec/Appendix A -- Persisted Documents.md @@ -114,7 +114,8 @@ LowerCaseHexDigit :: one of - `0` `1` `2` `3` `4` `5` `6` `7` `8` `9` - `a` `b` `c` `d` `e` `f` -OtherPrefixedDocumentIdentifier :: `x-` UnreservedCharacter+ `:` UnreservedCharacter+ +OtherPrefixedDocumentIdentifier :: `x-` UnreservedCharacter+ `:` +UnreservedCharacter+ CustomDocumentIdentifier :: UnreservedCharacter+ From eeab3f3e9d528f818898b4c7ce7ea1801748827c Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Fri, 26 Jul 2024 09:51:28 +0200 Subject: [PATCH 8/9] Feedbacks: - move `x-` and `sha256` to validation - allow `:` in prefixed identifier payloads - add link to RFC3986 --- spec/Appendix A -- Persisted Documents.md | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/spec/Appendix A -- Persisted Documents.md b/spec/Appendix A -- Persisted Documents.md index bb67af4e..a16b2bb6 100644 --- a/spec/Appendix A -- Persisted Documents.md +++ b/spec/Appendix A -- Persisted Documents.md @@ -97,6 +97,12 @@ MD5 hash of the GraphQL document, as traditionally used by Relay. ### Document identifier syntax +A _document identifier_ must only contain colons (`:`) and characters that are +defined as +[`unreserved` in RFC3986](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) +(alphanumeric characters (`A-Z`, `a-z`, `0-9`), dashes (`-`), periods (`.`), +underscores (`_`), and tildes (`~`)). + DocumentIdentifier :: - PrefixedDocumentIdentifier @@ -104,20 +110,18 @@ DocumentIdentifier :: PrefixedDocumentIdentifier :: -- Sha256HexDocumentIdentifier -- OtherPrefixedDocumentIdentifier +- Prefix `:` Payload -Sha256HexDocumentIdentifier :: `sha256:` LowerCaseHexDigit+ +Prefix :: UnreservedCharacter+ -LowerCaseHexDigit :: one of +Payload :: PayloadCharacter+ -- `0` `1` `2` `3` `4` `5` `6` `7` `8` `9` -- `a` `b` `c` `d` `e` `f` +CustomDocumentIdentifier :: UnreservedCharacter+ -OtherPrefixedDocumentIdentifier :: `x-` UnreservedCharacter+ `:` -UnreservedCharacter+ +PayloadCharacter :: -CustomDocumentIdentifier :: UnreservedCharacter+ +- UnreservedCharacter +- `:` UnreservedCharacter :: From dda338ea06d86241ec0f3e1b6baaa3484c53c516 Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Sat, 27 Jul 2024 00:08:26 +0200 Subject: [PATCH 9/9] remove parser ambiguity --- spec/Appendix A -- Persisted Documents.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/Appendix A -- Persisted Documents.md b/spec/Appendix A -- Persisted Documents.md index a16b2bb6..1c899f41 100644 --- a/spec/Appendix A -- Persisted Documents.md +++ b/spec/Appendix A -- Persisted Documents.md @@ -116,7 +116,7 @@ Prefix :: UnreservedCharacter+ Payload :: PayloadCharacter+ -CustomDocumentIdentifier :: UnreservedCharacter+ +CustomDocumentIdentifier :: UnreservedCharacter+ [lookahead != `:`] PayloadCharacter ::