pings.yaml file

Documentation for the pings.yaml file has moved to custom pings in the Glean user documentation.

JSON Schema

There is a formal schema for validating pings.yaml files, included in its entirety below:

# This Source Code Form is subject to the terms of the Mozilla Public
# License, v. 2.0. If a copy of the MPL was not distributed with this
# file, You can obtain one at http://mozilla.org/MPL/2.0/.

---
$schema: http://json-schema.org/draft-07/schema#
title: Pings
description: |
  Schema for the pings.yaml files for Mozilla's Glean telemetry SDK.

  The top-level of the `pings.yaml` file has a key defining the name of each
  ping. The values contain metadata about that ping. Ping names must be
  kebab-case per https://docs.telemetry.mozilla.org/cookbooks/new_ping.html

$id: moz://mozilla.org/schemas/glean/pings/2-0-0

definitions:
  dotted_snake_case:
    type: string
    pattern: "^[a-z_][a-z0-9_]{0,29}(\\.[a-z_][a-z0-9_]{0,29})*$"
    maxLength: 40
  # Prior to version 2.0.0 of the schema, special ping names with underscores
  # were also supported.
  kebab_case:
    type: string
    pattern: "^[a-z][a-z0-9-]{0,29}$"

type: object

propertyNames:
  allOf:
    - anyOf:
        - $ref: "#/definitions/kebab_case"
        - enum: ['$schema', 'no_lint']
    - not:
        enum: ['all-pings']

properties:
  $schema:
    type: string
    format: url

  no_lint:
    title: Lint checks to skip globally
    description: |
      This parameter lists any lint checks to skip for this whole file.
    type: array
    items:
      type: string

additionalProperties:
  type: object
  properties:
    description:
      title: Description
      description: |
        **Required.**

        A textual description of the purpose of this ping and what it contains.

        Descriptions may contain [markdown
        syntax](https://www.markdownguide.org/basic-syntax/).
      type: string

    metadata:
      title: Metadata
      description: |
        Additional metadata about this ping. Currently limited to a list of
        tags.
      type: object
      properties:
        tags:
          title: Tags
          description: Which tags are specified for this ping.
          type: array
          items:
            type: string
            maxLength: 80
        precise_timestamps:
          title: Precise Timestamps
          description: |
            When `true` Glean uses millisecond-precise timestamps for
            the ping's start/end time (the default).
            When `false` Glean uses minute-precise timestamps for
            the ping's start/end time.
          type: boolean
        include_info_sections:
          title: Include Info Sections
          description: |
            When `true`, assemble and include the `client_info` and `ping_info`
            sections in the ping on submission.
            When `false`, omit the `client_info` and `ping_info` sections when
            assembling the ping on submission.
            Defaults to `true`.

            Interaction with `include_client_id`: `include_client_id` only takes
            effect when `metadata.include_info_sections` is `true`.
          type: boolean
        ping_schedule:
          title: Ping Schedule
          description: |
            An optional array of ping names. When one of the listed pings is
            sent, then this ping will also be sent. A ping cannot list its own
            name in `ping_schedule`.
          type: array
          items:
            type: string
            maxLength: 30

      default: {}

    include_client_id:
      title: Include client id
      description: |
        **Required.**

        When `true`, include the `client_id` value in the ping.

        Interaction with `metadata.include_info_sections`: `include_client_id`
        only takes effect when `metadata.include_info_sections` is `true`.
      type: boolean

    send_if_empty:
      title: Send if empty
      description: |
        When `false` a ping is sent only if it contains data (the default).
        When `true` a ping is sent even if it contains no data.
      type: boolean

    notification_emails:
      title: Notification emails
      description: |
        **Required.**

        A list of email addresses to notify for important events with the
        ping or when people with context or ownership for the ping need to
        be contacted.
      type: array
      minItems: 1
      items:
        type: string
        format: email

    bugs:
      title: Related bugs
      description: |
        **Required.**

        A list of bugs (e.g. Bugzilla and Github) that are relevant to this
        ping, e.g., tracking its original implementation or later changes to
        it.

        It must be a URI to a bug page in a tracker.

        Prior to version 2.0.0 of the schema, bugs could also be integers.
      type: array
      minItems: 1
      items:
        type: string
        format: uri

    data_reviews:
      title: Review references
      description: |
        **Required.**

        A list of URIs to any data collection reviews relevant to the ping.
      type: array
      items:
        type: string
        format: uri

    reasons:
      title: The reasons this ping can be sent.
      description: |
        A list of reasons that the ping might be triggered. Sent in the ping's
        `ping_info.reason` field.

        Specified as a mapping from reason codes (which are short strings), to
        a textual description of the reason.
      type: object
      propertyNames:
        type: string
        maxLength: 30
      additionalProperties:
        type: string

    enabled:
      title: Whether or not this ping is enabled
      description: |
        **Optional.**

        When `true`, the ping will be sent as usual.
        When `false`, the ping will not be sent, but the data will continue to
        be collected and will be cleared when the ping is submitted.

        Defaults to `true` if omitted.
      type: boolean

    no_lint:
      title: Lint checks to skip
      description: |
        This parameter lists any lint checks to skip for this metric only.
      type: array
      items:
        type: string

  required:
    - description
    - include_client_id
    - bugs
    - notification_emails
    - data_reviews

  additionalProperties: false