Data Schemas
The ForVoyez API allows you to customize the output of the generated metadata by providing a schema in the request. In this section, we'll explore the JSON schema structure, how to customize schemas, and the importance of schema validation.
JSON Schema Structure
The schema you provide in the API request should follow the JSON Schema format. It defines the structure and constraints of the generated metadata. Here's an example of a basic schema:
{
"title": "string",
"alternativeText": "string",
"caption": "string",
"tags": ["string"],
"categories": ["string"]
}
In this example, the schema defines the expected data types for each field. The title
, alternativeText
, and caption
fields are specified as strings, while tags
and categories
are arrays of strings.
Customizing Schemas
You can customize the schema to match your specific requirements. For example, you can add additional fields, specify required fields, or define default values. Here's an example of a customized schema:
{
"title": {
"type": "string",
"required": true
},
"alternativeText": {
"type": "string",
"required": true
},
"caption": {
"type": "string",
"required": false
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"customField": {
"type": "string"
}
}
In this customized schema:
- The
title
andalternativeText
fields are marked as required. - The
caption
field is optional. - The
tags
field is an array of strings with an empty array as the default value. - A custom field named
customField
is added.
To use a customized schema in your API request, include it in the data
parameter as a JSON object. Here are examples using cURL and JavaScript:
curl -X POST \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: multipart/form-data" \
-F "image=@/path/to/your/image.jpg" \
-F "data={\"schema\":{\"title\":{\"type\":\"string\",\"required\":true},\"alternativeText\":{\"type\":\"string\",\"required\":true},\"caption\":{\"type\":\"string\",\"required\":false},\"tags\":{\"type\":\"array\",\"items\":{\"type\":\"string\"},\"default\":[]},\"customField\":{\"type\":\"string\"}}}" \
-F "language=en" \
https://forvoyez.com/api/describe
Note that the language
parameter is now included separately from the data
object in both the cURL and JavaScript examples.
Schema Validation
When providing a custom schema, it's important to ensure that it is valid and well-formed. The ForVoyez API performs schema validation on the server side to check for any structural or type-related issues.
If the provided schema is invalid, the API will return a 400 Bad Request
error with details about the validation errors. Make sure to carefully construct your schema and test it before using it in production.
If you have any questions or need further assistance with data schemas, feel free to reach out to our support team.