Date example changed type after merging

[robertmassaioli]

Moved from: https://bitbucket.org/echo_rm/openapi-merge/issues/8/date-example-changed-type-after-merging

Hi, when I’m trying to merge 2 specs and one includes a schema with property of type string and format date and has an example specified e.g. 2017-07-21, after I run the openapi-merge-cli the example changes from date to date-time. E.g. 2017-07-21T00:00:00.000Z

I created a repository with an example: https://github.com/falnyr/openapi-merge-date-bug

[robertmassaioli]

This is a really common mistake. The fix is this:

diff --git a/spec/spec1.yaml b/spec/spec1.yaml
index bb9be08..d7422e7 100644
--- a/spec/spec1.yaml
+++ b/spec/spec1.yaml
@@ -28,4 +28,4 @@ components:
         dateCreated:
           type: string
           format: date
-          example: 2017-07-21
+          example: "2017-07-21"

The mistake that people make is that Yaml spec requires that anything that looks like a Date, and is not in string quotes, will be parsed as a date.

Therefore the Yaml parser that we uses parses this into a JS DateTime and then stringifies it back out in ISO format to the output file. Ensuring that your example actually is a Yaml string (by wrapping it in quotes) gets the behaviour you expect.

I hope this helps!

[falnyr]

Hey @robertmassaioli! Thanks for coming back on this one.

I understand the parser treats the 2017-07-21 as a Date and casts it back when I don't specify the quotes like this"2017-07-21".

The issue I see here is the stringification. If the spec is format: date-time, then the stringification should result in what it does now - e.g. 2017-07-21T00:00:00.000Z.

In case of the format: date however, the stringification should result in 2017-07-21 as the time part is not desired and this results in invalid OpenAPI spec.

[robertmassaioli]

@falnyr Just to make things even clearer:

• The openapi-merge library is behaving correctly on this data.
• The Yaml parser library (js-yaml) that this library is using is behaving correctly by treating the YAML date as a Date and then converting it back into a Date Time string when it dumps that yaml.

The problem is that the input that it has been given is invalid: the input OpenAPI definition is wrong. The date string needs to be in quotes.

To word it a different way, here is the type that has been defined:

dateCreated:
  type: string
  format: date
  example: 2017-07-21

Now we can look at two facts from this definition:

1. As we have already ascertained, the example value will be parsed as a Date because it is a Yaml Date.
2. The type of dateCreated is string.

That means that the type of the example is Date when a string is expected: there is a type mismatch. Thus the openapi definition is invalid. This means that the bug belongs with whomever wrote, or generated, the original OpenAPI definition.

As you can see, this would be true even if the format field did not exist. This means that the format field is irrelevant when considering the behaviour here.

In conclusion, there is no bug in the openapi-merge library here; this is expected and valid behaviour. I hope this helps!

In terms of next steps for you I would:

1. Try and see if you can get this bug fixed up in the original OpenAPI files.
2. See if you can try and get your linting tool to indicate that using a Yaml date in an OpenAPI file is a mistaken that needs to be fixed.
3. Reach out to js-yaml and see if they are willing to implement an option that will always treat Yaml Dates as Strings in the load function.

For openapi-merge, I'm attempting to stay away from modifying any of the input OAS files. I think that it should be the responsibility of another tool or process to do that in an attempt to keep this library focussed.