decentralized-identity · andorsk · Aug 9, 2023 · Sep 6, 2023 · Sep 7, 2023 · Sep 7, 2023
diff --git a/spec/spec.md b/spec/spec.md
@@ -835,22 +835,41 @@ Get all objects of a given schema type:
 
 #### `RecordsWrite`
 
-`RecordsWrite` messages are JSON objects that include general [Message Descriptor](#message-descriptors) properties and the following additional properties, which ****must**** be composed as follows:
+`RecordsWrite` messages are JSON objects that include general [Message Descriptor](#message-descriptors) properties and the following additional properties, which ****MUST**** be composed as follows:
 
-- The message object ****MUST**** contain a `recordId` property, and its value ****MUST**** be the `recordId` of the logical record the entry corresponds with. If the message is the initial entry for a new record, the value ****MUST**** be set to the resulting string from the [_Record ID Generation Process_](#recordid-generation).
-- If the message object is attached to a Protocol, and its value ****MUST**** be a [_Computed Context ID_](#computed-context-ids). If the message is not attached to a Protocol, it ****MUST NOT**** contain a `contextId` property.
+- The message object ****MUST**** contain a `recordId` property, and its value ****MUST**** be the `recordId` of the logical record with which the entry corresponds. If the message is the initial entry for a new record, the value ****MUST**** be set to the string resulting from the [_Record ID Generation Process_](#recordid-generation).
+- The object ****MAY**** contain a `contextId` property. If present, its value ****MUST**** be the deterministic ID for a contextually linked set of objects.
+- The object ****MAY**** contain an `attestation` property. If present, its value ****MUST**** be a `string` representing the signing conditions detailed below. If the property is not present, evaluators ****MUST**** treat it as if its value was set to `optional`.
+- If the message object is attached to a Protocol, the value of its `contextId` property ****MUST**** be a [_Computed Context ID_](#computed-context-ids). If the message is not attached to a Protocol, it ****MUST NOT**** contain a `contextId` property.
+- The message object ****MUST**** contain an `authorization` property, which ****MUST**** be a JSON object as defined by the [Message Authorization](#message-authorization)
+  section of this specification, with the requirement that the `kid` and `signature` ****MUST**** match the DID of the requesting party.
+- The object ****MAY**** contain an `encryption` property. If present, its value ****MUST**** be a string that matches one of the [Supported Encryption Formats](#supported-encryption-format), indicating the encryption format with which the data is encrypted. The absence of this property indicates the data is not encrypted.
 - The message object ****MUST**** contain a `descriptor` property, and its value ****MUST**** be a JSON object composed as follows:
   - The object ****MUST**** contain an `interface` property, and its value ****MUST**** be the string `Records`.
   - The object ****MUST**** contain a `method` property, and its value ****MUST**** be the string `Write`.
-  - The object ****MUST**** include a `parentId` property if the currently active entry for the record is a `RecordsDelete` or a `CollectionWrite` that has a declared a Commit Strategy. The object ****MUST NOT**** contain a `parentId` under any other circumstance. If present, the value of the `parentId` property ****MUST**** be the stringified [Version 1 CID](https://docs.ipfs.io/concepts/content-addressing/#identifier-formats) of the [DAG CBOR](https://github.com/ipld/specs/blob/master/block-layer/codecs/dag-cbor.md) encoded `descriptor` object of the previous `RecordsWrite` or `RecordsDelete` entry the message is intending to overwrite.
-  - The object ****MAY**** contain a `protocol` property, and its value ****Must**** be a URI that denotes the Protocol an object is a part of.
-    - If the object contains a `protocol` property the object ****MUST**** also contain a `protocolVersion` property, and its value ****Must**** be a [SemVer](https://semver.org/) string that denotes the version of the Protocol the object is a part of.
-  - The object ****MAY**** contain a `schema` property, and if present its value ****Must**** be a URI string that indicates the schema of the associated data and ****MUST**** be treated as an immutable value for the lifetime of the logical record.
-  - The object ****MAY**** contain a `commitStrategy` property, and if present its value ****Must**** be a string from the table of registered [Commit Strategies](#commit-strategies).
-  - The object ****MAY**** contain a `published` property, and if present its value ****Must**** be a boolean indicating the record's publication state. A value of `true` indicates the record has been published for public queries and consumption without requiring authorization. A value of `false` or the absence of the property indicates the record ****MUST NOT**** be served in response to public queries that lack proper authorization.
-  - The object ****MAY**** contain an `encryption` property, and if present its value ****Must**** be a string that matches one of the [Supported Encryption Formats](#supported-encryption-format), indicating the encryption format with which the data is encrypted. The absence of this property indicates the data is not encrypted.
+  - The object ****MAY**** include a `parentId` property if the currently active entry for the record is a `RecordsDelete` or a `CollectionWrite` that has a declared Commit Strategy. The object ****MUST NOT**** contain a `parentId` under any other circumstance. If present, the value of the `parentId` property ****MUST**** be the stringified [Version 1 CID](https://docs.ipfs.io/concepts/content-addressing/#identifier-formats) of the [DAG CBOR](https://github.com/ipld/specs/blob/master/block-layer/codecs/dag-cbor.md) encoded `descriptor` object of the previous `RecordsWrite` or `RecordsDelete` entry the message is intended to overwrite.
+  - The object ****MAY**** contain a `protocol` property. If present, its value ****MUST**** be a URI that denotes the Protocol of which the object is a part.
+    - If the object contains a `protocol` property, the object ****MUST**** also contain a `protocolVersion` property. If present, its value ****MUST**** be a [SemVer](https://semver.org/) string that denotes the version of the Protocol of which the object is a part.
+  - The object ****MAY**** contain a `schema` property. If present, its value ****MUST**** be a URI string that indicates the schema of the associated data, and ****MUST**** be treated as an immutable value for the lifetime of the logical record.
+  - The object ****MAY**** contain a `commitStrategy` property. If present, its value ****MUST**** be a string from the table of registered [Commit Strategies](#commit-strategies).
+  - The object ****MAY**** contain a `published` property. If present, its value ****MUST**** be a boolean indicating the record's publication state. A value of `true` indicates the record has been published for public queries and consumption without requiring authorization. A value of `false` or the absence of the property indicates the record ****MUST NOT**** be served in response to public queries that lack proper authorization.
   - The object ****MUST**** contain a `dateCreated` property, and its value ****MUST**** be an [[spec:rfc3339]] ISO 8601 timestamp that ****MUST**** be set and interpreted as the time the `RecordsWrite` was created by the DID owner or another permitted party.
   - The object ****MAY**** contain a `datePublished` property, and its value ****MUST**** be an [[spec:rfc3339]] ISO 8601 timestamp that ****MUST**** be set and interpreted as the time the `RecordsWrite` was published by the DID owner or another permitted party.
+  - The object ****MUST**** contain a `dataFormats` property, and its value ****MUST**** be an array of strings that indicate the format of the data in accordance with its media type designation. The most common format is JSON, which is indicated by setting the value of the `dataFormats` property to `['application/json']`.
+  - The object ****MUST**** contain a `messageTimestamp` property, which ****MUST**** be of type `string`, with a value that ****MUST**** be an [[spec:rfc3339]] ISO 8601 timestamp that ****MUST**** be set and interpreted as the time the `RecordsWrite` record itself was created by the requester.
+  - The object ****MUST**** contain a `dataCid` property, and its value ****MUST**** be the stringified [Version 1 CID](https://docs.ipfs.io/concepts/content-addressing/#identifier-formats) of the [DAG PB](https://github.com/ipld/specs/blob/master/block-layer/codecs/dag-pb.md) encoded data.
+  - The object ****MUST**** contain a `dataSize` property, and its value must be equal to the number of bytes in the record.
+
+```
+<tab-panels selected-index="0">
+<nav>
+  <button type="button">Simple Records Write Example</button>
+  <button type="button">Sample JSON Schema For Records Write</button>
+</nav>
+
+<section>
+
+::: Sample Records Write
 
 ```json
 { // Message
@@ -869,6 +888,287 @@ Get all objects of a given schema type:
   }
 }
 ```
+</section>
+
+<section>
+
+::: example Records Write - JSON Schema
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://identity.foundation/dwn/json-schemas/records-write-unidentified.json",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "descriptor"
+  ],
+  "properties": {
+    "recordId": {
+      "type": "string"
+    },
+    "contextId": {
+      "type": "string"
+    },
+    "attestation": {
+      "$ref": "https://identity.foundation/dwn/json-schemas/general-jws.json"
+    },
+    "authorization": {
+      "$ref": "https://identity.foundation/dwn/json-schemas/general-jws.json"
+    },
+    "encryption": {
+      "type": "object",
+      "properties": {
+        "algorithm": {
+          "type": "string",
+          "enum": [
+            "A256CTR"
+          ]
+        },
+        "initializationVector": {
+          "$ref": "https://identity.foundation/dwn/json-schemas/defs.json#/definitions/base64url"
+        },
+        "keyEncryption": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "properties": {
+              "rootKeyId": {
+                "type": "string"
+              },
+              "derivationScheme": {
+                "type": "string",
+                "enum": [
+                  "dataFormats",
+                  "protocolContext",
+                  "protocolPath",
+                  "schemas"
+                ]
+              },
+              "derivedPublicKey": {
+                "$ref": "https://identity.foundation/dwn/json-schemas/public-jwk.json"
+              },
+              "algorithm": {
+                "type": "string",
+                "enum": [
+                  "ECIES-ES256K"
+                ]
+              },
+              "encryptedKey": {
+                "$ref": "https://identity.foundation/dwn/json-schemas/defs.json#/definitions/base64url"
+              },
+              "initializationVector": {
+                "$ref": "https://identity.foundation/dwn/json-schemas/defs.json#/definitions/base64url"
+              },
+              "ephemeralPublicKey": {
+                "$ref": "https://identity.foundation/dwn/json-schemas/public-jwk.json"
+              },
+              "messageAuthenticationCode": {
+                "$ref": "https://identity.foundation/dwn/json-schemas/defs.json#/definitions/base64url"
+              }
+            },
+            "additionalProperties": false,
+            "required": [
+              "rootKeyId",
+              "derivationScheme",
+              "algorithm",
+              "encryptedKey",
+              "initializationVector",
+              "ephemeralPublicKey",
+              "messageAuthenticationCode"
+            ]
+          }
+        }
+      },
+      "additionalProperties": false,
+      "required": [
+        "algorithm",
+        "initializationVector",
+        "keyEncryption"
+      ]
+    },
+    "descriptor": {
+      "type": "object",
+      "properties": {
+        "interface": {
+          "enum": [
+            "Records"
+          ],
+          "type": "string"
+        },
+        "method": {
+          "enum": [
+            "Write"
+          ],
+          "type": "string"
+        },
+        "recipient": {
+          "$ref": "https://identity.foundation/dwn/json-schemas/defs.json#/definitions/did"
+        },
+        "protocol": {
+          "type": "string"
+        },
+        "protocolPath": {
+          "type": "string",
+          "pattern": "^[a-zA-Z]+(\/[a-zA-Z]+)*$"
+        },
+        "schema": {
+          "type": "string"
+        },
+        "parentId": {
+          "type": "string"
+        },
+        "dataCid": {
+          "type": "string"
+        },
+        "dataSize": {
+          "type": "number"
+        },
+        "dateCreated": {
+          "$ref": "https://identity.foundation/dwn/json-schemas/defs.json#/definitions/date-time"
+        },
+        "messageTimestamp": {
+          "$ref": "https://identity.foundation/dwn/json-schemas/defs.json#/definitions/date-time"
+        },
+        "published": {
+          "type": "boolean"
+        },
+        "datePublished": {
+          "$ref": "https://identity.foundation/dwn/json-schemas/defs.json#/definitions/date-time"
+        },
+        "dataFormat": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false,
+      "required": [
+        "interface",
+        "method",
+        "dataCid",
+        "dataSize",
+        "dateCreated",
+        "messageTimestamp",
+        "dataFormat"
+      ],
+      "dependencies": {
+        "parentId": [
+          "protocol"
+        ]
+      },
+      "allOf": [
+        {
+          "$comment": "rule defining `published` and `datePublished` relationship",
+          "anyOf": [
+            {
+              "properties": {
+                "published": {
+                  "type": "boolean",
+                  "enum": [
+                    true
+                  ]
+                }
+              },
+              "required": [
+                "published",
+                "datePublished"
+              ]
+            },
+            {
+              "properties": {
+                "published": {
+                  "type": "boolean",
+                  "enum": [
+                    false
+                  ]
+                }
+              },
+              "not": {
+                "required": [
+                  "datePublished"
+                ]
+              }
+            },
+            {
+              "allOf": [
+                {
+                  "not": {
+                    "required": [
+                      "published"
+                    ]
+                  }
+                },
+                {
+                  "not": {
+                    "required": [
+                      "datePublished"
+                    ]
+                  }
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    }
+  },
+  "$comment": "rule defining `protocol` and `contextId` relationship",
+  "anyOf": [
+    {
+      "properties": {
+        "descriptor": {
+          "type": "object",
+          "required": [
+            "protocol",
+            "protocolPath",
+            "schema"
+          ]
+        }
+      },
+      "required": [
+        "contextId"
+      ]
+    },
+    {
+      "allOf": [
+        {
+          "not": {
+            "required": [
+              "contextId"
+            ]
+          }
+        },
+        {
+          "properties": {
+            "descriptor": {
+              "type": "object",
+              "not": {
+                "required": [
+                  "protocol"
+                ]
+              }
+            }
+          }
+        },
+        {
+          "properties": {
+            "descriptor": {
+              "type": "object",
+              "not": {
+                "required": [
+                  "protocolPath"
+                ]
+              }
+            }
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+</section>
+</tab-panels>
 
 #### `RecordsCommit`