YAML OpenAPI format/profile

[pali]

Hello! I would like to ask some information about YAML::PP and OpenAPI YAML files.

OpenAPI specification is at website https://swagger.io/specification/ and says that it uses YAML 1.2 format with some constrains:

• Tags MUST be limited to those allowed by the JSON Schema ruleset.
• Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.

Can YAML::PP parse these YAML files with above constrains correctly?

And could be YAML::PP configured to generate YAML file from Perl structure according to these constrains?

[perlpunk]

I worked a bit with OpenAPI, but I'm not uptodate.

That said,

OpenAPI specification is at website https://swagger.io/specification/ and says that it uses YAML 1.2 format with some constrains:

• Tags MUST be limited to those allowed by the JSON Schema ruleset.

Yes, YAML::PP implements all 3 schemas from 1.2 (Failsafe, JSON and Core).
However, the JSON schema diverges from the official one, in that strings in gerneral don't have to be quoted (unless special values).
If I read the specification, it actually says

null                                                           | tag:yaml.org,2002:null
true \| false                                                  | tag:yaml.org,2002:bool
-? ( 0 \| [1-9] [0-9]* )                                       | tag:yaml.org,2002:int
-? ( 0 \| [1-9] [0-9]* ) ( \. [0-9]* )? ( [eE] [-+]? [0-9]+ )? | tag:yaml.org,2002:float
*                                                              | Error

So anything that is not null, boolean or a number, needs to be quoted.
I plan to add this original Schema, maybe as JSONStrict or something.
From what I understand, OpenAPI does not want anyone to quote all strings, so they probably also mean the less stricter version of it.

To use the JSON Schema:
my $yp = YAML::PP->new( schema => ['JSON'] );

This is actually the current default, but I decided that it was not a good decision. The Core schema should be the default, because that will be compatible to most other YAML processors that implement 1.2. Some of them only implement the Core Schema. (I want to change it and hope I can do that soon and not too much users really depend on the default right now...)

• Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.

This is not something you can restrict YAML::PP to without being prepared for changes. You can already add some callbacks to influence the loading process, but it's still in the works, and overriding the hash construction is probably something that will change.

And could be YAML::PP configured to generate YAML file from Perl structure according to these constrains?

You mean dumping an OpenAPI specification to YAML? Only with the first constraint currently.
Edit: Well, actually since in perl all keys are strings, with both constraints can be made for dumping.

I'm always happy to hear about new use cases. So far only one CPAN project I know of is using the tag resulution/callback API.

[perlpunk]

• Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.

Another comment about this: The Failsafe schema does not restrict mapping keys to only scalars.

YAML places no restrictions on the type of keys; in particular, they are not restricted to being scalars.

So I find this rule a bit confusing.

[pali]

Primary use case is:
Load & convert OpenAPI 3 YAML file correctly to Perl in-memory structure (e.g. hashref/arrayref).

We have already find out that e.g. Python YAML parser has problems with yes and no keys. According to OpenAPI 3, following YAML file

somekey:
 - yes
 - value

should be interpreted as somekey => [ 'yes', 'value' ] (both yes and value as strings). But e.g. python interprets unquoted yes as boolean value, not as string. And unquoted false should be boolean false value.

I do not know if there can be other problems, but booleans and unquoted literals are the first thing which started causing problems in more languages when we were trying to load OpenAPI 3 YAML files.

[perlpunk]

Yes, Python's PyYAML implements only the YAML 1.1 types, so it cannot be used for this. You can try the alternative ruamel.yaml.

Besides booleans and null values, also the regular expressions for numbers are different between the YAML 1.2 Core and JSON schema.
So by explicitly using the JSON schema in YAML::PP you should be safe.
You probably also want to enable JSON::PP booleans:
my $yp = YAML::PP->new( schema => ['JSON'], boolean => 'JSON::PP' );

[pali]

So by explicitly using the JSON schema in YAML::PP you should be safe.

Ok, thank you very much for information.