Adding comments in a GraphQL text

The standard way of adding comment in a GraphQL text (Schema, query or mutation) is by using a '#' at the begining of the line to comment out. The comment starts with this '#' and ends at the end the the line. Here are some examples

mutation {
# This is a single line comment
CreateNodesAndRelations(

#********************************************#
#*** This is a kind of multi-line comment ***#
#********************************************#

    Nodes: [
			{ 
            KeyProperty: "Key", 
            KeyValue: "Custom variables1",
            #******** Comments can be anywhere ******** 
            NodeType: "VARIABLE_GROUP" ,
            Properties : [ {Name : "Type",Value: "Custom1"}]}
        ],
    WhatIf : 0
) { WhatIf NumberOfNodes }}

Swagger issue

The normalized comments are not well suite for swagger input fields. Imagine the following GraphQL query:

#This is a valid GraphQL query
query { Name { Prop }}

When this text is pasted in swagger, it becomes a single line, all CR/LF characters being erased. The query entering the Open Data Model engine will look like: "#This is a valid GraphQL query query { Name { Prop }}" Since this sigle line is fully commented out due to it's first character, the query is interpreted as an empty one.

Recommended way to comment

If you want a GraphQL text that is GraphQL-compliant and that works well in swagger, just append the string "\n" (2 chars, '\' + 'n') at the end of EVERY comment line. The Open Data Model will convert this "\n" into a real carriage return. Any other GraphQL (tool like Altair) will handle the text the right way since the "\n" string is at the end of a commented line, hence not interpreted.

Our previous example of commented text becomes:

mutation {
# This is a single line comment \n
CreateNodesAndRelations(

#********************************************#\n
#*** This is a kind of multi-line comment ***#\n
#********************************************#\n

    Nodes: [
			{ 
            KeyProperty: "Key", 
            KeyValue: "Custom variables1",
            #******** Comments can be anywhere ********\n 
            NodeType: "VARIABLE_GROUP" ,
            Properties : [ {Name : "Type",Value: "Custom1"}]}
        ],
    WhatIf : 0
) { WhatIf NumberOfNodes }}

Caution

The replacement of "\n" is performed during a pre-processing phase, not during the parsing phase. This means that the Open Data Model engine will replace it independently of it's parsed location.

Imagine a property named "My\nProperty": the pre-processor will replace \n by a carriage return leading the parse to fail because a carriage return is not allowed in a string definition.