So many questions! After many weeks I still have not gotten relations to work in my custom integration. 
This explains why:
When to use “array[text]” field type?
The array[text] field type is mentioned in the Integration docs, but never explained.
When should “array[text]” be used as the field type in a schema? What does it correspond to in the Fibery front end and back end?
Schema Docs say: "Each type must contain 'name' and 'id' field", giving this example:
{
"repository": {
"id": {
"type": "id",
"name": "Id"
},
"name": {
"type": "text",
"name": "Name"
},
According to this example, the name field should be a simple text field.
But the Notion Integration app passes the following data to Fibery for an entity’s name field content:
"name": [
"ABC Inc. Website"
]
even though the app itself defines the name field type as text in its schema, not array[text]:
"name": {
"name": "Name",
"type": "text",
"path": "properties.Name.title",
"arrayPath": "plain_text"
}
Why does the Notion Integration app pass the name field to Fibery as array[text] when the schema defines it as text? Why does this even work?
What are the requirements for the special id and name fields in the schema? What is flexible, and what must be exactly as described in the doc? Must the id field be unique, and what happens if multiple records are defined with the same value for id?
Schema structure confusion
The Integration doc describes the schema object as:
Schema is JSON object where key is field and value if field description.
I think this means “a key is a Type ID and its value is the Type’s definition”.
Yes?
Also, the doc says nothing about adding miscellaneous undocumented properties to our schema, such as the path and arrayPath properties added by the Notion Integration app.
What are the rules and uses for adding additional custom properties to our schema?
Notion Multi-Select fields become Fibery Text field
In my Notion DB I have a Multiselect “Tags” field, but the sample Notion Integration app translates this into an array[text] field in the generated schema:
"tags": {
"name": "Tags",
"path": "properties.Tags.multi_select",
"type": "array[text]",
"arrayPath": "name"
},
So a Notion Multiselect field becomes just a Fibery Text field.
Why?
Confusing relations documentation
-
Cardinality: Why is there no “one-to-many” option? How to define one-to-many relations?
-
How about one-to-one relations? These are very important, but there is no mention.
-
No discussion of the “hidden fields” created by relations, or how they are related to our explicitly defined fields – or (most importantly) which of these explicit and implicit and visible and hidden fields should actually be present in the entity data we send to Fibery - on each side of a relation?
-
Missing discussion of Relation fields: E.g., What are the requirements for
targetFieldId? Does it have to be “id”, or can it be ANY field, of any type? -
No discussion of the “duplication of relations fields” – e.g., how should we decide which side of a relation to define/keep/remove? If the field for one side of a relation is removed from the schema, should we still send that field’s data to Fibery?
-
What are the rules for the field types to use for relations? E.g., should a relation field be
array[text]even if it only refers to single entity (many-to-one)? Can it be a number, a Date, etc? -
Sometimes Fibery renames a field by prefixing it with the name of the integration. Why?
-
How to use Single- and Multi-Select fields?
Undocumented fields in data requests from Fibery
When Fibery sends data requests to an integration app’s /api/v1/synchronizer/data endpoint some fields can be included in the request that are not described in the documentation.
E.g. a subset of the schema is sometimes included in a data request.
Could we get updated documentation for this endpoint that describes all the data passed?
Webhooks
The Integrations API description of Webhooks does not explain how to use webhooks.