[Windows] 10, version 1607 (W) is missing a link, schema validation fails

[filip-szweda]

Link to product page on endoflife.date

https://endoflife.date/api/windows/10,%20version%201607%20(W).json

Details of incorrect and correct details you have found

The cycle's link is missing.

This means that schema present in openapi.yml fails to validate the cycle's JSON.

Either the schema would have to be updated from:

link:
  type: string
  minLength: 1
  description: 'Link to changelog for the latest release, if available'

or missing link should be added.

Additional context

To avoid such discrepancies in the future, do you think it would be worth adding to the CI a Python script that would validate every change to product .md(s) against the schema?

[captn3m0]

We already have a script (https://github.com/endoflife-date/endoflife.date/blob/master/_auto/validate.py), but it doesn't validate the link property yet.

[filip-szweda]

Oh, understood. Thank you for the clarification.

[marcwrobel]

In this case the link is optional, so I think we need to change the schema.

[captn3m0]

We should do both:

1. Fix the schema to mark it as optional
2. Update our generator to avoid link: null values.

@filip-szweda Curious to hear how you're using the API. We have a Known Users wiki page, would like to update this if it's an interesting usecase.

There's also a v1 API in progress (#2080), would appreciate feedback there as well.

[marcwrobel]

2. Update our generator to avoid link: null values.

I do not think we can do that. link: null is needed to suppress the link if a changelogTemplate is configured for the product. So without that information a link based on the changelogTemplate will be automatically generated.

[captn3m0]

I meant dropping null values in the output JSON files, not in the input YAML. Basically, if link=null, unset(release.link)

[marcwrobel]

I meant dropping null values in the output JSON files, not in the input YAML. Basically, if link=null, unset(release.link)

That does not seem compatible with #2079.

[marcwrobel]

Just checked by generating a client with openapi-generator-cli.

# spec is declared invalid, but it is not (see https://spec.openapis.org/oas/v3.1.0.html#license-object), hence --skip-validate-spec
docker run --rm -v $PWD:/local openapitools/openapi-generator-cli generate -i /local/openapi.yml --skip-validate-spec -g java -o /local/out

The generated code for link is :

   /**
   * Link to changelog for the latest release, if available
   * @return link
  **/
  @javax.annotation.Nullable
  public Object getLink() {
    return link;
  }

This is consistent with what I read on the subject, which says that parameters are optional by default (see the required field on https://spec.openapis.org/oas/latest.html#model-with-example). But I may have missed something, it needs to be confirmed by more research.

@filip-szweda, what makes you say the link attribute is mandatory ? Did you use a generator to create the client ? And if you used a generator, which one ?

[filip-szweda]

Hey, I'm on a leave right until next week. Now unfortunately I can't get this information.

Additionally, I was allowed by my company to share the usecase we're your using your project for (as @captn3m0 asked), but this will also have to wait until next week.

Thanks in advance for understanding.

[filip-szweda]

@captn3m0 @marcwrobel Thank you for your wait!

First of all, I am a developer from Agent Installation & Deployment team of Dynatrace.
We have a JSON list of operating systems supported by our product, OneAgent, and we want to keep it up to date https://www.dynatrace.com/support/help/technology-support

For that purpose, a special tool has been created that verifies EOL dates and checks for new operating systems using your endoflife.date project.

It is important for us to keep the API as stable as possible.
With that being said, we understand that it is in its early development stage.
#2080 will definitely help, but we are also afraid of general data changes such as e.g. #2297

If you are interested in putting us somewhere as your customer, let us know - we can write something more.

Second of all, to validate data from the API our tool uses schemas contained in endoflife.date/assets/openapi.yml.
The schemas are loaded with pyyaml using safe_load function.
The issue is that the link attribute lacks 'null' type.
Its definition should look like this:

link:
  type:
	- string
	- 'null'
  minLength: 1
  description: 'Link to changelog for the latest release, if available'

[captn3m0]

1. I've filed [api] Mark link as nullable #2483 for the nullable issue. Please confirm if this fixes the issue.
2. I added Dynatrace to our list of known users wiki page: https://github.com/endoflife-date/endoflife.date/wiki/Known-Users

We try to ensure consistency for the API wherever we can, so releases will always use x.y for easier matching (No prefix/suffix) whenever possible. However, windows numbering scheme is weird, so we can't really have any good guarantees there - we will switch to a better scheme if we find it, same as switching to better links, or more accurate dates.

The releaseLabel changes are supposed to be cosmetic, and our v1 API will pre-render these nicely, so such minor changes will not impact the API ideally.

Hopefully, once we have a stable API release, we will have a way to notify users of API breakage on a product level, but that's a far away goal as of now.

[filip-szweda]

Thank you for the fix.