Skip to content

Message Best Practices

Jump to bottom
Phil Adams edited this page Mar 29, 2023 · 6 revisions

Message Best Practices

This page provides guidance on best practices associated with developing messages to be displayed by a validation rule to identify a violation. These guidelines will help ensure that messages displayed by the validator have a consistent appearance and style.

Guidelines:

  1. Use clear and concise wording. Be as brief as possible while still conveying to the user enough information to assist them in fixing the violation.

  2. Messages need not be complete sentences. Avoid adding a period at the end of messages.

  3. If possible, construct the message so that any variables appear at the end of the message. This is due to the fact that the validator will group together (in the summary section of the output) any messages that differ only by a ": foo" suffix. Compliance with this guideline will help facilitate that.
    Examples:

    • A tag is defined but never used: UnusedTag01
    • Properties with the same name have inconsistent types: id

  4. When using a proper name within a message (such as a property name or schema name), it should be quoted with single quotes. An exception to this is that when a property name appears at the end of a message after the ':' separator, no need for quoting.
    Examples:

    • The 'offset' parameter must be of type integer and optional
    • 'minimum' cannot be greater than 'maximum'
    • Discriminator property must be defined in the schema: resource_type

  5. Within a message, http methods should be displayed in upper-case.
    Examples:

    • DELETE operations should not contain a requestBody
Clone this wiki locally