PokeAPI/api-data

API validity broken

mlemesle opened this issue · 6 comments

mlemesle commented

Hello !

I'm currently working on my library wrapping PokeAPI. By default, I set everything as nullable.
However, after checking this repo and looking in data/schema, I wanted to remove those nullable to be valid to the json schemas.

Unfortunately, if I'm not mistaken, the schemas seem outdated. For example:
ContestEffect json schema says there is 2 keys in flavor_text_entries inner data type, flavor_text and language. But in PokeAPI official docs flavor_text_entries inner type is FlavorText and there is a new key that the json schema doesn't mention: version.

After a quick call to the API, it seems the official doc is the one to follow, but the official doc doesn't state which fields are nullable and which fields aren't.

So which documentation should I trust ? If possible, can you regenerate the schemas (and maybe regenerate them regurlary like the data) ?

Thanks for you attention.
I'm open to discuss the topic :)

C-Garza commented

I'm pretty sure the schema is the source of truth here and are regenerated on new merges in pokeapi. The docs are updated manually I believe. It probably shouldn't be listed as FlavorText since it doesn't have the version on it. The version got added to it because other resources have it and it was just missed here.
For example, the flavor_text_entries on the /pokemon-species endpoint has that missing version field:
https://pokeapi.co/api/v2/pokemon-species/1

C-Garza commented

A bit more about discussion on nullable fields here:
PokeAPI/pokeapi#683

mlemesle commented

Thanks for your answer !

So if I understand correctly, the documentation at https://pokeapi.co/docs/v2#flavortext says there is a field version, but all types pointing to it don't use the version field ?

Then we can't know for sure what fields are nullable and which types aren't.

The real documentation is then a mix between the doc at https://pokeapi.co/docs/v2 and the json_schema ?

Naramsim commented

Hi @mlemesle, basically the docs aren't autogenerated. Most probably there are some errors there. We should investigate how to build them from either this schema file, or even better the schema in our python files.

https://github.com/PokeAPI/pokeapi/blob/master/pokemon_v2/models.py#L1017 Link from the URL @C-Garza posted above.

mlemesle commented

Noted !
Thanks for the explanations!

  • 👍1
Naramsim commented

I'll close thanks