NIP-101 - Forms On Nostr

draft optional author:abhay-raizada

The nip provides a way for users to create form templates on nostr, and for other users to be able to fill them.

Form Template - Public

Event 30168 describes a form with field tags that contain the description of each form field, with optional settings

{
    "kind": 30168,
    "content" : ""
    "tags": [
      ["d", "<form identifier>"],
      ["name", "Name of the form"],
      ["settings", JSON.stringify({description: "<description of the form."})],
      ["field", "<fieldId>","<input-type>","<label for the field>","<Options (for option type)>", "<stringified JSON settings>"],
      ["field", "<fieldId>", "option", "label for options field", 
        JSON.stringify([["<optionId1>", "option label", "<optionId2>", "option label"]]),
        "<stringified JSON settings>"
      ]
    ],
    "pubkey": "<Author of the form>"
}

The different tags used to describe the form are described as:

Tags Description

d The unique identifier of a form, for a user

name A text serving as the name of the form

settings An optional global config for the form.

field

Contains the following values

index	name	description
1	FieldId	an id that uniqely identifies a field in the forn
2	input-type	A field that describes the type of value that can be expected as a response to this field, values can be: `text`, `option` or `label`
3	label	A label for the field
4	options	Only used for input-type option, is a Json stringified array of strings containing [`<OptionId`>, <`label`>, `<optional config>`]
5	fieldSettings	An optional JSON stringified object that contains settings specific to the field, for example `renderElement`, a setting which indicates what UI element to render to the client

Responses - Public

Response events are attached to a form(3068 kind event), and the event data is stored in a kind: 30169 event

Response structure:

{
    "kind": 30169,
    "content" : "",
    "tags": [["a", "30168:<pubkey of the author>:<form identifier>"],
    ["response", "<FieldId>", "<response as string>", "<stringified metadata object>"]],
    "pubkey": "Author of Response"
}

for option fields, the response is the id of the option selected. In case of multiple-choice fields these id's maybe delimited by a semi-colon, ";", For example:

{
    "kind": 30169,
    "content" : "",
    "tags": [["a", "30168:<pubkey of the author>:<form identifier>"],
    ["response", "<FieldId>", "ZCZC;XCZXCZ;Z34Z", "<stringified metadata object>"]],
    "pubkey": "Response author"
}

Access Control

In general access is granted by signing the event and encrypting the content with different keys. the mechanism to share the keys is by encrypting the keys and adding it to the p-tag of the event. The p-tag for kind:30168 events, should look like.

["p","<pubkey for the user>", "<optional relays>", "<Encrypted-View-Key>", "<Encrypted-Signing-key>"]

View-key : generated during form-creation, this key should used to encrypt/decrypt the ".content" string in the form template. Edit-key/Signing-Key: Is the key which is used to sign the 30168 event. Encryption should be via nip-44 using the conversation key derived from the p-tags pubkey and the signing-key.

Public Forms Public Responses

Both the form and the responses are kept in that tags array and signed by the respective users. Useful for cases like polls.

Encrypted Responses.

Response tags are added to the .content field of the event and encrypted as per the spec in nip-44 by the responders private key and the form authors public key.

Private Forms only viewable by a group.

Form fields should be placed in the .content key, nip-44 encrypted by the view-key, and the form-authors public-key. The selected responders can decrypt the form using the view key. The tags array is used to keep track of the allowed-responders identities.

Public forms editable by a group.

A signing key is generate for the group. Form fields are in the tag array, and the signing-key is encrypted in the p-tag like: ["p", "<pub-key with edit access>", "<relays>","","<encrypted signing key>"]. The key should be the same that the 30168 event is signed with. The pubkeys with edit access, will also be able to view the form responses.

Private forms editable by a group.

Form fields should be placed in the .content key, encrypted by a view-key, which is shared in the 3rd index of the p-tag for the viewers. The signing key is encrypted and placed in the 4th index of the p-tag for the editors.

4.8 KiB Raw Blame History