Structured Fields in Resources

Monetary Value

The standardized format for representing currency amounts, consists of two fields: value for the numerical amount and currency for the currency ISO 4217 code. This consistent structure allows for clear and unambiguous representation of monetary values across different resources in the API.

Structure

Field	Type	Description
value	Number	Monetary value in the currency
currency	String	Currency ISO 4217 code (e.g., "EUR")

Example

{
    "price": {
        "currency": "EUR",
        "value": 1.99
    }
}

Structured represenation of the price with a value of 1.99 EUR.

Multi-language Representation Format

The multi-language representation format is a structured approach used in API resources to support multiple languages for specific fields. This format allows fields like name, description, and others to provide data in different languages, enhancing localization and accessibility for diverse audiences.

Structure

Fields that support multi-language representation are arrays of objects, where each object corresponds to a specific language. Each object includes:

Field	Type	Description
language	String	The language code in ISO 639-2 format (e.g., "eng" for English, "ger" for German).
text	String	The value of the field in the specified language.

Example

A field with multi-language support is represented as follows:

"field_name": [
    {
        "language": "eng",
        "text": "Example in English"
    },
    {
        "language": "ger",
        "text": "Beispiel auf Deutsch"
    }
]

In this example, the field contains values in both English (eng) and German (ger).

Notes

If a language-specific value is not available, the name field for that language will be null. Clients consuming the API should handle fallback scenarios (e.g., using a default language) when a language-specific value is unavailable.

Example with Missing Language Data

"city": [
    {
        "language": "eng",
        "text": "Munich"
    },
    {
        "language": "ger",
        "text": null
    }
]

Typed Value Objects

The typed value object structure supports versatile use cases where data items are paired with a type indicator for context and a corresponding value for content.

Structure

A typed value object has following structure:

Field	Type	Description
type	String (required)	A descriptor indicating the category, source, or classification of the data. This allows differentiation between various types of information (e.g., data category, or context-specific label).
value	String (required)	The specific data or identifier corresponding to the type. This value provides the unique or relevant information associated with the given type.

Example

{
    "type": "klopotek",
    "value": "12345"
}