Skip to main content

Field labels to use in template files

The Document Assembly Line framework can help you automate templates that use any field (or variable) names that you choose. However, you should use the names that we list below for full compatibility.

Example documents​

The basics​

Fields, labels, and variables​

A blank space on a paper form is usually called a form field, or field for short. We call adding unique names that refer to those blank spaces labeling them.

When you access the labeled field in your Docassemble code, it is usually called a variable.

General rules for labels​

You should always use the specific labels from this page when they match the concepts in your form. But if you cannot find a matching label, use the general rules below to add as many custom labels as you need.

Labels should be valid Python variable names that start with a letter​

PDF and DOCX labels should also work as valid Python variable names. The basic rule is that Python variable names need to start with a letter and can only contain letters, digits, and the _ underscore character. Some variable names are reserved and have a special meaning inside AssemblyLine interviews. You should not use a variable name on the reserved list. Doing so can lead to hard to track bugs.

Variable names are case sensitive - make them all lowercase​

Field names are case sensitive. The convention is to never re-use variable names with different capitalizations to store different things. Stick with all lower case names for fields when possible.

Use the Python snake_case format for field labels​

In PDFs, labels should be all one word, lowercase, with multiple words separated by an underscore, the _ character. This convention is called snake_case. Do not use a . symbol or [] inside a PDF field's label.

In a DOCX file, you can use the . symbol as well as brackets [] but they have a special meaning. The . separates an object from its attribute, and the [] indicates that you are referencing a list of items. Beginners should avoid these symbols except when instructed to do so for one of the variable names below.

Use short but descriptive labels​

Use variable names that are descriptive but also short. Avoid using abbreviations. A good rule of thumb is to spell out acronyms and initialisms for clarity, but to freely remove words other than nouns and verbs to keep the names short. Use a name you would still understand if you read it in a year.

About 30 characters is a good limit to the length of a variable name. It's unusual to need more than that. If your variable name is shorter than 5 characters, it might not be descriptive enough.

Some suggestions for coming up with custom labels​

There are no hard and fast rules other than the ones listed above, but here are some conventions that may help you:

  1. Drop words from the variable name that don't add specific meaning. Filler words like "a", "the", etc. are almost never needed. Stick with nouns and verbs.
  2. Yes/no variables (also called boolean) commonly start with a form of the verb "to be" or "to have", paired with a noun. E.g., is_attorney or has_notice_to_quit. You can also use other verbs--writes_docassemble or saved_status or wants_copies_returned.
  3. Do not include the type of variable in the variable name itself. It is usually redundant and is not a common Python style. Exception: you might add something like _list or _date that is both a type and is descriptive of the variable's real world contents.
  4. There are now a number of samples of interviews built with the Assembly Line framework that you can find online. You can get ideas for variable names to use in your interview that match if they apply to the same concepts.

When you're stuck, feel free to ask for help! It's a good idea to get a second opinion the first few times you label a document. A fellow programmer may have some good ideas to make your variable names shorter, clearer, or more closely follow programming conventions.

How the Assembly Line labels work​

We have identified common fields that exist in most paper court forms:

  • names of people
  • addresses
  • information that identifies the court
  • signatures
  • dates
  • currency figures
  • a pair of yes/no checkboxes
  • docket numbers or court filing numbers

We came up with a convention to identify the roles that people may play in relation to your form:

  • The "user" of the form: the person who the form is being filed for, making a request or response to the court
  • The "other_party" of the form: the person who the user is responding to or suing

We have also identified some common names for people that appear across many forms.

By using the labels for fields that we selected, you will be able to use the questions that we have vetted and pre-written without needing to write them from scratch. You still have the option to customize those questions later.

A note about objects

For those with programming experience, we turn most of the field labels that we recognize into objects. Learn more about the Individual object in the Docassemble documentation.

Special names for special roles: users and other_parties​

Where possible, you should use the label users for the person who the interview is benefiting and other_parties for the person that is on the other side of their dispute. Sometimes this is not known. In that situation, you can use the labels plaintiffs and defendants or petitioners and respondents.

