Вопрос или проблема
Мне сложно работать с 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-схемами, не стесняйтесь спрашивать.