Syntax for GitHub's form schema

You can use GitHub's form schema to configure forms for supported features.

In this article

Note

GitHub's form schema is currently in public preview and subject to change.

About GitHub's form schema

You can use GitHub's form schema to configure forms for supported features. For more information, see Configuring issue templates for your repository.

A form is a set of elements for requesting user input. You can configure a form by creating a YAML form definition, which is an array of form elements. Each form element is a set of key-value pairs that determine the type of the element, the properties of the element, and the constraints you want to apply to the element. For some keys, the value is another set of key-value pairs.

For example, the following form definition includes four form elements: a text area for providing the user's operating system, a dropdown menu for choosing the software version the user is running, a checkbox to acknowledge the Code of Conduct, and Markdown that thanks the user for completing the form.

YAML
- type: textarea
  attributes:
    label: Operating System
    description: What operating system are you using?
    placeholder: "Example: macOS Big Sur"
    value: operating system
  validations:
    required: true
- type: dropdown
  attributes:
    label: Version
    description: What version of our software are you running?
    multiple: false
    options:
      - 1.0.2 (Default)
      - 1.0.3 (Edge)
    default: 0
  validations:
    required: true
- type: checkboxes
  attributes:
    label: Code of Conduct
    description: The Code of Conduct helps create a safe space for everyone. We require
      that everyone agrees to it.
    options:
      - label: I agree to follow this project's [Code of Conduct](link/to/coc)
        required: true
- type: markdown
  attributes:
    value: "Thanks for completing our form!"

Keys

For each form element, you can set the following keys.

KeyDescriptionRequiredTypeDefaultValid values
typeThe type of element that you want to define.String
  • checkboxes
  • dropdown
  • input
  • markdown
  • textarea
  • upload
idThe identifier for the element, except when type is set to markdown. Can only use alpha-numeric characters, -, and _. Must be unique in the form definition. If provided, the id is the canonical identifier for the field in URL query parameter prefills.String
attributesA set of key-value pairs that define the properties of the element.Map