Add missing things to metadata extraction

Author: tilenkavcic

fern/docs/pages/airdrop/metadata-extraction.mdx

@@ -7,6 +7,16 @@ The extraction function of the snap-in must provide a valid metadata file.
 DevRev provides a JSON schema and a CLI tool [chef-cli](https://github.com/devrev/adaas-chef-cli)
 to validate the proposed schema.
 
+## Validating metadata
+
+To check the metadata for internal consistency, you should use the following command after every step:
+
+```bash
+chef-cli validate-metadata < metadata.json
+```
+
+This will output any problems there may be with the metadata file.
+
 ## Triggering event
 
 Airdrop initiates the metadata extraction by starting the snap-in with a message with an event
@@ -48,7 +58,7 @@ For best results:
 - Use referentially consistent example data if possible
 - Make sure IDs are strings, not numbers
 
-This generated metadata serves as a starting point that will need further refinement.
+This generated metadata serves as a starting point that will need further refinement. It can be used to prototype initial domain mappings (by running a sync with it) and to generate example normalized data, but it is still just a guess: It has to be reviewed and refined.
 
 ## Craft the metadata declaration
 
@@ -169,6 +179,7 @@ be changed by the end user at any time, such as mandatory fields or custom field
   ### Declare fields for each record type
 
     Fields' keys must match what is actually found in the extracted data in the artifacts.
+    Note that field keys are case-sensitive.
 
     The supported types are:
     - `bool`
@@ -183,19 +194,22 @@ be changed by the end user at any time, such as mandatory fields or custom field
     - `timestamp`
     - `struct`
 
+    For a detailed explanation of these supported types, refer to the [supported types page](./supported_types.md).
+
     If the external system supports custom fields, the set of custom fields in each record type
     you wish to extract must be declared too.
 
     Enum fields' set of possible values can often be customizable.
     A good practice is to retrieve the set of possible values for all enum fields from the external
-    system's APIs in each sync run.
+    system's APIs in each sync run. You can mark specific enum values as deprecated using the `is_deprecated` property.
 
     `ID` (primary key) of the record, `created_date`, and `modified_date` must not be declared.
 
     Example:
 
     ```json
     {
+      "schema_version": "v0.2.0",
       "record_types": {
         "issues_stock_epic": {
           "name": "Epic",
@@ -237,7 +251,8 @@ be changed by the end user at any time, such as mandatory fields or custom field
                     "key": "P-1"
                   },
                   {
-                    "key": "P-2"
+                    "key": "P-2",
+                    "is_deprecated": true
                   }
                 ]
               }
@@ -323,22 +338,24 @@ be changed by the end user at any time, such as mandatory fields or custom field
   External system fields that shouldn't be mapped in reverse should be marked as `is_read_only`. 
   Depending on their purpose you can also mark fields as `is_indexed`, `is_identifier`, `is_filterable`, 
   `is_write_only` etc. By default these will be set to false. You can find the full list of supported 
-  field attributes and their descriptions in the [metadata schema](./external_domain_metadata_schema.json).
+  field attributes and their descriptions in the `external_domain_metadata_schema.json`.
 
   ### Configure state transitions
 
   If an external record type has some concept of states, between which only certain transitions are 
   possible (e.g., to move to the 'resolved' status, an issue first has to be 'in_testing'), you 
   can declare these in the metadata too.
 
-  This will allow creation of a matching 'stage diagram' in DevRev, which enables a much simpler 
-  import and a closer preservation of the external data than mapping to DevRev's builtin stages.
+  This will allow creation of a matching 'stage diagram' (a collection of stages and their permitted 
+  transitions) in DevRev, which enables a much simpler import and a closer preservation of the external 
+  data than mapping to DevRev's builtin stages.
 
   This is especially important for two-way sync, as setting the transitions correctly ensures that 
   the transitions a record undergoes in DevRev can be replicated in the external system.
 
   To declare this in the metadata, make sure the status is represented as an enum field, and then 
-  declare the allowed transitions:
+  declare the allowed transitions (which you might have to retrieve from an API at runtime, if they 
+  are also customized):
 
   ```json
   {
@@ -409,8 +426,9 @@ be changed by the end user at any time, such as mandatory fields or custom field
 
   In the above example:
   - The status field is the controlling field of the stage diagram
-  - If a status field has no explicit transitions but you still want a stage diagram, set `all_transitions_allowed` to `true`
+  - If a status field has no explicit transitions but you still want a stage diagram, set `all_transitions_allowed` to `true`, which will create a diagram where all the defined stages can transition to each other
   - External systems may categorize statuses (like Jira's status categories), which can be included in the diagram metadata (`states` in the example)
-  - The `starting_stage` defines the initial stage for new object instances
+  - The `starting_stage` defines the initial stage for new object instances. This data should always be provided if available, otherwise the starting stage will be selected alphabetically
   - In current metadata format (v0.2.0), the order and human-readable name are taken from the enum values defined on the controlling field
+  - If the `states` field is not provided, default DevRev states will be used: `open`, `in_progress` and `closed`
 </Steps>