nostr/nips
1
0
Fork 0
mirror of https://github.com/nostr-protocol/nips.git synced 2024-12-22 16:35:52 -05:00
Code Issues Actions Packages Projects Releases Wiki Activity

Move form spec to tags

Browse Source
This commit is contained in:
Abhay Raizada 2024-05-09 01:34:46 +05:30
parent 549f128bd3
commit 9dda0ad291
1 changed files with 44 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

101
101.md
View File

@ -1,88 +1,75 @@
# NIP-101 - Forms On Nostr
`draft` `optional` `author:abhay-raizada` `author:rramaa`
`draft` `optional` `author:abhay-raizada`
## Form Template
Form template is stored in a parameterized replaceable event of `kind: 30168`.
The event structure is:
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
```js
{
"kind": 30168,
"content" : "<Form Template as JSON>"
"tags": [["d", "<form identifier>"]],
"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>"
}
```
Content is a stringified JSON object with the following attributes:
|Attribute | Description |
|----------|-------------|
| name |name of the form|
| description | description of the form, may support markdown|
| schemaId | identifier for the schema that describes the structure of the fields and settings key of the form|
| fields |Client specific object holding the form structure: questions, metadata, optionally encrypted by a sha256 hash of a shared password, follows the schema as mentioned in the schemaId field|
| settings |Client specific object holding the settings for the form|
The different tags used to describe the form are described as:
Clients may wish to add additional keys depending on the use-case.
|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<table><tr><th>index</th><th>name</th><th>description</th></tr><tbody><tr><td>1</td><td>FieldId</td><td>an id that uniqely identifies a field in the forn</td></tr><tr><td>2</td><td>input-type</td><td>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`</td></tr><tr><td>3</td><td>label</td><td>A label for the field</td></tr><tr><td>4</td><td>options</td> <td>Only used for input-type option, is a Json stringified array of strings containing [`<OptionId`>, <`label`>, `<optional config>`] </td> </tr><tr><td>5</td><td>fieldSettings</td><td>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 </td></tr>
</tbody></table>
A list of schemaIds with the specification may optionally be collated in the table below:
## Sharing and Private forms.
| SchemaId | Link to the structure|
|----------|----------------------|
|formstrV1| https://github.com/abhay-raizada/nostr-forms/blob/master/packages/formstr-sdk/src/form-schemas/v1/form-spec.json
`<TBD>` similar to the sharing of spreadsheets as described in the proposed [NIP](https://github.com/nostr-protocol/nips/pull/1189).
Fields and settings maybe client specific, but a form is expected to have name, description and schema as part of the content JSON for interoperability.
### Sharing Links
Links would need to parameters from the users: the npub of the author and form identifier.
For example: `https://formstr.app/#f/<npub of author>/<form identifier>`
The form identifier is the d tag of the form template event.
### Groups
If a user wants to share a form with a group, they would need to create a shared user and share the private key of this user with their group.
### Private Forms
The fields key in the form template can be plain-text or encrypted using a symmetric key derived from a sha-256 hash of a password that can be shared with the participants. This would protect the form from being viewed by public querying of the relays. The password can be part of the shared url itself.
Example `https://formstr.app/#f/<npub of author>/<form identifier>?pwd=<password>`
## Responses
## 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:
```
```js
{
"kind": 30169,
"content" : "<Optionally encrypted response as JSON>",
"tags": [["a", "30168:<pubkey of the author>:<form identifier>"]],
"content" : "",
"tags": [["a", "30168:<pubkey of the author>:<form identifier>"],
["response", "<FieldId>", "<response as string>", "<stringified metadata object>"]],
"pubkey": "Author of Response"
}
```
Content is a stringified JSON, containing the following attributes:
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:
| Attribute | Description|
|-----------|------------|
|schema|describes the structure of the response key of the content
|response| Client specific object holding the response structure mapped to the form template|
|isPublic| a boolean field that identifies whether the response key is encrypted
```js
{
"kind": 30169,
"content" : "",
"tags": [["a", "30168:<pubkey of the author>:<form identifier>"],
["response", "<FieldId>", "ZCZC;XCZXCZ;Z34Z", "<stringified metadata object>"]],
"pubkey": "Response author"
}
```
The response key may optionally be encrypted with the author's private key using the specification mentioned in [nip-44 v2](./44.md)
## Responses - Private
A list of schemaIds with the specification may optionally be collated in the table below:
response tags are added to the ".content" field and encrypted as per the spec in [nip-44](./44.md)
| SchemaId | Link to the structure|
|----------|----------------------|
|formstrV1 | https://github.com/abhay-raizada/nostr-forms/blob/master/packages/formstr-sdk/src/form-schemas/v1/response-spec.json
### Polls
Polls is a use-case for forms where public responses are expected.