Trying to make sense of Integrations doc and Notion sample Integration app 😢

So many questions! After many weeks I still have not gotten relations to work in my custom integration. :slightly_frowning_face: This explains why:

:question: When to use “array[text]” field type?

The array[text] field type is mentioned in the Integration docs, but never explained.

:point_right: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"

:point_right: 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?

:point_right: 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?

:question: Schema structure confusion

The Integration doc describes the schema object as:

Schema is JSON object where key is field and value if field description.

:point_right:I think this means “a key is a Type ID and its value is the Type’s definition”.

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.

:point_right:What are the rules and uses for adding additional custom properties to our schema?

:question: 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.

:question: Confusing relations documentation

  • :point_right:Cardinality: Why is there no “one-to-many” option? How to define one-to-many relations?

  • :point_right:How about one-to-one relations? These are very important, but there is no mention.

  • :point_right: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?

  • :point_right: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?

  • :point_right: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?

  • :point_right: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?

  • :point_right: Sometimes Fibery renames a field by prefixing it with the name of the integration. Why?

  • :point_right: How to use Single- and Multi-Select fields?

:question: 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.

:point_right:Could we get updated documentation for this endpoint that describes all the data passed?

:question: Webhooks

The Integrations API description of Webhooks does not explain how to use webhooks.

:point_right:Could we get updated documentation for Integration API Webhooks that includes some use cases and examples?

1 Like

Agree that more documentation would be helpful! In case it’s helpful while you’re waiting for a comprehensive response, I’ve discovered the answers to a couple of these question through trial and error:

  • For relation field type, array[text] seems to only be for many-to-many relations. For many-to-one relations, you can definitely use text. I suspect that it needs to be text (and not a number, date, etc.), but have not tried those.
  • Every one-to-many relation is just the opposite side of a many-to-one relation. So you can define them by adding a many-to-one relation to the type on the other side of the relation.
1 Like

Hello, @Matt_Blais

Thanks for feedback. Indeed relations mapping and our api is not a simple thing to understand and we need to provide more examples and make our documentation more friendly.

Regarding arrayPath. It is used by Notion connector itself only: app/notion.api.js · main · fibery-community / Notion App · GitLab

Thanks again for rising this important topic. We need to fix docs for sure.

1 Like

Thank you for bearing with me in my frustration.

I have figured it out now - at least, enough of it that it is now working as expected in my Integration (finally!).

I believe I could write the “missing” conceptual overview on implementing relations in the Integration app, which would have saved me much time and frustration.

Many of my questions are still unanswered and pertinent, though - e.g.: “How do we implement one-to-one relations?”

Hello, @Matt_Blais

Unfortunately it is not supported. Probably the reason is that one-to-one never came up for our connectors.

Sorry for inconvenience, will need to support it as well.


1 Like