Support question: OpenAPI 3.0.x flow mapping workarounds

[numberoverzero]

Thanks for the great library! I'm hoping to use this instead of pyyaml when parsing OpenAPI 3.0.x documents, but I'm running into an issue with the Security Requirements Object of a path item.

From that link, emphasis mine:

Each name MUST correspond to a security scheme which is declared in the Security Schemes under the Components Object. If the security scheme is of type "oauth2" or "openIdConnect", then the value is a list of scope names required for the execution. For other security scheme types, the array MUST be empty.

This means I've got paths like this:

paths:
  /users/{userId}/widgets/{widgetId}/revisions:
    post:
      operationId: createWidgetRevision
      security:
        - apiToken: []

Which fails as expected with FLowMappingDisallowed:

$ ipython
Python 3.6.5 (default, Apr  1 2018, 15:30:28) 
Type 'copyright', 'credits' or 'license' for more information
IPython 6.5.0 -- An enhanced Interactive Python. Type '?' for help.

In [1]: from strictyaml import load

In [2]: doc="""paths:
   ...:   /users/{userId}/widgets/{widgetId}/revisions:
   ...:     post:
   ...:       operationId: createWidgetRevision
   ...:       security:
   ...:         - apiToken: []"""

In [3]: load(doc)
FlowMappingDisallowed [traceback clipped]

Any recommendations? There's also a commonly-used form for an unauthenticated method with a similar issue:

paths:
  /items/{itemId}:
    put:
      operationId: updateItem
      security:
        - {}

[crdoconnor]

Hi @numberoverzero thanks for your issue. I'm really sorry I haven't gotten back to you sooner. I was on holiday for the last couple of weeks (and with only intermittent internet access). I won't be so unresponsive from now on.

As to your question, I see two ways of dealing with it. Either make your YAML like this (e.g. by running it through ruamel.yaml first and then changing just those things):

paths:
  /users/{userId}/widgets/{widgetId}/revisions:
    post:
      operationId: createWidgetRevision
      security:
        - apiToken: 

You can then use the EmptyList validator you could interpret the blank value as an empty list.

Or changing the document to be like this:

paths:
  /users/{userId}/widgets/{widgetId}/revisions:
    post:
      operationId: createWidgetRevision
      security:
        - apiToken: '[]'

Using Enum("[]") you could ensure that it is only possible to parse a string of '[]'. This is possibly less ideal since you don't really want to get back "[]" as a string.

Unfortunately I don't see another happy way of dealing with this problem without 1) enabling flow style completely or 2) adding this as some sort of special case where flow style is allowed, but only for empty lists and mappings (which makes me a bit uncomfortable).

[crdoconnor]

On the other hand I've just noticed woocart@8963a53 by @zupo which suggests that you're not the only one that wants this, so maybe I should rein in my objections to flow style and at least allow it to be turned on via an optional parameter...

[zupo]

Yep, my use case is restricted to how PHP works (i.e. how PHP is broken) so I couldn't fix the source YAML but had to do a workaround in a fork.

[numberoverzero]

Would you consider a set of flags that has a discouraging name so most people don't enable them?

class PoorForm:
    FLOW_MAPPING = 1
    DUPLICATE_KEYS = 2
    ANCHOR_TOKENS = 4

and usage:

from strictyaml import load, PoorForm


bad_swagger_decisions = PoorForm.FLOW_MAPPING | PoorForm.ANCHOR_TOKENS
with open("v1.yaml", "r") as f:
    spec = load(f.read(), allow=bad_swagger_decisions)

[crdoconnor]

Yeah, I'm coming around to this idea. Except for the duplicate keys thing (I don't think anybody would actually want that), I might create a special method for parsing disallowed YAML.

I think I'll probably have to turn off roundtripping too, since parsing this stuff opens up a can of worms that I don't really want to get in to.

[crdoconnor]

Dirty load is now available and implemented in version 0.13.0:

http://hitchdev.com/strictyaml/using/alpha/restrictions/loading-dirty-yaml/

[numberoverzero]

Thanks for adding this! Docs look great too.

[hax]

"dirty load" seems really dirty :)

2. adding this as some sort of special case where flow style is allowed, but only for empty lists and mappings (which makes me a bit uncomfortable).

Theoretically only empty lists/mappings is the issue, so adding special case is not bad at all :P

---

Before I know strictyaml, I actually already write yaml close to strictyaml, I avoid flow style in most cases, the only case I want to use flow style is when the data is simple enough so it could be wrote in one line.

So I think maybe we could introduce one-line style (only allow non-nested flow style in one line) which make it not very "special" but also useful?

[gunpinyo]

I just come across StrictYAML and really like the idea, but the restriction of flow mapping was about to be my deal-breaker: I was wonder why this is a bad thing? It is indeed a good way to write a short list/dict in a single line: allowing us to write more compact YAML files, which is more human-readable.

Then, I realise the motivation of this restriction is; in fact, the multiline flow mapping, which I completely agree that it should be forbidden. However, I agree with @hax that a single line flow mapping should be allowed with the reason of my paragraph above.

[crdoconnor]

My motivation was driven by: * The desire to have one, simple obvious way of doing things. * Crafting the language such that its form and behavior was obvious to non-programmers - for whom the distinction between null, empty list, dict and empty string is non-obvious. * Fighting with templating languages both used to generate entire YAML documents and embedded within text values wherein there was an almighty mess of {s and }s and [s and ]s, some of which were non-obviously part of the YAML and some of which were non-obviously not.

…

On Wed, 13 Oct 2021, 05:03 Gun Pinyo, ***@***.***> wrote: I just come across StrictYAML and really like the idea, but the restriction of flow mapping was about to be my deal-breaker: I was wonder why this is a bad thing? It is indeed a good way to write a short list/dict in a single line: allowing us to write more compact YAML files, which is more human-readable. Then, I realise the motivation of this restriction is; in fact, the *multiline* flow mapping, which I completely agree that it should be forbidden. However, I agree with @hax <https://github.com/hax> that a single line flow mapping should be allowed with the reason of my paragraph above. — You are receiving this because you modified the open/close state. Reply to this email directly, view it on GitHub <#38 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABOJKNKW4U5JIRLCRVUJ6TTUGUAH5ANCNFSM4FSZ533Q> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>.

[crdoconnor]

Also note that comma separated lists on a single line can be parsed with https://hitchdev.com/strictyaml/using/alpha/scalar/comma-separated/

This is shorter (no opening [ and closing ] required), explicitly type-safe and, IMO, a little more non-programmer friendly than flow-style lists.