From 6a7372cf19ac800e2ab1034647c93cc7a79cef9f Mon Sep 17 00:00:00 2001 From: Liran Cohen Date: Wed, 4 Sep 2024 09:22:54 -0400 Subject: [PATCH 1/5] Add tags field to RecordsWrite interface descriptor with detailed description on its usage and constraints --- spec/spec.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/spec/spec.md b/spec/spec.md index c717895..a37aef4 100644 --- a/spec/spec.md +++ b/spec/spec.md @@ -1052,6 +1052,9 @@ directory of the specification. - 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; if present, 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 ****MAY**** contain a `tags` property; if present, its value ****MUST**** be an object with at least one and at most ten properties. Each property value in the `tags` object can be one of the following types: string, number, boolean, or an array of strings/numbers. Arrays must have at least one item and no more than ten items. These tags can be used for categorization and filtering. The `tags` field can be constrained by a protocol definition. + + ```json { // Message From d7a0b7c4248d90fa909a08558f226635ec401a7b Mon Sep 17 00:00:00 2001 From: Liran Cohen Date: Wed, 4 Sep 2024 09:48:01 -0400 Subject: [PATCH 2/5] Finalize detailed description for $tags property with constraints in protocol definition --- spec/spec.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/spec/spec.md b/spec/spec.md index a37aef4..b6ecad6 100644 --- a/spec/spec.md +++ b/spec/spec.md @@ -1203,6 +1203,8 @@ Retained messages in the Records interface are those that may be stored against DWeb Nodes are designed to act the substrate upon which a wide variety of decentralized applications and services can be written. With an interface like [Records](#records) alone, a DWeb Node owner and those they permission can write isolated records, but that alone is not enough to support and facilitate decentralized apps. Protocols introduces a mechanism for declaratively encoding an app or service's underlying protocol rules, including segmentation of records, relationships between records, data-level requirements, and constraints on how participants interact with a protocol. With the DWeb Node Protocols mechanism, one can model the underpinning protocols for a vast array of use cases in a way that enables interop-by-default between app implementations that ride on top of them. + + #### `ProtocolsConfigure` `ProtocolsConfigure` messages are JSON objects that include general [Message Descriptor](#message-descriptors) properties and the following additional properties, which ****must**** be composed as follows: @@ -1293,6 +1295,12 @@ Protocol Definition objects are declarative rules within `ProtocolConfigure` mes - The _Protocols Definition_ object ****MUST**** contain a `structure` property, and its value ****MUST**** be a _Record Rules_ object whose keys match the labels defined in the _Protocols Definition_ object. This object is recursive, allowing subsequent record relationships to be defined within. Labeled members of the object are composed as follows: - The keys of the object ****MUST**** be a string that matches one of the `types` - The values representing those keys within the object ****MUST**** be an object composed as follows: + - The object ****MAY**** contain a `$tags` property; if present, its value ****MUST**** be an object with defined constraints: + - `$requiredTags` (optional) is an array that lists required tag names. + - `$allowUndefinedTags` (optional) is a boolean that defaults to false, and if set to false, undefined tags are not allowed. + - The constraints are a subset of JSON Schema that may include properties such as `type`, `enum`, `minimum`, `maximum`, `minLength`, `maxLength`, and others. + - Protocols can define these constraints for each tag, ensuring adherence to the expected formats and usage guidelines specified within the protocol definition. + - The object ****MAY**** contain an `$actions` property and its value ****MUST**** be an array of rule set objects described as follows: - The object ****MUST**** contain a `who` property and it ****MUST**** have one of the following values: - `anyone` From 613a781224e2c438e40a520eb22cef551445bdc5 Mon Sep 17 00:00:00 2001 From: Liran Cohen Date: Wed, 4 Sep 2024 10:03:43 -0400 Subject: [PATCH 3/5] Update $tags section in Decentralized Web Node Protocol Language and remove final blurb --- spec/spec.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/spec/spec.md b/spec/spec.md index b6ecad6..bb1766d 100644 --- a/spec/spec.md +++ b/spec/spec.md @@ -1367,6 +1367,11 @@ Please see the following JSON Schema to describe the DWN Protocol Language: - `co-update` +- The protocol **MAY** have a `$tags` section to define tag constraints within the protocol. The `$tags` section, if present, must have the following properties: + - `$requiredTags` (optional) is an array that lists required tag names. + - `$allowUndefinedTags` (optional) is a boolean that defaults to false, and if set to false, undefined tags are not allowed. + - The constraints are a subset of JSON Schema that may include properties such as `type`, `enum`, `minimum`, `maximum`, `minLength`, `maxLength`, and others. +