Multiple Languages: The Names Object
Typically, if a piece of text in the API response is intended for display in a client UI, the API schema supports providing that text in multiple languages. This applies not only to synopses, but also to country names, the name of attributes like “Live” and “Subtitled”, etc. The actual set of languages in which the text is supplied depends on the customer’s contract with Simply.TV.
The API does not have separate requests or responses for each language. Each program, contributor etc. document contains all the relevant fields in all the available languages.
For each such field, the values are supplied in one JSON object, often called …Names. The object contains one property for each language, whose name is the (two-character) ISO 639-1 code for the language, and whose value is the relevant piece of text in the relevant language. For example:
"countryNames": {
"de": "Deutschland",
"en": "Germany",
"fr": "Allemagne"
}
Content Instance Attributes Object
Several arrays that store attributes of a program, event etc. are “soft-coded” to allow Simply.TV to expand the set of attributes that the array can list without having to update the formal JSON schema. These include the following: accessServiceAttributes, audioAttributes, videoAttributes and otherAttributes. The
tags array is essentially a special case of an attributes array, while the
rights object has its own attributes array.
At an oversimplified level, each object within an attributes array represents an attribute of the program as a name-value pair, e.g.:
"Original Language": "German"
However, the API schema actually provides (a) a system-generated language-independent ID and (b) a language map object for both the name and the value. The IDs provide values that will not change over time or between API instances, while the language maps provides values that should make sense to a human being. For example, the following array contains a single object indicating that the original language of the program is German:
"audioAttributes": [
{
"attribute": {
"attributeId": "2720000099999",
"attributeNames": {
"en": "Original Language"
}
},
"value": {
"valueId": "de",
"valueNames": {
"en": "German"
}
}
}
]
