Fields
Content request are built up of one or more fields. Fields are used both to request a localization of a text, the creation of a text and to deliver contextual information needed to work with a content request.
A field object contains the following values:
| Name | Type | Description |
|---|---|---|
id |
string | Identifier of the field, use this for retrieval of field data and querying of requests. |
name |
string | Human readable name of the field. Optional, id is used if this value is not provided. |
type |
type | How this field should be treated, either internal, context or localizable. Required |
data |
data type | The type of data this field contains, two types are currently supported: string and html. Required |
value |
dynamic | Value of this field. Required for internal, context and localizable, has to be nullfor creatable fields. |
originalValue |
dynamic | Original value of this field. Only readable |
intermediateValue |
dynamic | Intermediate value of this field. Used for things such as machine translation that can deliver unfinished values for early use. Only readable |
Field types
| Name | Description |
|---|---|
internal |
Used for storing data relevant to the submitter but that does not affect the localization and creation of content. |
context |
Contextual information to help writers with localization and content creation. |
localizable |
Used for fields where the value should be localized into another language. |
creatable |
Used for fields where content should be created based on context and hints. |
Data types
| Name | Description |
|---|---|
string |
String of text - no formatting and will not be encoded. JSON data is expected to be a string. |
html |
HTML formatted text, needs to be a valid HTML fragment and will be returned HTML encoded. JSON data is expected to be a string. |
html:relaxed |
Like html but will not use strong validation. |
HTML can be messy and our html type uses strong validation to help us write correct HTML.
This means that we will validate against the same rules that the
W3C Markup Validation Service uses. In certain cases the markup
you want to send us might not validate, in which case you can switch to html:relaxed to avoid the
use of strong validation.
Hints
Hints can be placed on fields to help with creating better content for you.
There are both soft hints, such as target word count and harder ones such as a
maximum length to enforce at datababse limit. Different types of fields can
support different types of hints. Hints are specified via an array on the field
named hints. Example:
{
"id": "title",
"type": "localizable",
"data": "string",
"value": "Produkter",
"hints": [
{
"type": "length",
"max": 400
}
]
}
Length limit
Limit the length of the text in a field.
Type: length
Use: Works for localizable and creatable fields.
| Argument | Description |
|---|---|
around |
Optional length of the text, used as an indicator of a desired length, but the finished text can be shorter than this text. |
max |
Optional maximum length of the returned text. The finished text will never be longer than this. |
Word count
Set a target on the number of words a text should have.
Type: word-count
Use: Only with field type creatable.
| Argument | Description |
|---|---|
around |
Number of words that the created text should aim for. Used as an indicator on how many words the text should have, but a returned text is allowed to have less words. |
Free text
Ties some free text information to a field, similar to context but scoped to a single field.
Type: free-text
Use: Works for localizable and creatable fields.
| Argument | Description |
|---|---|
text |
The text that should be associated with this field. |
Examples of fields
Internal field, that can be queried but is not visible during localization and content creation:
{
"id": "database-id",
"type": "internal",
"data": "string",
"value": "1457355474317"
}
Context field, can be queried and is shown during localization and content creation:
{
"id": "product-type",
"type": "context",
"data": "string",
"value": "Coffee Brewer"
}
Localizable field, can be queried and should be localized:
{
"id": "product-listing-text",
"type": "localizable",
"data": "html",
"value": "Coffee Brewer with integrated timer & automatic shut down."
}
Retrieve a localized field:
{
"id": "product-listing-text",
"type": "localizable",
"data": "html",
"value": "Kaffebryggare med integrerad timer & automatisk avstängning.",
"originalValue": "Coffee Brewer with integrated timer & automatic shut down."
}
Creatable field with a few hints:
{
"id": "short description",
"type": "creatable",
"data": "html",
"hints": [
{
"type": "free-text",
"text": "Summarize product description"
},
{
"type": "word-count",
"around": 100
}
]
}
Retrieve a creatable field:
{
"id": "short description",
"type": "creatable",
"data": "html",
"value": "Coffee Brewer with integrated timer & automatic shut down.",
"hints": [
{
"type": "free-text",
"text": "Summarize product description"
},
{
"type": "word-count",
"around": 100
}
]
}