Absolutely! Adding comments alongside property definitions (like your examples notes: string # optional and role: string # admin | market | client) is totally allowed and widely used in YAML.

How YAML comments work #

In YAML, any text starting with a # (hash symbol) is treated as a comment, and everything from the # to the end of the line is ignored by parsers. This means you can place comments:

• At the start of a line (like your top-level # profile fields comment)
• After a property and its value, exactly as you've done with the optional fields and role enum notes

Example of valid YAML with inline comments #

Here’s your provided YAML, which is completely valid:

# profile fields
firstName: string
lastName: string
phoneNum: string # optional
active: boolean
notes: string # optional
role: string # admin | market | client
by: User_Id

This pattern is super useful for documenting details like optional fields, allowed value ranges, or field purposes directly in your YAML schema, making it easier for other developers (or future you) to understand the structure at a glance. All major YAML parsers support this syntax without issues.

内容的提问来源于stack exchange，提问作者Islam Y-