Which JSON properties are optional?

Opensubtitles API Developing
1

In the documentation for the JSON Subtitle model all properties are listed as required:

However the server is sometimes returning null for the following properties:

  • comments
  • from_trusted
  • legacy_subtitle_id
  • parent_title
  • tmdb_id
  • uploader_id
  • year

Specific examples shown below.

The macOS JSONDecoder will throw an exception when parsing a null value unless I have specified an optional type for that property. Using optional types for all properties would avoid this, but it is desirable to avoid the additional code to handle an optional type if it is known that a property must always have a value.

I am a bit worried that I have not identified all of the optional properties. Is there a list of properties that are guaranteed to not have null values?

Examples:

low-batt@gag ~$ curl --location --silent 'https://api.opensubtitles.com/api/v1/subtitles?languages=en&query=Better%2BCall%2BSaul%2BS04E03%2B1080p%2BBluRay%2Bx265-RARBG.mp4' \
>   --header 'Accept: */*' \
>   --header 'Content-Type: application/json' \
>   --header 'Api-Key: <REDACTED>' \
>   --user-agent 'IINA v1.3.3' | jq | grep -e null -e '"subtitle_id' | grep --before-context=1 null | grep -v -- --
        "subtitle_id": "7177003",
          "tmdb_id": null,
        "subtitle_id": "7177002",
          "tmdb_id": null,
        "subtitle_id": "7224325",
          "uploader_id": null,
low-batt@gag ~$ 

low-batt@gag ~$ curl --location --silent 'https://api.opensubtitles.com/api/v1/subtitles?languages=en&query=Armageddon.mp4' \
>   --header 'Accept: */*' \
>   --header 'Content-Type: application/json' \
>   --header 'Api-Key: <REDACTED>' \
>   --user-agent 'IINA v1.3.3' | jq | grep -e null -e '"subtitle_id' | grep --before-context=1 null | grep -v -- --
        "subtitle_id": "4383085",
        "comments": null,
        "subtitle_id": "4380383",
        "comments": null,
        "subtitle_id": "1925612",
          "tmdb_id": null,
        "subtitle_id": "2703125",
          "tmdb_id": null,
        "subtitle_id": "4381220",
        "comments": null,
        "subtitle_id": "2898835",
          "tmdb_id": null,
        "subtitle_id": "1916624",
        "comments": null,
        "subtitle_id": "1925684",
          "tmdb_id": null,
low-batt@gag ~$ 

low-batt@gag ~$ curl --location --silent 'https://api.opensubtitles.com/api/v1/subtitles?languages=en&query=Poetry.mp4' \
>   --header 'Accept: */*' \
>   --header 'Content-Type: application/json' \
>   --header 'Api-Key: <REDACTED>' \
>   --user-agent 'IINA v1.3.3' | jq | grep -e null -e '"subtitle_id' | grep --before-context=1 null | grep -v -- --
        "subtitle_id": "6234402",
          "uploader_id": null,
        "subtitle_id": "6559152",
          "tmdb_id": null,
          "parent_title": null,
        "subtitle_id": "6559154",
          "tmdb_id": null,
          "parent_title": null,
        "subtitle_id": "5101872",
          "uploader_id": null,
          "tmdb_id": null,
        "subtitle_id": "5101859",
          "uploader_id": null,
          "tmdb_id": null,
        "subtitle_id": "6428207",
          "tmdb_id": null,
low-batt@gag ~$ 

low-batt@gag ~$ curl --location --silent 'https://api.opensubtitles.com/api/v1/subtitles?languages=en&query=Klem.mp4' \
>   --header 'Accept: */*' \
>   --header 'Content-Type: application/json' \
>   --header 'Api-Key: <REDACTED>' \
>   --user-agent 'IINA v1.3.3' | jq | grep -e null -e '"subtitle_id' | grep --before-context=1 null | grep -v -- --
        "subtitle_id": "7201901",
        "from_trusted": null,
        "legacy_subtitle_id": null,
          "uploader_id": null,
low-batt@gag ~$ 

low-batt@gag ~$ curl --location --silent 'https://api.opensubtitles.com/api/v1/subtitles?languages=en&query=Vikings.mp4' \
>   --header 'Accept: */*' \
>   --header 'Content-Type: application/json' \
>   --header 'Api-Key: <REDACTED>' \
>   --user-agent 'IINA v1.3.3' | jq | grep -e null -e '"subtitle_id' | grep --before-context=1 null | grep -v -- --
        "subtitle_id": "5194209",
          "year": null,
        "subtitle_id": "5151274",
          "year": null,
        "subtitle_id": "5151224",
          "year": null,
low-batt@gag ~$
2

Hi,

no sorry we couldn’t keep a track of that, titles can indeed have more or less fields that are empty, there should be a way to handle this in your library because it is a very standard behavior for an API, loads of values are null loading from API’s such as themoviedb for example

cheers
os_dev

3

Understood. I will update my code accordingly.

Given this answer the REST API JSON model documentation should be updated to indicate these properties are “optional”. Currently every property is documented as “required”, which implies values are guaranteed to be present.