65

I have the following YAML fragment:

description: |
  "API for bean consuming applications.
  Examples: painted pony, lima bean"

Swagger editor interprets the colon (:) as a special character, despite the quotation marks.

According to the accepted answer to this question, the colon should not be treated as special character.

Is this a bug of Swagger or is an escape sequence needed to use the colon in quoted text literals?

I tried to find this out using the YAML specification but gave up.

How do I have to read that spec to answer the question?

Is there a difference between single quotes (') and double quotes (") in YAML?

Does the pipe (|) or the greater than (>) construction only influence the line break handling or the handling of special characters, too?

dreftymac
  • 31,404
  • 26
  • 119
  • 182
Gustave
  • 3,359
  • 4
  • 31
  • 64
  • 1
    If you paste this fragment into [Online YAML Parser](http://yaml-online-parser.appspot.com/), you will found that not only colons are preserved in the `description` value, but also quotation marks themselves. Actually quotes have special meaning for *flow* scalars, not for *block* scalars which are denoted with '|' and '>'. – Tsyvarev Oct 07 '15 at 13:16
  • For this kind of questions the online editor helps a lot: http://editor.swagger.io/ – David Lopez Oct 07 '15 at 14:25
  • I experienced different YAML tools behaving very inconsistently, so I would not rely on some tools behaviour to say if something is wrong or not. That's the reasson I explicitely asked for the spec. – Gustave Oct 08 '15 at 07:31

3 Answers3

51

I would consider this a bug in swagger, but I have seen problems in other editors e.g. when highlighting YAML.

When a string scalar is surrounded by single quotes '....' the only escaping within that string that can be done is inserting a double single quote to indicate a single quote: 

'It''s a good question'

When double quotes, "....", go around a scalar string you use backslash (\) for escaping, and you have to escape at least the backslash and the double quotes. In addition you can escape other special characters like linefeed (\n) and escape an end-of-line by preceding it by a backslash.

The YAML spec says there is no way to escape characters inside literal scalars ( starting with |), so you cannot insert extra newlines, or other escape sequences withing these.

For the folded style (>), the escaping behaviour is as with literal scalars.

All string scalars except for plain scalars (those without any quotes or >/|) can contain : followed by space without problem, and if an editor interprets that differently, that is understandable (as full YAML parsing is expensive), but incorrect.

patridge
  • 26,385
  • 18
  • 89
  • 135
Anthon
  • 69,918
  • 32
  • 186
  • 246
  • Thanks for your answer! Still I am not able to find the relevant parts of the spec. The link you provided takes me to "3.2.1.3. Node Comparison". How is that related to escape mechanisms? – Gustave Oct 08 '15 at 09:00
  • @Gustave Sorry, pasted in a wrong link. I have updated it. It is in the sentence right before example 8.8 – Anthon Oct 08 '15 at 11:05
  • 2
    For what it's worth, the linked spec is for YAML 1.2 which contains breaking changes from YAML 1.1. PyYAML uses the 1.1 spec. Ref: http://pyyaml.org/wiki/PyYAML – Taylor D. Edmiston Aug 03 '16 at 02:25
33

I had the exact same issue, and found that using the HTML escape code works :, which is what I resorted to.

Boris Lutskovsky
  • 551
  • 5
  • 11
  • 2
    So to escape these kinds of character in YAML, should one always resort to using HTML code? – BND Mar 22 '19 at 09:58
  • Can you back this up with a reference? The yaml spec (1.2.2) doesn’t mention `entity` or `` so what you are describing sounds implementation specific. Also `&` is not on the list of characters that need escaping, which support of HTML entities would imply. – mvds Nov 27 '21 at 17:45
  • Maybe Swagger's implementation of YAML in early 2017 wasn't completely up to spec? – Boris Lutskovsky Dec 06 '21 at 20:07
  • The question seems to (also) be about YAML in general, so I would avoid making statements without a reference or some additional constraints about the applicability to a particular implementation. I was new to YAML when I posted my comment and this answer needlessly confused me. – mvds Dec 07 '21 at 19:50
11

Building on answers already provided in other comments: http://yaml.org/spec/1.2/spec.html#id2788097

And from this: https://yaml.org/spec/1.2/spec.html#id2776092

I found that with any quotes you can just use two colons to escape the colon special character. i.e. ::

So the description would become:

description: "API for bean consuming applications. Examples:: painted pony, lima bean"

Updated from comment: It looks like swagger specifically doesn't like multi-line strings, and in the editor whether the quoted text is on two lines or one it shows up the same. So I would suggest keeping the double quoted text on one line, to avoid problems with colons. i.e.

description: | "API for bean consuming applications. Examples: painted pony, lima bean"

RichE
  • 133
  • 1
  • 6
  • Unfortunately, this doesn't seem to work in [the Swagger editor](https://editor.swagger.io) - I still get a parsing error with a double colon. – wwkudu May 18 '21 at 15:03
  • Ah, I tried it in swagger, it doesn't seem to need double colons. But it does need to be on the same line, so based on the example given here, it should be: ` description: | "API for bean consuming applications. Examples: painted pony, lima bean" ` – RichE Jun 01 '21 at 16:36