Docs: Add field type examples and permissions examples (#385)

versioned_docs/version-1.2.x/surrealql/statements/define/field.mdx

@@ -65,6 +65,9 @@ DEFINE FIELD metadata ON TABLE user FLEXIBLE TYPE object;
 ```
 
 ### Array type 
+
+You can also set a field to have the array data type. The array data type can be used to store a list of values. You can also set the data type of the array's contents.
+
 ```surql
 -- Set a field to have the array data type
 DEFINE FIELD roles ON TABLE user TYPE array<string>;
@@ -80,21 +83,34 @@ DEFINE FIELD posts.* ON TABLE user TYPE record<string>;
 ```
 ### Making a field optional
 
+You can make a field optional by wrapping the inner type in an `option`, which allows you to store `NONE` values in the field.
+
 ```surql
 -- A user may enter a biography, but it is not required.
 -- By using the option type you also allow for NONE values.
 DEFINE FIELD biography ON TABLE user TYPE option<string>;
 ```
+
+The example below shows how to define a field `user` on a `POST` table. The field is of type [record](/docs/surrealdb/surrealql/datamodel/overview). This means that the field can store a `record<user>` or `NONE`.
+
+```surql
+DEFINE FIELD user ON TABLE POST TYPE option<record<user>>;
+```
+
+
+
 ### Setting a default value
 
+You can set a default value for a field using the `DEFAULT` clause. The default value will be used if no value is provided for the field.
+
 ```surql
 -- A user is not locked by default.
 DEFINE FIELD locked ON TABLE user TYPE bool
 -- Set a default value if empty
 DEFAULT false;
 ```
 
-#### `DEFAULT` inherited from `VALUE`
+### `DEFAULT` inherited from `VALUE`
 
 If the `VALUE` clause contains a static query, meaning not depending on any variables, and in case no `DEFAULT` clause is specified, then the `VALUE` clause will be used as the `DEFAULT` clause aswell.
 
@@ -104,6 +120,9 @@ DEFINE FIELD updated ON resource VALUE time::now();
 
 ### Alter a passed value
 
+You can alter a passed value using the `VALUE` clause. This is useful for altering the value of a field before it is stored in the database. 
+In the example below, the `VALUE` clause is used to ensure that the email address is always stored in lowercase characters by using the [`string::lowercase`](/docs/surrealdb/surrealql/functions/string#stringlowercase) function.
+
 ```surql
 -- Ensure that an email address is always stored in lowercase characters
 DEFINE FIELD email ON TABLE user TYPE string
@@ -112,7 +131,7 @@ DEFINE FIELD email ON TABLE user TYPE string
 
 ## Asserting rules on fields
 
-You can take your field definitions even further by using asserts. Assert is a powerful feature that can be used to ensure that your data remains consistent.
+You can take your field definitions even further by using asserts. Assert can be used to ensure that your data remains consistent. For example you can use asserts to ensure that a field is always a valid email address, or that a number is always positive. 
 
 ### Email is required
 
@@ -125,12 +144,29 @@ DEFINE FIELD email ON TABLE user TYPE string
 
 ### Making a field `READONLY`
 
+The `READONLY` clause can be used to prevent any updates to a field. This is useful for fields that are automatically updated by the system. To make a field `READONLY`, add the `READONLY` clause to the `DEFINE FIELD` statement. As seen in the example below, the `created` field is set to `READONLY`.
+
 ```surql
 DEFINE FIELD created ON resource VALUE time::now() READONLY;
 ```
 
+### Setting permissions on fields
+
+You can set permissions on fields to control who can perform operations on them using the `PERMISSIONS` clause. The `PERMISSIONS` clause can be used to set permissions for `SELECT`, `CREATE`, `UPDATE`, and `DELETE` operations.
+
+```surql
+-- Set permissions for the email field
+DEFINE FIELD email ON TABLE user
+  PERMISSIONS 
+    FOR select WHERE published=true OR user=$auth.id
+    FOR update WHERE user=$auth.id
+    FOR delete WHERE user=$auth.id OR $auth.role="admin";
+```
+
+The `PERMISSIONS` clause can also be used to set permissions for all operations using the `FULL` keyword.
+
 ## Array with allowed values
-By using an Access Control List as an example we can show how we can restrict what values can be stored in an array.
+By using an Access Control List as an example we can show how we can restrict what values can be stored in an array. In this example we are using an array to store the permissions for a user on a resource. The permissions are restricted to a specific set of values.
 
 ```surql
 -- An ACL can be applied to any kind of resource (record)
@@ -177,6 +213,8 @@ CREATE acl SET
 ```
 ## Using RegEX to validate a string
 
+You can use the `ASSERT` clause to apply a regular expression to a field to ensure that it matches a specific pattern. In the example below, the `ASSERT` clause is used to ensure that the `countrycode` field is always a valid ISO-3166 country code.
+
 ```surql
 -- Specify a field on the user table
 DEFINE FIELD countrycode ON user TYPE string