# Form response check

`form-response-check` · version 1.0.0 · Forms · free, no key needed

Report missing required answers, nulls, type failures, and choice failures.

**Use when you need to: check form completeness · check form answers.**

## Supported

- check form completeness
- check form answers

## Not supported

- general json schema
- fuzzy answers
- medical or legal judgment
- inferred defaults

## Behavior

- Provide exactly one of answers or responses. The definition is the only accepted shape.
- required means the key is present and the value matches the type. An empty string or empty multi-select satisfies it.
- JSON null is never valid. Optional absence is counted and is not an issue.
- Issue codes are missing_required, null_not_allowed, type_mismatch, choice_not_allowed, and duplicate_multi.
- Unknown answer keys are listed. complete is true only when issues and unknown keys are both empty.
- The field counts partition every defined field exactly once.

## Input

- `definition` (object, required)
- `answers` (object, optional)
- `responses` (array of object, optional)

## Output

- `mode` (one of "answers", "responses", required)
- `complete` (boolean, optional)
- `issues` (array of any, optional)
- `unknown_fields` (array of any, optional)
- `respondents` (array of any, optional)
- `counts` (object, required)

## Limits

- max input bytes: 262144
- max output bytes: 262144
- max input depth: 16
- max input nodes: 20000
- max fields: 100
- max choices: 50
- max respondents: 100
- max id bytes: 128
- max label bytes: 256
- max choice bytes: 128
- max answer string bytes: 4096
- max answer depth: 6
- max answer nodes: 50
- max changes: 500
- max mapping: 100

## Example

Request input:

```json
{
  "definition": {
    "fields": [
      {
        "id": "email",
        "label": "Email",
        "type": "string",
        "required": true
      },
      {
        "id": "nickname",
        "label": "Nickname",
        "type": "string",
        "required": false
      }
    ]
  },
  "answers": {
    "nickname": ""
  }
}
```

Response:

```json
{
  "result": {
    "mode": "answers",
    "complete": false,
    "issues": [
      {
        "field_id": "email",
        "code": "missing_required"
      }
    ],
    "unknown_fields": [],
    "counts": {
      "fields": 2,
      "valid": 1,
      "missing_required": 1,
      "missing_optional": 0,
      "null_not_allowed": 0,
      "type_mismatch": 0,
      "choice_not_allowed": 0,
      "duplicate_multi": 0,
      "unknown_fields": 0,
      "empty": 1
    }
  }
}
```

## How to call it

### MCP

Connect `https://computefirst.net/mcp` ([setup](/docs#connect)), then call `execute` with:

```json
{
  "id": "form-response-check",
  "version": "1.0.0",
  "input": {
    "definition": {
      "fields": [
        {
          "id": "email",
          "label": "Email",
          "type": "string",
          "required": true
        },
        {
          "id": "nickname",
          "label": "Nickname",
          "type": "string",
          "required": false
        }
      ]
    },
    "answers": {
      "nickname": ""
    }
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/form-response-check/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"definition":{"fields":[{"id":"email","label":"Email","type":"string","required":true},{"id":"nickname","label":"Nickname","type":"string","required":false}]},"answers":{"nickname":""}}'
```

The machine-readable contract is at [/v1/tools/form-response-check/versions/1.0.0](/v1/tools/form-response-check/versions/1.0.0).

### CLI

```sh
node cli.mjs run form-response-check 1.0.0 --input input.json --base-url https://computefirst.net
```

Get the client at [/clients/cli/](/clients/cli/).

## Related tools

- [Form answer diff](/tools/form-answer-diff): Diff two answer maps against one shared form definition.
- [Form response diff](/tools/form-response-diff): Reconcile two form response sets by exact respondent id.
- [Form compare](/tools/form-compare): Compare two filled form snapshots and return compact field and answer changes.
- [Form definition diff](/tools/form-definition-diff): Diff two form definitions by stable field id, including choice lists and field order.
- [Form field map](/tools/form-field-map): Rename form fields with an explicit id map and reject collisions.