# NIP-101 - Forms On Nostr

`draft` `optional` `author:abhay-raizada` `author:rramaa`

## Form Template

Form template is stored in a parameterized replaceable event of `kind: 30168`.
The event structure is:

```
{
    "kind": 30168,
    "content" : "<Form Template as JSON>"
    "tags": [["d", "<form identifier>"]],
    "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|

Clients may wish to add additional keys depending on the use-case.

A list of schemaIds with the specification may optionally be collated in the table below:

| 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 

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

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" : "<Optionally encrypted response as JSON>",
    "tags": [["a", "30168:<pubkey of the author>:<form identifier>"]],
    "pubkey": "Author of Response"
}
```

Content is a stringified JSON, containing the following attributes:

| 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

The response key may optionally be encrypted with the author's private key using the specification mentioned in [nip-44 v2](./44.md)

A list of schemaIds with the specification may optionally be collated in the table below:

| 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.