Skip to content

Commit 011b6f1

Browse files
stevenjstevenj
committed
docs: wip
1 parent 21f8bb3 commit 011b6f1

File tree

12 files changed

+600
-371
lines changed

12 files changed

+600
-371
lines changed

‎docs/src/architecture/08_concepts/signed_doc/spec/Justfile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ check: format
1616

1717
# Fix and Check Markdown files
1818
regenerate: check
19-
cue export -f -s -p signed_docs --out yaml --outfile signed_doc.yaml
19+
cue export -f -s -p signed_docs --out json --outfile signed_doc.json
2020

2121
# Pre Push Checks - intended to be run by a git pre-push hook.
2222
pre-push: regenerate

‎docs/src/architecture/08_concepts/signed_doc/spec/all_docs.cue‎

Lines changed: 0 additions & 11 deletions
This file was deleted.

‎docs/src/architecture/08_concepts/signed_doc/spec/def_cose_headers.cue‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
// Signed Document Definitions
2+
//
3+
// COSE Headers and Constraints
4+
package signed_docs
5+
6+
import "list"
7+
8+
// Supported Content Types (list of values)
9+
#contentType:
10+
*"application/json" |
11+
"application/schema+json" |
12+
"application/cbor" |
13+
"application/cddl"
14+
15+
// Supported content encodings (list of values)
16+
// All documents support content encoding, this defines the supported encoding types.
17+
// Documents may also not encode data, and will omit this field.
18+
#contentEncoding: ["br"]
19+
20+
#contentEncodings: [...#contentEncoding]
21+
22+
// Canonical List of COSE header names
23+
_coseHeaderNames: list.UniqueItems
24+
_coseHeaderNames: [
25+
"alg",
26+
"crit",
27+
"content type",
28+
"content-encoding", // Not strictly a true Cose Header, but we include it because of its relationship to `content type`
29+
"kid",
30+
"IV",
31+
"Partial IV",
32+
"counter signature",
33+
]
34+
35+
_allCoseHeaderNames: or([
36+
for k in _coseHeaderNames {k},
37+
])
38+
39+
#coseHeaderFormat:
40+
"COSE Algorithm" |
41+
"IANA Media Type" |
42+
"HTTP Content Encoding"
43+
44+
#coseField: {
45+
coseLabel: int | string
46+
description: string
47+
required: #optionalField | *"yes"
48+
format: #coseHeaderFormat
49+
if format == "IANA Media Type" {
50+
"value": {
51+
*[#contentType] | [...#contentType]}
52+
}
53+
54+
if format == "HTTP Content Encoding" {
55+
"value": #contentEncoding
56+
}
57+
}
58+
59+
// Metadata Fields that are required for every signed document
60+
#coseHeaders: {
61+
[_allCoseHeaderNames]: #coseField
62+
}
63+
_coseHeaders: #coseHeaders & {
64+
// Default Signature Algorithm
65+
alg: {
66+
coseLabel: 1
67+
required: "optional"
68+
format: "COSE Algorithm"
69+
description: "Default cryptographic signature algorithm"
70+
}
71+
72+
// Documents content type
73+
"content type": {
74+
coseLabel: 3
75+
format: "IANA Media Type"
76+
description: "IANA Media Type/s allowed in the Payload"
77+
}
78+
// Allowed content encodings
79+
"content-encoding": {
80+
coseLabel: "content-encoding"
81+
format: "HTTP Content Encoding"
82+
required: "optional"
83+
description: "Supported HTTP Encodings of the Payload"
84+
}
85+
}

