Input validation

The rules you can set for an input (required, default, minimum, maximum, allowed values), how a value is checked before the workbook calculates, and what a caller receives when a value is refused.

Why validate

Every value a caller sends is checked before it reaches the workbook. A value that breaks a rule is refused with a clear message, and no calculation takes place. Your model therefore only ever calculates with values it was built for, and callers learn at once what to correct.

The rules

You set the rules in the dialog of an input: hover over the input in the panel on the Configuration (Konfiguration) tab and click the pencil, or see Add inputs for a new one.

After changing a rule, click Update Parameter (Parameter aktualisieren), then Save (Speichern), and publish again. Until then callers are checked against the published rules.

Required and optional

A new input is required. A call that leaves it out, or sends it empty, is refused with "Missing required parameters". The answer names every missing input.

To make an input optional, untick Mandatory parameter. The field Default Value (Optional) appears, filled with the value the cell has in the workbook.

• With a default, a call without the input calculates with the default.
• If you clear the default, the cell is empty for a call without the input. Make sure your formulas give a sensible result for an empty cell.
• A default must itself pass the rules. If you set allowed values, the dialog only accepts a default from that list: Default value must be one of: …

Minimum and maximum

Min Value and Max Value appear for inputs of the type Number. Both limits are inclusive: with a minimum of 0 and a maximum of 100, the values 0 and 100 are accepted. You can set one of them, both or neither.

For a percentage input the limits are decimals: a maximum of 1 means 100%. A new percentage input gets a minimum of 0 and a maximum of 1 as a suggestion; see Percentages and formats.

Allowed values

Allowed Values (Optional) restricts an input to a fixed list, for example Basic, Pro, Enterprise. Type a value and press Enter or a comma to add it. Leave the field empty to allow any value.

• From a drop-down list. If the cell has a drop-down list in the workbook, its entries are filled in when you add the input, with the note Auto-detected from cell dropdown.
• From a range. Click Advanced (Erweitert) next to the label and enter a range under Or Load from Worksheet Range, for example Values!B2:B24. The values of that range are read each time you publish, so the list follows the workbook. Empty cells and duplicates are left out.
• Upper and lower case. For text, pro and Pro count as the same value. Tick Case-sensitive matching (Groß-/Kleinschreibung beachten) if they must match exactly.
• Numbers. For a number input the list holds numbers, for example 12, 24, 36.

How a call is checked

1. Required inputs. If one or more required inputs are missing or empty, the call is refused. The answer lists all of them.
2. Each value sent. Every value is checked against its input: data type first, then minimum and maximum, then allowed values. If one or more values fail, the call is refused. The answer lists every failed value.
3. Defaults. Optional inputs that were not sent take their default.
4. Calculation. Only now are the values written into the workbook.

An optional input that is sent empty counts as not sent. A key that matches no input of the service is ignored.

What a caller receives when a value is refused

The API answers with HTTP status 400 and a JSON body. error names the kind of problem, message says it in a sentence, and details lists each input concerned.

A missing required input:

{
  "error": "Missing required parameters",
  "message": "The following required parameters are missing: Loan amount",
  "details": {
    "required": [ { "name": "loan_amount", "title": "Loan amount" } ]
  }
}

A refused value:

{
  "error": "Parameter validation failed",
  "message": "1 parameter(s) failed validation",
  "details": {
    "errors": [
      {
        "name": "years",
        "title": "Years",
        "parameter": "Years",
        "type": "above_maximum",
        "error": "Value 45 is above maximum 40",
        "max": 40,
        "value": 45
      }
    ]
  }
}

The answer also repeats the serviceId and the inputs that were sent.

How to read and fix these answers as a caller is described in Input errors. All errors of the API are listed in the Error reference.

The same checks apply to every way of using the service: the API, AI assistants, web apps, automation tools and the Excel export for callers. An AI assistant receives the message and corrects its call.

For developers and agents

• Status 400; details.required is a list of { name, title }, details.errors a list of objects with name, title, parameter (the title), type, error and the extra fields above.
• name is the key to send. Use it to map an error back to your request.
• All missing inputs are reported together, and all failed values are reported together. Missing inputs are reported first; fix them and call again to see value errors.
• Minimum and maximum are inclusive.
• Allowed values for text are compared without regard to case unless the input is case-sensitive; surrounding spaces are ignored.
• Before calling, an agent can read each input's rules (required, minimum, maximum, allowed values, default) from the service's definition; see The discovery address.

FAQ

How do I make an input required?

Open the input with the pencil and tick Mandatory parameter. New inputs are required already. Save and publish again.

How do I set a minimum or maximum for an input?

Open the input, make sure Data Type is Number, and fill in Min Value and Max Value. Both limits are inclusive.

How do I restrict an input to a list of values?

Open the input and enter the values under Allowed Values (Optional). A cell with a drop-down list in the workbook gets its entries filled in when you add it as an input.

Can the allowed values come from a range in my workbook?

Yes. Click Advanced next to Allowed Values and enter the range, for example Values!B2:B24. The values are read each time you publish.

What does a caller get when a value is not allowed?

HTTP status 400 with "error": "Parameter validation failed" and, under details.errors, one entry per refused value with its name, the reason and the limit or list it broke. Nothing is calculated.

How do I set a default value for an input?

Open the input, untick Mandatory parameter and fill in Default Value (Optional). Only optional inputs have a default; it is used whenever a caller does not send the input.

Is "pro" accepted when the allowed value is "Pro"?

Yes, unless you ticked Case-sensitive matching for that input. Then only the exact spelling is accepted.

I changed a rule but callers are still checked the old way. Why?

Rules belong to the draft until you publish. Click Save, then Republish.

Are values checked in the web app and for AI assistants too?

Yes. The same rules apply to every way of using the service. An AI assistant receives the reason and corrects its values.

Can I validate with a formula, for example "end date after start date"?

The rules of an input check one value at a time. For a rule across several inputs, calculate it in the workbook and return it as an output, for example =IF(B2>B1,"OK","End date must be after start date").

As an agent, how do I avoid a refused call?

Read the inputs of the service first: each lists whether it is required, its type, minimum, maximum, allowed values and default. Send every required input by its name and keep values within those rules.