Вопрос о схеме JSON и синтаксисе для... вложенного массива?

Вопрос о схеме JSON и синтаксисе для… вложенного массива?

На чтение 4 мин Опубликовано 15.10.2024

Содержание

Вопрос или проблема
Ответ или решение
Объяснение внесённых изменений:
Пример вызова API

Вопрос или проблема

Мне сложно работать с JSON-схемой, используемой для вызовов API (похожей на следующую, но для небольшого проекта: https://docs.databricks.com/en/machine-learning/model-serving/function-calling.html). В моем случае я пытаюсь создать схему, которая будет направлять вызовы API для получения данных о хранении природного газа. Название схемы будет относиться к функции API, а параметры схемы будут спецификациями параметров для API.

API: https://www.eia.gov/opendata/browser/natural-gas/stor/cap

Проблема заключается в “фасетах” – есть четыре категории фасетов: “duoarea”, “process”, “product” и “series”. Выбрав, например, “duoarea”, я смогу выбрать из списка, выбрав “NUS” и “R48”. Я думаю, что это привело к массиву внутри массива, но я не знаю достаточно о JSON, чтобы выразить это в схеме, что приводит к неправильному вызову.

Моя схема:

{
    "name": "NaturalGasStorage",
    "description": "Емкость хранения природного газа",
    "parameters": {
        "type": "object",
        "properties": {
            "frequency": {
                "type": "string",
                "description": "Частота",
                "enum": ["ежемесячно", "ежегодно"],
                "default": "ежемесячно"
            },
            "data": {
                "type": "array",
                "items": {
                    "type": "string",
                    "enum": ["value"]
                },
                "default": null
            },
            "facets": {
                "type": "array",
                "items": {
                    "type": "string",
                    "enum": ["NUS", "R48"]
                },
                "uniqueItems": true,
                "default": null
            },
            "start": {
                "type": "string",
                "description": "Дата. Пример 2019-12-31",
                "default": null
            },
            "end": {
                "type": "string",
                "description": "Дата. Пример 2019-12-31",
                "default": null
            }
        },
        "required": ["frequency", "data"]
    }
}

Это сгенерировало следующий неправильный вызов – проблема в “фасетах” – у него нет “duoarea” – слоя данных выше “NUS” и “R48”:

[
    {
        "name": "NaturalGasStorage",
        "parameters": {
            "frequency": "monthly",
            "data": ["value"],
            "facets": ["NUS","R48"],
            "start": "2022-12-31",
            "end": "2023-12-31"
        }
    }
]

Правильный вызов ниже – похоже, я не реализовал массив внутри массива / вложенный массив – в интерфейсе API мне нужно выбрать “duoarea”, затем открывается выбор, который позволяет мне выбрать “NUS” и “R48”:

"parameters": {
    "frequency": "monthly",
    "data": ["value"],
    "facets": {"duoarea": ["NUS","R48"]},
    "start": null,
    "end": null,
}

Какой правильный синтаксис в JSON-схеме, чтобы разрешить правильное поведение (с “duoarea” в “facets”)?

Спасибо!

Ответ или решение

Чтобы исправить вашу проблему с JSON-схемой и воплотить вложенные массивы, необходимо в вашем текущем определении свойства "facets" добавить новый уровень вложенности. В вашем случае требуется, чтобы "facets" содержал объект, в котором ключом будет категория (например, "duoarea"), а значением — массив, в котором будут находиться соответствующие элементы (например, "NUS" и "R48").

Ниже приведён откорректированный вариант вашей схемы JSON:

{
    "name": "NaturalGasStorage",
    "description": "Natural Gas Storage Capacity",
    "parameters": {
        "type": "object",
        "properties": {
            "frequency": {
                "type": "string",
                "description": "Frequency",
                "enum": ["monthly", "annual"],
                "default": "monthly"
            },
            "data": {
                "type": "array",
                "items": {
                    "type": "string",
                    "enum": ["value"]
                },
                "default": null
            },
            "facets": {
                "type": "object",
                "properties": {
                    "duoarea": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": ["NUS", "R48"]
                        },
                        "uniqueItems": true,
                        "default": null
                    }
                },
                "required": ["duoarea"],
                "additionalProperties": false
            },
            "start": {
                "type": "string",
                "description": "Date. Example: 2019-12-31",
                "default": null
            },
            "end": {
                "type": "string",
                "description": "Date. Example: 2019-12-31",
                "default": null
            }
        },
        "required": ["frequency", "data", "facets"]
    }
}

Объяснение внесённых изменений:

Тип facets: Изменили тип "facets" с массива на объект, что позволит иметь ключи (категории) и значения (массивы значений).
Ключ duoarea: Внутри свойства "facets" добавлено свойство "duoarea", которое является массивом строк (перечисление значений "NUS", "R48"). Это соответствует вашему желаемому формату вызова API.
Required: Теперь "facets" является обязательным полем в объекте параметров. Кроме того, требуется, чтобы "duoarea" присутствовало внутри "facets".
Дополнительные свойства: Установлено значение false для additionalProperties, что гарантирует, что не будут допустимы дополнительные категории фасетов кроме "duoarea".

Пример вызова API

После внесения всех вышеупомянутых изменений ваш вызов API должен выглядеть так:

[
    {
        "name": "NaturalGasStorage",
        "parameters": {
            "frequency": "monthly",
            "data": ["value"],
            "facets": {
                "duoarea": ["NUS", "R48"]
            },
            "start": "2022-12-31",
            "end": "2023-12-31"
        }
    }
]

Таким образом, вы сможете корректно обрабатывать вложенные массивы и избежать ошибок в запросах к API. Если у вас возникнут дополнительные вопросы или потребуется углублённое объяснение работы с JSON-схемами, не стесняйтесь спрашивать.