Skip to content
PaprikaPaprikaPaprika

Values

A template’s fields are its contract: the values a render, job or batch record sends are checked against them, and refused with every problem when they break it. The same rules hold in the editor’s preview.

The rules

Section titled “The rules”
  • Values are an object, each key a field of the template. A key that isn’t a field is refused (field-unknown).
  • A text field takes a string, used as sent: a newline starts a new line. It is at most 10,000 characters, or the field’s own limit if lower (value-too-long), and has no control characters other than newline and tab (value-characters).
  • A number field takes a JSON number, 2.8 and not "2.8", within its minimum and maximum (value-range) and with at most its decimals (value-type).
  • A choice field takes the value of one of its options, a string such as "FR" (value-type). The text shows the option’s label.
  • A switch field takes true or false (value-type).
  • An image field takes the id of an image in the template, or resource:<name>, an image you uploaded under that name (value-type).
  • A required field must be given (field-missing), and a text one must have more than spaces (value-empty).
  • A field left out takes its default. null is not a value: it’s refused (value-type).
  • All the values together are at most 100 KB as JSON.

A render, job or batch with values that break the rules is refused: 422 values-invalid, with every problem and the field it concerns (see below).

A version’s contract

Section titled “A version’s contract”

Each published version’s fields are a JSON Schema, for your code or your form builder:

Terminal window
curl -H "Authorization: Bearer $PAPRIKA_KEY" "$PAPRIKA_URL/v1/templates/tpl_9fK2mQ7rLx4VbN1s/versions/latest/schema"
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Conference badge",
  "type": "object",
  "properties": {
    "name": { "type": "string", "maxLength": 10000, "pattern": "\\S" },
    "role": { "type": "string", "maxLength": 10000, "pattern": "\\S" }
  },
  "required": ["name", "role"],
  "additionalProperties": false
}

A number field is a number (an integer without decimals) with its minimum, maximum and, with decimals, multipleOf (0.01 for two); a choice is a string enum of its options’ values, with a oneOf giving each its label as title; a switch is a boolean.

When the template sorts its fields into groups, each field in one has "x-paprika-group": "<id>", and the schema’s root lists the groups in their order, "x-paprika-groups": [{ "id": "offer", "label": "Offer" }]. Validators ignore both; a form builder can use them to show the fields in folders. The values themselves stay one flat object.

Check values first

Section titled “Check values first”

To check values without rendering, send them, the values object itself, to validate:

Terminal window
curl -H "Authorization: Bearer $PAPRIKA_KEY" -H "Content-Type: application/json" -d '{"name": "Grace Hopper", "role": "Keynote speaker", "extra": "x", "photo": null}' "$PAPRIKA_URL/v1/templates/tpl_9fK2mQ7rLx4VbN1s/versions/latest/validate"

It answers as a render would: {"valid": true}, or 422 with every problem:

{
  "code": "values-invalid",
  "message": "The values have 2 problems; see errors",
  "errors": [
    { "field": "extra", "code": "field-unknown", "message": "Unknown template field: extra" },
    {
      "field": "photo",
      "code": "value-type",
      "message": "photo must be the id of an image in the template, or resource:<name> of an uploaded one"
    }
  ],
  "requestId": "c8d04700"
}

Add ?layout=true to lay the document out too, and see the layout errors and warnings these values give (see Policy).