Skip to main content
Skip table of contents

VA Forms Library Overview

Welcome!

You have found your way to the home of the VA Forms Library, where forms are created and enhanced for our customers across the country.

This is technical documentation meant to serve as a reference for software engineers working on the platform. If you don’t find what you are looking for, please submit a request for new or updated documentation via this documentation request form.

If you're interested in reading more about the initial process of moving a paper form online, and the content design behind it, check out A Guide to Digitizing VA Forms or Forms - VA.gov Design System.

If you are looking for information about the VA Forms System Core (VAFSC - the next generation version of the Forms Library), details about the current development status of the package can be found on the VA Forms System Core Docs page.

What is the VA Forms Library?

The VA Forms Library is a comprehensive system that provides an easy to use and consistent way of creating complex forms for Veterans. Applications using forms that are created with the Forms Library are created with this general flow:

Introduction Page → Form Pages Start → Form Pages → Review Page → Submission → Confirmation Page

The Forms Library consists of several different pieces:

  • Standardized inputs and field sets for common types of form data

  • Validation functions used for commonly collected types of data

  • A standardized data flow within the application that triggers validation and updates conditionally displayed UI

  • Hooks for custom validation, hiding/showing fields, and writing custom fields and widgets

  • Save and restore form data using the save in progress and pre-fill APIs

What does the Forms Library do?

The Forms Library uses the Yeoman generator script (Yeoman Generator) and allows all files to be created and inserted inside of vets-website project under an application directory. This will also alter the local content-build repo and add an entry to the registry.json file so vets-website knows where your new application is located and how to display it.

The underlying technology of the Forms Library is React JsonSchema Form, and using this framework allows for specifying a “schema” and a “uiSchema” in a single form config file (JSON). This is great for consistency, speed of building, and general ease of use. If you'd like to learn more about these different options go here: Forms Library - About schema and uiSchema

How the Forms Library uses React Json Schema Form (RJSF)

The Forms Library code uses the form config to determine which React components to render to build your form, usually automatically. React components require props to render properly. These are passed down through the top-level Formcomponent, which takes the entire form config itself as a prop. The Formcomponent is also connected to the store, so it can access to the form data as well.

Why is the Forms Library set up using RJSF?

In January of 2017, there were a number of paper forms that needed to be digitized. Teams started researching different tools to easily convert these forms without too much overhead on Engineers and Designers. See the Decision Doc for Using RJSF page for the full history of this effort.

What was found was RJSF, and this solution was chosen because of a few factors:

  • Almost all form specific information is in a single configuration file, and has less boilerplate than building forms with React components.

  • There's very little form-specific React code. Most form specific-code are files that export configuration information, which is easy to modify and overwrite when necessary.

  • Forms are built using a JSON Schema file as a base and the backend uses the same file to validate submissions. So we're less likely to have schema errors than previously.

  • Building the config files is generally faster than building React components for each form.

Once RJSF was chosen, it was very fast to digitize the required OMB paper forms and get them deployed quickly and efficiently. As with all good systems, this came with some challenges and some customization that needed to be implemented. After a certain amount of customization was implemented, the team decided to “fork” the version of RJSF to eliminate upgrade breakages:

  • Switched JSON Schema validators from jsonschema to ajv. The ajv validator is faster and has more detailed error output, but is also much larger. It nearly doubles the size of RJSF. There haven’t been any major issues with jsonschema, and one of our goals is to reduce the bundle size of our forms.

  • Moved defaulting logic out of widgets. This means that all widgets now get form data with empty records, which is contrary to how they were written. It makes it harder to determine when a field is actually empty vs. just defaulted.

  • Maintains internal state for form data. This is not new, but it causes autofill bugs because rapid onChange events can cause stale data to overwrite the current form info. This is a design choice, so it's not really a bug to fix in the current library.

When should the Forms Library be used?

To determine when to use the Forms Library, use the guidelines listed below:

A Form in the Forms Library should follow these general guidelines:

Must have

  • Can accept data

  • Can submit data

    • With the expectation that you’re getting something in return

    • In a linear workflow with a clear start and end

    • At least one piece of data is required to submit it

  • That data goes somewhere

    • Is saved for later

    • To be used through a workflow, review, or approval process

    • To receive sort of response

Can have

  • 1:1 correlation to an OMB number

    • (office of management & budget, as a consumer of gov’t services, it shows it’s official)

    • Not all forms, for example VHA forms, will have an OMB#

  • Conditional components

    • Pathing

    • Field show/hide

  • Can be only submitted once

    • Some forms allow editing after the fact, but it resubmits the data

    • When you must re-submit a form, that sends it through a workflow, review, or approval process again

  • Submitter acknowledgement of how the submitted data will be used

What is not a Form?

  • A search bar

    • Submit and data goes somewhere but it isn’t saved for later

  • Login

    • Authorization and can be submitted more than once

  • CRUD

    • Create, Read, Update, and Delete interface / system that can be continuously updated

    • You can personally maintain in an ongoing fashion

    • Example: profile page, preference settings

  • VA hospital finder - using forms library to find now but is really a search function

  • Note that not all forms applications are using the current forms library:

    • VAOS scheduling

    • VA forms (checkin, et al)

When to use the Design System instead of the Forms Library?

After reviewing the guidelines in the above section and determining that your use case does NOT fit the definition of a form (ex. Search bars, login pages, CRUD, etc), then we suggest you take a look into the Design System elements and components to see which of these could be useful. Here are some helpful links to get you started.

Forms Library standards

Forms Library customizations

Inside of the Forms Library there are a ton of different ways to customize your form/application. A few of them can be referenced below by following the links.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close