‎docs/src/architecture/08_concepts/signed_doc/spec/def_metadata.cue‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
// Signed Document Definitions
2+
//
3+
// Metadata Types and Constraints
4+
package signed_docs
5+
6+
import "list"
7+
8+
// Format of a Metadata Field
9+
#metadataFormat:
10+
*"UUIDv7" |
11+
"Document Reference" |
12+
"Document Hash" |
13+
"Section Reference" |
14+
"Collaborators Reference List"
15+
16+
// Canonical List of all valid metadata names
17+
_metadataNames: list.UniqueItems
18+
_metadataNames: [
19+
"id",
20+
"ver",
21+
"ref",
22+
"ref_hash",
23+
"ref_type",
24+
"template",
25+
"template_doc",
26+
"reply",
27+
"section",
28+
"collaborators",
29+
"brand_id",
30+
"campaign_id",
31+
"election_id",
32+
"category_id",
33+
]
34+
35+
_allMetadataNames: or([
36+
for k in _metadataNames {k},
37+
])
38+
// Definition of a metadata field.
39+
#metadataField: {
40+
// Format of the field.
41+
format: #metadataFormat
42+
if format == "Document Reference" {
43+
ref: {
44+
type: [#DocumentName, ...#DocumentName]
45+
if list.Contains(type, "Template") {
46+
// What the template_ref must point to in the template for it to be valid.
47+
template_ref?: #DocumentName
48+
// What media type must the template be
49+
template_media_type?: #contentType
50+
}
51+
}
52+
}
53+
54+
// Is the field required to be present.
55+
required: #optionalField
56+
57+
// Markdown description of the field.
58+
description: string
59+
// Optional notes about validating the field.
60+
validation?: string
61+
}
62+
63+
// Metadata fields that are optional
64+
#metadataStruct: {
65+
[_allMetadataNames]: #metadataField
66+
}
67+
_metadata: #metadataStruct & {
68+
// Document ID
69+
id: #metadataField & {
70+
required: "yes"
71+
description: "Document ID, created the first time the document is created."
72+
}
73+
// Document Version
74+
ver: {
75+
required: "yes"
76+
description: """
77+
## Document Version
78+
79+
The unique version of the document.
80+
The first version of the document must set `ver` == `id`
81+
"""
82+
83+
validation: """
84+
The document version must always be >= the document ID.
85+
"""
86+
}
87+
88+
ref?: {
89+
format: "Document Reference"
90+
}
91+
92+
if ref != _|_ {
93+
ref_hash?: {
94+
format: "Document Hash"
95+
}
96+
}
97+
98+
// "ref_hash"?: string``
99+
template?: {
100+
format: "Document Reference"
101+
description: "Reference to the template used to create and/or validate this document."
102+
validation: "The document payload is not valid if it does not validate completely against the referenced template."
103+
ref: {
104+
type: ["Template"]
105+
template_ref: "Template"
106+
template_media_type: "application/schema+json"
107+
}
108+
}
109+
110+
template_doc?: {
111+
format: "Document Reference"
112+
required: "yes"
113+
description: """
114+
Metadata only in Template documents.
115+
Defines what type of document may use this template.
116+
"""
117+
ref: {
118+
type: _allDocNamesList
119+
template_ref: "Template"
120+
template_media_type: "application/schema+json"
121+
}
122+
}
123+
124+
reply?: {
125+
format: "Document Reference"
126+
required: "optional"
127+
description: """
128+
Reference to a Comment document type being referred to.
129+
"""
130+
validation: """
131+
The `ref` of the `reply` document must be the same as
132+
the original comment document.
133+
"""
134+
}
135+
136+
section?: {
137+
format: "Section Reference"
138+
required: "optional"
139+
description: """
140+
A Reference to the original document, or the comment being replied to.
141+
"""
142+
validation: """
143+
For a non-reply this must be a valid section reference into the referenced document.
144+
For a reply, this must be a valid section reference into the comment being replied to.
145+
"""
146+
}
147+
148+
collaborators?: {
149+
format: "Collaborators Reference List"
150+
required: "optional"
151+
description: """
152+
A list of collaborators who may also publish updates to versions of this document.
153+
This should include all parties who have not signed this document directly.
154+
"""
155+
validation: """
156+
This list does not imply these collaborators have consented to collaborate, only that the author/s
157+
are permitting these potential collaborators to participate in the drafting and submission process.
158+
"""
159+
}
160+
161+
brand_id?: {
162+
format: "Document Reference"
163+
required: "optional"
164+
description: "A reference to the Brand Parameters Document this document lies under."
165+
}
166+
167+
campaign_id?: {
168+
format: "Document Reference"
169+
required: "optional"
170+
description: "A reference to the Campaign Parameters Document this document lies under."
171+
}
172+
173+
election_id?: {
174+
format: "Document Reference"
175+
required: "optional"
176+
description: "A reference to the Election Parameters Document this document lies under."
177+
}
178+
179+
category_id?: {
180+
format: "Document Reference"
181+
required: "optional"
182+
description: "A reference to the Category Parameters Document this document lies under."
183+
}
184+
185+
}

‎docs/src/architecture/08_concepts/signed_doc/spec/def_signed_doc.cue‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
// Signed Document Definitions
2+
//
3+
// Base Types and Constraints
4+
package signed_docs
5+
6+
#optionalField:
7+
"yes" |
8+
"optional" |
9+
*"excluded"
10+
11+
// A UUIDv4 formatted string regex
12+
#uuidv4: =~"^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-4[0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}$"
13+
14+
// A uuidv7 formatted string regex
15+
#uuidv7: =~"^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{7}-4[0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}$"
16+
17+
// Document Type must be a valid UUIDv4
18+
#docType: #uuidv4
19+
20+
// Document ID or Version must be a valid UUIDv7
21+
#docIdOrVer: #uuidv7
22+
23+
#templateMetadata: {
24+
[_metadataNames]: #metadataField
25+
}
26+
#templateMetadata: {
27+
"template doc": {
28+
format: "Document Reference"
29+
required: "yes"
30+
description: """
31+
Metadata only in Template documents.
32+
Defines what type of document may use this template.
33+
"""
34+
}
35+
36+
"template ref": {
37+
format: "Document Reference"
38+
required: "yes"
39+
description: """
40+
Metadata only in Template documents.
41+
Defines what the `ref` field of the document using the template must be.
42+
Prevents a Document using the wrong kind of template.
43+
"""
44+
}
45+
46+
}
47+
48+
// Individual Signed Document Definition
49+
#signedDocument: {
50+
// The Document Type Identifier
51+
type!: #docType
52+
53+
// The description of this document. Markdown Supported.
54+
description?: string
55+
56+
// Fixed headers in every document
57+
headers: _coseHeaders
58+
59+
// The Metadata fields in this document (non cose standard)
60+
metadata: _metadata
61+
}
62+
63+
// We can only define known documents in the document definitions object
64+
#DocumentDefinitions: {
65+
[_allDocNames]: #signedDocument
66+
}
67+
68+
// Default Definitions for all documents.
69+
// Customize each document type in its own `<document_name>.cue` file.
70+
docs: #DocumentDefinitions & {
71+
for k, v in _allDocs {
72+
(k): {
73+
type: v
74+
}
75+
}
76+
}

0 commit comments

Comments
 (0)