info

The term users does not always mean the person sitting in front of the screen. We use the term "user" to mean the person who the form is for. I.e., it should usually not be used to identify an attorney or advocate filling in a form for someone else. In a court case, the user should normally be a party to the case.

People are "plural" by default​

We made the choice to make all variables representing people plural by default. This allows us to use consistent terms across the many forms that do allow multiple parties in different roles.

Special situation for names of people in PDFs​

In PDF forms, you can identify a single person's name like this:

users1, users2. This is due to a limit in how PDF labels work.

When the form is automated in the Weaver, the field name becomes part of a list: users. There is also a special syntax that lets you indicate which item in the list you are accessing, with the first item starting at 0: users[0] represents the first user, users[1] the second, and so on.

The Docassemble and DOCX variable name users[0] is the equivalent of users or users1 in a PDF label. users[1] is the equivalent of user2.

Names are not transformed at all when you work in a DOCX template. You need to use the Docassemble syntax from the beginning if you are identifying a specific person in a list.

Labels for people, places, and things​

Labels for people's names​

  • users (Always use this for the person benefiting from the form)
  • other_parties (Always use this for the opposing party)
  • plaintiffs
  • defendants
  • petitioners
  • respondents
  • children
  • spouses
  • parents
  • caregivers
  • attorneys
  • translators
  • debt_collectors
  • creditors
  • witnesses
  • guardians_ad_litem
  • guardians
  • decedents
  • interested_parties
Historical note

When the Assembly Line Project first began, we used singular names for people that were then automatically turned into plural names. Like: user became users. This feature still works but is confusing now that we automate both PDF forms and DOCX templates. We do not recommend using it any longer.

Custom names​

You can add your own custom names for people to represent concepts that are not listed above. Just use them in a way that matches specific information about the person below--like custom_name, custom_name_first, etc. and the Weaver tool will prompt you to decide if they should be treated as like people in the automation process.

Different forms of someone's name​

Substitute the name users with any of the names listed above.

PDF variationDocassemble / DOCX formMeaning
users1_name or users1_name_fullusers[0] or users[0].name.full()Full name
users1_name_firstusers[0].name.first or users[0].familiar()First name only
users1_name_middleusers[0].name.middleMiddle name only
users1_name_middle_initialusers[0].name.middle_initial()First letter of middle name
users1_name_lastusers[0].name.lastLast name only
users1_name_suffixusers[0].name.suffixSuffix of user's name only
note

If the form has only one "user", "plaintiff", etc., it is not necessary to use a digit. You can just write users_name, for example.

Listing all parties at once​

In a DOCX file, writing out users will list all of the users added to the form, separated by a comma. Writing users.familiar() will list all of the first names of each user separated by a comma.

This works for any Docassemble list.

Demographic data for people​

Substitute any name for a person for users below.

PDF variationDocassemble / DOCX formMeaning
users1_birthdateusers[0].birthdateBirthdate (formatted like January 1, 2021 by default)
users1_ageusers[0].age_in_years()Calculated age (based on birthdate)
users1_genderusers[0].genderGender
users1_gender_femaleusers[0].gender_femaleUser is female (for checkbox field)
users1_gender_maleusers[0].gender_maleUser is male (for checkbox field)
users1_gender_otherusers[0].gender_otherUser is not male or female (for checkbox field)
users1_gender_nonbinaryusers[0].gender_nonbinaryUser identifies as nonbinary (for checkbox field)
users1_gender_undisclosedusers[0].gender_undisclosedUser chose not to disclose gender (for checkbox field)
users1_gender_self_describedusers[0].gender_self_describedUser chose to self-describe gender (for checkbox field)
user_needs_interpreteruser_needs_interpreterUser needs an interpreter (for checkbox field)
user_preferred_languageuser_preferred_languageUser's preferred language

Addresses​

Substitute any name for a person for users below.

