A field of a template: the name of a value in submission data, and how and where it prints. Fields with the same name share one value and the settings the descriptions say are shared. A PDF template's fields are placed on its pages: x, y, width and height are in units where every page is 2480 wide, measured from the top-left corner of the field's page. To convert from PDF points, multiply by 2480 and divide by the page's width in points (document.page_dimensions on the template). An HTML or Word template's fields are all on page 1, and their placement and style settings aren't used: its HTML or Word document places and styles each value.
| Name | Type | Description | Notes |
|---|---|---|---|
| id | int | The field's ID, an integer that's unique within the template. | |
| name | str | The field's name, the key of its value in submission data. A / nests the key in objects and arrays (client/address, items/0/price); write a literal / as ~1 and ~ as ~0. Fields with the same name share one value and their shared settings, and array indexes inside a name are ignored for settings, so items/0/price and items/1/price share settings but not values. A # and a line number (notes#0, notes#1) splits one value over several fields as lines of text, and names that start with @@ print submission details such as @@date. |
|
| page | int | The number of the page the field is on, starting at 1. A field added without one goes on page 1, and a field moved to another page without a new y keeps its place on the page. |
|
| acroform_name | str | The name of the PDF form field this field was made from, when the template's PDF had fillable fields. Null for fields added in DocSpring. | |
| type | FieldType | The data type of the field's value: string, number, boolean, date, address, country, email, url, image, signature, initials, barcode, or combined (made from other fields' values, never sent in submission data). It sets how the value is validated and which display_types the field can use. object and array are the types of field groups (the template's field_groups), not of fields. Shared by every field with the same name. |
|
| static | bool | The field prints fixed content, its default, instead of a value from submission data, and it's left out of the template's data schema and forms. Static check marks and shapes always print unless hidden, and a static number field's default can be a formula. Shared by every field with the same name. |
|
| editable | bool | Text and check display only: prints the field as a fillable PDF form field instead of flat content (a text field with an option_list becomes a dropdown). A submission's editable option, when set, overrides this for every field. Shared by every field with the same name. |
|
| default | str | The value used when a submission leaves the field out, and the value forms are pre-filled with. A required field still needs a value in each submission. An image field's default is an image URL, a number field's can be a formula, and a static field's is the content it prints. Shared by every field with the same name. |
|
| title | str | The field's title in the template's data schema and on forms. When it's empty, a title is made from the field's name. Shared by every field with the same name. |
|
| description | str | Help text for the field, added to the template's data schema and shown on forms. Shared by every field with the same name. |
|
| placeholder | str | Placeholder text for the field's input on forms, added to the template's data schema as x-placeholder. Shared by every field with the same name. |
|
| metadata | str | Text for your own use, added to the template's data schema as x-metadata. DocSpring doesn't use it. Shared by every field with the same name. |
|
| required | bool | Whether each submission must include a value for the field. A submission without one fails validation, and no PDF is generated. Shared by every field with the same name. |
|
| option_list | str | String fields only: a comma-separated list of the values the field accepts. It's added to the template's data schema as an enum, forms show it as a select list, and an editable field becomes a dropdown. Shared by every field with the same name. |
|
| combined_field_names | str | Combined fields only: a comma-separated list of the names of the fields whose values are combined, in order. Shared by every field with the same name. |
|
| combined_field_type | CombinedFieldType | Combined fields only: separator joins the values with combined_field_separator, and format puts them into combined_field_format. Shared by every field with the same name. |
|
| combined_field_separator | str | Combined fields only: the text placed between the values when combined_field_type is separator. Empty values are skipped. Defaults to a space. Shared by every field with the same name. |
|
| combined_field_format | str | Combined fields only: the text for combined_field_type format, where $0, $1 and so on are replaced with the values of combined_field_names in order, such as Full name: $0, Occupation: $1. Shared by every field with the same name. |
|
| integer | bool | Number fields only: the value must be a whole number. Shared by every field with the same name. |
|
| minimum | float | Number fields only: the smallest value allowed. Shared by every field with the same name. |
|
| maximum | float | Number fields only: the largest value allowed. Shared by every field with the same name. |
|
| exclusive_minimum | bool | Number fields only: the value must be greater than minimum, not equal to it. Shared by every field with the same name. |
|
| exclusive_maximum | bool | Number fields only: the value must be less than maximum, not equal to it. Shared by every field with the same name. |
|
| include_time | bool | Date fields only: the value is a date and time (YYYY-MM-DDThh:mm:ss.fffZ) instead of a date (YYYY-MM-DD), and it prints with the template's date-time format unless date_time_format is set. Shared by every field with the same name. |
|
| signature_allow_draw | bool | Signature and initials fields only: lets signers draw their signature on forms and in data requests. Shared by every field with the same name. |
|
| signature_allow_type | bool | Signature and initials fields only: lets signers type their name and choose a script font instead of drawing, on forms and in data requests. Shared by every field with the same name. |
|
| barcode_symbology | BarcodeSymbology | Barcode fields only: the barcode format, which the value must match. code_128 and pdf417 take any ASCII text; code_39 and code_93 take capital letters, digits, spaces and - . $ / + %; code_25 takes digits; ean_13 takes 12 digits, ean_8 7 digits and upc_a 11 digits (the check digit is added). Shared by every field with the same name. |
|
| hidden | bool | Leaves the field off the PDF. It stays in the template's data schema (marked x-hidden) and on forms, so other fields, such as combined fields, can use its value. A hidden static check mark or shape isn't printed. |
|
| x | float | The distance from the page's left edge to the field's left edge. Positions and sizes are in units where every page is 2480 wide: one unit is the page's width in points divided by 2480 (about 0.247 points on a US Letter page). | |
| y | float | The distance from the top edge of the field's page down to the field's top edge, in the units of x. A page is 2480 times its height divided by its width units tall: about 3209 for US Letter and 3508 for A4. |
|
| width | float | The field's width, in the units of x. A check mark is sized to the field's width. |
|
| height | float | The field's height, in the units of x. The template editor keeps check marks, QR codes, and square and circle shapes square, with height equal to width. |
|
| rotation | float | Rotates the field clockwise by this many degrees, from -360 to 360 (negative turns it counterclockwise). | |
| display_type | FieldDisplayType | How the value appears on the PDF: text, check (a check mark), shape, qrcode, barcode, or image (image, signature and initials fields). Check marks and shapes print only when the value meets the field's condition, and the field's type limits which display types it can use. |
|
| opacity | float | The opacity of the field's content and background, from 0 (invisible) to 1. QR codes and barcodes always print at full opacity. | |
| date_time_format | str | Date fields only: how the date prints, as a strftime format such as %m/%d/%Y, or a calculation such as @years_since, @years_until or @diff_years (also months, weeks, days, hours, minutes and seconds), counted to when the PDF is generated. Empty uses the template's date format, or its date-time format with include_time. |
|
| typeface | Typeface | Text display only: the font, one of Helvetica, Arial, Calibri, Open Sans, Roboto, Lato, Poppins, Public Sans, Questrial, Times New Roman, Dancing Script, Lovtony Script, or the monospace Courier, Inconsolata, Menlo, Roboto Mono and Ubuntu Mono. Empty uses the template's default typeface. |
|
| font_size | int | Text display only: the font size in points. Empty uses the template's default font size. | |
| character_spacing | float | Text display only: extra space between characters, in points. Empty uses the template's default. | |
| bold | bool | Text display only: prints the text in bold. | |
| uppercase | bool | Text display only: prints the text in capital letters. | |
| strikethrough | bool | Text display only: draws a line through the text. | |
| keep_leading_spaces | bool | Text display only: keeps the spaces at the start of the text and of each line, so text can be lined up with spaces. | |
| overflow | TextOverflow | Text display only: what happens to text that doesn't fit the field. shrink_to_fit makes the font smaller, down to 5 points; truncate cuts the text off and returns the rest in the submission's truncated_text. |
|
| multiline | bool | Text display only: wraps the text over as many lines as fit in the field's height instead of printing one line, and forms show a multi-line input. | |
| multiline_lines | int | Text display only, with multiline: spreads the text over exactly this many evenly spaced lines in the field's height (up to 300), to line up with lines printed on the form. Empty uses the font's normal line spacing. |
|
| min_length | float | Text display only: the fewest characters the value can have, added to the template's data schema. Not used for date, address, country or number fields, or fields with an option_list. |
|
| max_length | int | Text display only: the most characters the value can have, added to the template's data schema; it also limits an editable field. Not used for date, address, country or number fields, or fields with an option_list. |
|
| auto_calculate_max_length | bool | Text display only, with a monospace typeface (Courier, Inconsolata, Menlo, Roboto Mono or Ubuntu Mono): adds the number of characters that fit in the field to the template's data schema as its maximum length. |
|
| color | str | Text display only: the text color, as a hex code such as 444444. Empty uses the template's default text color. |
|
| color_field_name | str | Text display only: the name of a data field whose value, a hex code such as FF0000, sets the text color for each submission. That field is added to the template's data schema, with color as its default. |
|
| color_field_required | bool | Makes the color_field_name field required. When it isn't required and a submission leaves it out, color is used. |
|
| background_color | str | Text and check display only: a color that fills the field's area behind its content, as a hex code, to cover what the page shows there. Check fields print it even when unchecked; text fields print it only when they have a value. | |
| background_color_field_name | str | Text and check display only: the name of a data field whose value, a hex code, sets the background color for each submission. That field is added to the template's data schema, with background_color as its default. |
|
| background_color_field_required | bool | Makes the background_color_field_name field required. When it isn't required and a submission leaves it out, background_color is used. |
|
| alignment | TextAlignment | Text display only: how the text is aligned across the field: left, center, right or justify (both edges of every line of multiline text except the last of each paragraph). |
|
| v_alignment | TextVerticalAlignment | Text display only: how the text is aligned vertically in the field: bottom, center or top. |
|
| comb | bool | Text display only: splits the field into comb_number_of_cells boxes of equal width and prints one character, centered, in each. |
|
| comb_number_of_cells | int | With comb: how many boxes the field has. The value's maximum length in the template's data schema is this plus comb_value_offset. |
|
| comb_value_offset | int | With comb: the position, from 0, of the first character of the value that this field prints. For an SSN printed in boxes of 3, 2 and 4 digits, three fields named ssn use offsets 0, 3 and 5. |
|
| shape_type | ShapeType | Shape display only: square, rectangle, circle, ellipse, triangle or polygon. A square or circle uses the smaller of width and height. |
|
| shape_sides | int | Shape display only, with shape_type polygon: the number of sides, 3 to 12. |
|
| shape_border_width | int | Shape display only: the width of the shape's border, in points. | |
| shape_border_color | str | Shape display only: the shape's border color, as a hex code. Null draws no border. | |
| shape_border_color_field_name | str | Shape display only: the name of a data field whose value, a hex code, sets the border color for each submission. That field is added to the template's data schema, with shape_border_color as its default. |
|
| shape_border_color_field_required | bool | Makes the shape_border_color_field_name field required. When it isn't required and a submission leaves it out, shape_border_color is used. |
|
| shape_fill_color | str | Shape display only: the color that fills the shape, as a hex code. Null leaves it unfilled. | |
| shape_fill_color_field_name | str | Shape display only: the name of a data field whose value, a hex code, sets the fill color for each submission. That field is added to the template's data schema, with shape_fill_color as its default. |
|
| shape_fill_color_field_required | bool | Makes the shape_fill_color_field_name field required. When it isn't required and a submission leaves it out, shape_fill_color is used. |
|
| check_character | CheckCharacter | Check display only: the character printed, as an HTML entity: ✓ (✓), ✔ (✔, the default), ✖ (✖), ✗ (✗) or ✘ (✘). |
|
| check_color | str | Check display only: the check mark's color, as a hex code. Empty uses the template's default check color. | |
| check_color_field_name | str | Check display only: the name of a data field whose value, a hex code, sets the check mark's color for each submission. That field is added to the template's data schema, with check_color as its default. |
|
| check_color_field_required | bool | Makes the check_color_field_name field required. When it isn't required and a submission leaves it out, check_color is used. |
|
| qrcode_color | str | QR code display only: the QR code's color, as a hex code, printed on a white background. Empty prints it in black. | |
| qrcode_color_field_name | str | QR code display only: the name of a data field whose value, a hex code, sets the QR code's color for each submission. That field is added to the template's data schema, with qrcode_color as its default. |
|
| qrcode_color_field_required | bool | Makes the qrcode_color_field_name field required. When it isn't required and a submission leaves it out, qrcode_color is used. |
|
| true_text | str | Boolean fields with text display: the text printed when the value is true. Empty uses the template's true_text; when neither is set, nothing prints. |
|
| false_text | str | Boolean fields with text display: the text printed when the value is false. Empty uses the template's false_text; when neither is set, nothing prints. |
|
| condition | str | Check and shape display only: the value a string or number field's value is compared with, by string_condition_type or number_condition_type, to decide whether the check mark or shape prints. Boolean fields print when true (see invert_boolean_condition), and other types print when they have a value. |
|
| string_condition_type | StringConditionType | String fields with check or shape display: how the value is compared with condition: equals, contains, starts_with, ends_with, or regex, where condition is a regular expression (RE2 syntax) the value must match; each has a not_ form that prints when it doesn't match (not_equals, not_regex, ...). blank prints when the value is empty or only spaces and line breaks, and not_blank when it isn't; they ignore condition. |
|
| number_condition_type | NumberConditionType | Number fields with check or shape display: how the value is compared with condition: equals, gt (greater than), gte (greater than or equal to), lt (less than), lte (less than or equal to), or range, between number_condition_range_min and number_condition_range_max. |
|
| number_condition_range_min | float | With number_condition_type range: the lower end of the range, included unless number_condition_range_exclusive_min is set. |
|
| number_condition_range_max | float | With number_condition_type range: the upper end of the range, included unless number_condition_range_exclusive_max is set. |
|
| number_condition_range_exclusive_min | bool | With number_condition_type range: leaves number_condition_range_min itself out of the range. |
|
| number_condition_range_exclusive_max | bool | With number_condition_type range: leaves number_condition_range_max itself out of the range. |
|
| invert_boolean_condition | bool | Boolean fields with check or shape display: prints the check mark or shape when the value is false or missing, instead of true. |
|
| currency | bool | Number fields only: forms show a currency input, and the template's data schema gives the field format: currency. It doesn't change how the number prints. |
|
| decimal_places | int | Number fields with text display: prints the number with this many decimal places, from 0 (rounds to a whole number) to 99. Empty prints the number as it was sent. | |
| image_scale_type | ImageScaleType | Image fields only: how the image is resized to the field. fit keeps its proportions and fits it inside the field, which can leave empty space; fill keeps its proportions and crops it to fill the field; stretch stretches it to the field's size. Signatures and initials always fit. |
|
| image_gravity | ImageGravity | Image, signature and initials fields: where the image sits in the field with fit, or which part is kept with fill: NorthWest (top left), North, NorthEast, West, Center, East, SouthWest, South or SouthEast (bottom right). It also aligns typed signatures, and isn't used with stretch. |
|
| dependencies | FieldDependency | The field's own conditional logic rule: when other fields' values meet its conditions, the field is shown, made required, or both. Null when it has none. The template's rules (field_dependencies) can apply to the field too. Shared by every field with the same name. |
from docspring.models.model_field import ModelField # TODO update the JSON string below json = "{}" # create an instance of ModelField from a JSON string model_field_instance = ModelField.from_json(json) # print the JSON string representation of the object print(ModelField.to_json()) # convert the object into a dict model_field_dict = model_field_instance.to_dict() # create an instance of ModelField from a dict model_field_from_dict = ModelField.from_dict(model_field_dict)