add additional differences to fileformat doc (#90)

deckformat/fileformat.md

@@ -28,20 +28,27 @@ The best available description can be generated by using the Kong CLI with the "
 
 ### Metadata
 
-The DBLess format specifies metadata fields (fieldnames starting with an underscore; `"_"`). It supports the
+The format specifies metadata fields (fieldnames starting with an underscore; `"_"`). It supports the
 following metadata fields:
 
-| Field | decK | DBLess | description
-|-|-|-|-
-| `_format_version` | yes | yes | the format of the file, only supported on the root-object in the file.
-| `_transform` | yes| yes | whether field transforms should still be applied or not, only supported on the root-object in the file.
-| `_comment` | no | yes | a string field supporting opaque data to be stored in the same file, to be ignored by Kong. This field can be present on any entity (including the root-object) in the file.
-| `_ignore` | no | yes | an array field supporting opaque data to be stored in the same file, to be ignored by Kong. This field can be present on any entity (including the root-object) in the file.
-| `_workspace` | yes | no | To specify, in the deck file, the target workspace (only supported on the root-object in the file).
+| Field | decK/Kong | decK/Konnect |DBLess | description
+|-|-|-|-|-
+| `_format_version` | yes | yes | yes | the format of the file
+| `_transform` | yes| yes | yes | whether field transforms should still be applied or not
+| `_comment` | no | no | yes | a string field supporting opaque data to be stored in the same file, to be ignored by Kong. This field can be present on any entity (including the root-object) in the file.
+| `_ignore` | no | no | yes | an array field supporting opaque data to be stored in the same file, to be ignored by Kong. This field can be present on any entity (including the root-object) in the file.
+| `_workspace` | yes | no | no | To specify, in the deck file, the target workspace
+| `_info` |yes | yes | no | An object with file-level metadata.
+| `_info.select_tags` | yes | yes | no | The select tags (an array) to use when syncing/diffing this file using deck
+| `_info.defaults` | yes | yes | no | Defaults for entities.
+| `_konnect` | no | yes | no | An object with file-level metadata, specific to Konnect
+| `_konnect.control_plane_name` | no | yes | no | The control-plane to target.
+
 
 ### Explicit incompatibilities
 
 Around the "Consumer groups" feature some fields have explicitly different names in both formats. See this [Jira ticket](https://konghq.atlassian.net/browse/FTI-4808?focusedCommentId=93327).
+This seems related to the many-to-many relations ship, since the ACL plugin has the same issue.
 
 | decK | DBless | format |
 |-|-|-|
@@ -56,8 +63,8 @@ Around the "Consumer groups" feature some fields have explicitly different names
 || *Conversion*: </br>* rename `consumer_groups[*].consumer_group_plugins` to `consumer_groups[*].plugins` (possibly merge if it already exists) </br>* iterate over `consumer_group_plugins`, </br>* for each entry find the related `consumer_group` entry, </br>* append the entry to the `plugins` array in that entry (create array if it doesn't exist).|
 || *Issues*: to specify a plugin for a group, the group itself **must be defined in the same file** in the `decK` format (since it must be nested). With the Kong format one could simply only have the plugin in `consumer_group_plugins` but that one does not exist in the `decK` format.|
 |||
-| `consumer_group_consumers` | Does not exist, they are sub-entries in `consumers`. </br>*Note 1*: the target field is called `groups` (and hence this is inconsistent with standard entity relations, since this is a many-to-many relation which the DBLess relations are not allowed to be nested). </br>*Note 2*: the name is `groups` but by convention should have been `consumer_groups` (to match the foreign entity name) </br>*Note 3*: the foreign key entries are strings with an ID, but since this is many-to-many it is an array field</br>*Note 4*: the entries in the array should have been simple strings referencing an unique field in the `consumer_groups` table, by `id` or `name`, but for some unknown reason the entries are objects with a key `name` (possibly `id` could also work???, maybe even the entire entity?)|
-|| *Conversion*: </br>* iterate over `consumer_group_consumers` </br>* for each entry find the related `consumer` </br>* create a `groups` array in the `consumer` object if it doesn't exist </br>* insert into the `groups` array a new object with a single key `name` and the value being `consumer_group_consumer.consumer`|
+| `consumer_group_consumers` | Does not exist, they are sub-entries in `consumers`. </br>*Note 1*: the target field is called `groups` (and hence this is inconsistent with standard entity relations, since this is a many-to-many relation which the DBLess relations are not allowed to be nested). </br>*Note 2*: the name is `groups` but by convention should have been `consumer_groups` (to match the foreign entity name) </br>*Note 3*: the foreign key entries are strings with an ID, but since this is many-to-many it is an array field</br>*Note 4*: the entries in the array should have been simple strings referencing an unique field in the `consumer_groups` table, by `id` or `name`, but are objects with a single key `name`. The reason for this object is most likely to be able to add tags to the object (which wouldn't be possible of it were only a string-value) |
+|| *Conversion*: </br>* iterate over `consumer_group_consumers` </br>* for each entry find the related `consumer` </br>* create a `groups` array in the `consumer` object if it doesn't exist </br>* insert into the `groups` array a new object with a single key `name` and the value being `consumer_group_consumer.consumer` </br>* add the appropriate tags|
 || *Issues*: the consumer **must be defined in the same file** in the `decK` format (since group-membership is nested within consumer). With the Kong format one could simply only have the membership in `consumer_group_consumers` but that one does not exist in the `decK` format.|