PDF variationDocassemble / DOCX formMeaning
users1_address_blockusers[0].address.block()Full address, on multiple lines
users1_address_on_one_lineusers[0].address.on_one_line()Full address on one line
users1_address_line_oneusers[0].address.line_one()Line one of the address, including unit or apartment number
users1_address_line_twousers[0].address.line_two()Line two of the address, usually city, state, and Zip/postal code
users1_address_addressusers[0].address.addressStreet address
users1_address_unitusers[0].address.unitApartment, unit, or suite
users1_address_cityusers[0].address.cityCity or town
users1_address_stateusers[0].address.stateState, province, or sub-locality (dependent on country)
users1_address_zipusers[0].address.zipZip or postal code
users1_address_countyusers[0].address.countyCounty or parish
users1_address_countryusers[0].address.countryCountry
Mailing addresses

The Assembly Line framework also supports mailing addresses. Replace address with mailing_address to ask a separate question about the user's mailing address.

Other contact information​

Substitute any name for a person for users below.

PDF variationDocassemble / DOCX formMeaning
users1_phone_numberusers[0].phone_numberPhone number
users1_mobile_numberusers[0].mobile_numberA phone number explicitly labeled as the "mobile" number
users1_phonesusers[0].phone_numbers()A list of both mobile and other phone numbers
users1_emailusers[0].emailEmail

Signatures​

Substitute any name for a person for users below.

PDF variationDocassemble / DOCX formMeaning
users1_signatureusers[0].signatureSignature
signature_datesignature_dateDate the form is completed (automatically filled in by default)

Information about court and court processes​

PDF variationDocassemble / DOCX formMeaning
trial_courttrial_courtCourt's full name, like: "Eastern Housing Court"
trial_court_countytrial_court.address.countyCounty where court is located
trial_court_divisiontrial_court.divisionDivision of court (e.g., "Eastern")
trial_court_departmenttrial_court.departmentDepartment of court (e.g., "Housing Court")
docket_numberdocket_numberCase or docket number
docket_numbersdocket_numbersA comma-separated list of docket numbers (rare but used in some family law cases)

Special endings to mark data types​

Usually, it is not recommended to mark the type of fields in Docassemble. There are a few exceptions that both mark type and carry a separate meaning that the Weaver will recognize.

Indicating paired yes/no checkboxes​

The Weaver turns paired yes/no checkboxes into a single Docassemble variable.

Use any valid keyword to replace is_minor in the example below.

PDF variationDocassemble / DOCX formMeaning
is_minor_yes, is_minor_nois_minorIndicates the user is a minor

Marking dates​

Marking dates is optional. If you do mark a field with the _date suffix, the Weaver will automatically recognize it as a date.

Replace firm_founding with any valid keyword in the example below.

PDF variationDocassemble / DOCX formMeaning
firm_founding_datefirm_founding_dateWill be recognized as a date field by the Weaver.

Marking currency figures​

Marking currency values is optional. If you do mark a field with _amount or _value, the Weaver will automatically recognize it as a currency amount.

Replace expense_rent or house with any valid keyword in the example below.

PDF variationDocassemble / DOCX formMeaning
expense_rent_amountexpense_rent_amountWill be recognized as a currency value by the Weaver.
house_valuehouse_valueWill be recognized as a currency value by the Weaver.

Dealing with PDF limitations - adding the same field twice​

Docassemble does not work with PDF forms that use the same label for a field twice.

To work around this issue, annotate the second or third field with two underscores and any digit, like this: __1.

Replace users1_name with any other valid field name in the example below.

PDF variationDocassemble / DOCX formMeaning
users1_name__1users[0]Allows you to label two fields in the PDF to contain the user's name.
user1_name__2users[0]Same as above

DOCX files do not have any limit on using the same variable name twice. This special syntax only applies to PDF templates.

Use any digit

Docassemble does not do anything with the digit. Feel free to use __1, __99 or any other series of digits, in any order.

Remember, you will always have a chance to fix things later​

Do your best to get your template right before running it through the Weaver. Getting things right at the beginning can save you a lot of time and effort.

However, you can always edit your template later. When you make changes to your template, you do not need to run it through the Weaver again. You can upload your edited template directly to the Docassemble playground's templates folder.

See also​