Skip to main content

YAML Quotes Guidelines

tip

This page is current and ready for use.

In this project, we aim to use YAML configurations consistently and efficiently. Based on experience and observations (including inconsistencies in the official Overblog documentation), we recommend the following:

General Rule​

  • Do not use quotes (single or double) unless necessary.

When Quotes Are Not Needed​

  1. Simple Field Values:

    • Plain strings, integers, booleans, or lists without special characters.
    • Examples: 
      id:
        type: ID!
      name:
        type: String
      enabled: true
      limit: 10
      roles:
        - admin
        - user
        - guest

  2. GraphQL Type Definitions:

    • Common GraphQL types such as String, Int, Boolean, or non-null types (ID!).
    • Examples: 
      User:
        type: object
        config:
          fields:
            id:
              type: ID!
            email:
              type: String!

When Quotes Are Required​

  1. Special Characters:

    • If a value includes symbols like @, #, :, {}, or other special characters.
    • Example: 
      resolve: '@=query("App\\User\\GraphQL\\Resolver\\UserResolver::getUsers", args)'

  2. Strings Starting with Reserved Characters:

    • Strings starting with *, &, #, or : to prevent YAML misinterpretation.
    • Example: 
      default_value: "*any"

  3. Whitespace or Complex Text:

    • For strings with spaces, newlines, or unusual formatting.
    • Example: 
      notes: "User's full name and contact details."

  4. Avoiding YAML’s Implicit Typing:

    • Words like yes, no, on, off, etc., should be quoted to avoid being interpreted as booleans.
    • Example: 
      status: "no"

  5. Environment Variables with Special Characters:

    • Use quotes when values include %, $, parentheses, or other special characters.
    • Always use double quotes for environment variables for consistency.
    • Example: 
      api_key: "%env(API_KEY)%"

  6. Array Type in GraphQL:

    • Always quote array types to ensure proper parsing.
    • Example: 
      items:
        type: "[String]"

  7. Description:

    • Always quote description to ensure proper parsing.
    • Example: 
      items:
        type: "[String]"
        description: "This is a collection of multiple items"
  • Avoid quotes for simple cases to keep the YAML clean and readable.
  • Use quotes when dealing with special cases as outlined above.
  • Maintain consistency throughout the codebase.

Examples​

General Use Case (Preferred for Simplicity)​

User:
  type: object
  config:
    description: "A user object"
    fields:
      id: ID!
      email: String
      isActive: Boolean
      gender: "[String]"

By following these guidelines, developers can ensure clean, consistent, and error-free YAML configurations across the project.

For a detailed information, you can refer here.