add sharing examples

Author: Formato Post Instagram

v3/openapi.yaml

@@ -1491,6 +1491,13 @@ components:
  description: Flat map of attribute names to single values.
  additionalProperties: true
  example: { node_type: pole, scid: "001" }
+ SharingMap:
+ type: object
+ description: Flat map of company id to permission level (`read` or `write`). The owner company is added automatically.
+ additionalProperties:
+ type: string
+ enum: [read, write]
+ example: { "-OExampleCompanyId": write }
  PixelSelection:
  type: object
  properties:
@@ -1530,15 +1537,15 @@ components:
  model: { type: string, description: Model of the job (stored on `job_creator`). }
  map_styles: { type: string, description: Map style for the job (e.g. `default`). }
  metadata: { type: object, additionalProperties: true, description: Flat map of job metadata. }
- sharing: { type: object, additionalProperties: true, description: Flat map of sharing settings; owner company is added automatically. }
+ sharing: { $ref: '#/components/schemas/SharingMap', description: 'Flat map of company id to permission (`read` or `write`); the owner company is added automatically. See [Sharing](#sharing).' }
  UpdateJobBody:
  type: object
  properties:
  name: { type: string, description: Name of the job. }
  model: { type: string, description: Model of the job. }
  map_styles: { type: string, description: Map style for the job (e.g. `default`). }
  metadata: { type: object, additionalProperties: true, description: Flat map of job metadata. }
- sharing: { type: object, additionalProperties: true, description: Flat map of sharing settings. }
+ sharing: { $ref: '#/components/schemas/SharingMap', description: 'Flat map of company id to permission (`read` or `write`); the owner company is added automatically. See [Sharing](#sharing).' }
 
  Node:
  type: object

v3/reference/jobs.md

@@ -51,7 +51,7 @@ Body fields:
 | `model` | string | ✓ | Model of the job (stored on `job_creator`). |
 | `map_styles` | string | | Map style for the job (e.g. `default`). |
 | `metadata` | object | | Flat map of job metadata. |
-| `sharing` | object | | Flat map of sharing settings; owner company is added automatically. |
+| `sharing` | object | | Flat map of company id to permission (`read` or `write`); the owner company is added automatically. See [Sharing](#sharing). |
 
 ### Get a job (partial data)
 
@@ -97,7 +97,7 @@ Body fields:
 | `model` | string | | Model of the job. |
 | `map_styles` | string | | Map style for the job (e.g. `default`). |
 | `metadata` | object | | Flat map of job metadata. |
-| `sharing` | object | | Flat map of sharing settings. |
+| `sharing` | object | | Flat map of company id to permission (`read` or `write`); the owner company is added automatically. See [Sharing](#sharing). |
 
 ### Raw job write
 
@@ -168,3 +168,24 @@ through large result sets.
 
 Set `list=true` for lightweight list entries; `metadataFilter` does not apply in
 that mode. `includeArchived=true` includes archived jobs either way.
+
+## Sharing
+
+`sharing` controls which companies can access a job. It is a flat map of
+**company id** to permission level — either `read` or `write`. The owner
+company is added automatically, so list only the *other* companies you are
+sharing with. Omit `sharing` (or send `{}`) to share the job with the owner
+company only.
+
+```json
+{
+ "name": "Pole audit — Q3",
+ "model": "-OModelKey...",
+ "sharing": {
+ "-OAcmeCompanyId...": "write",
+ "-OBetaCompanyId...": "read"
+ }
+}
+```
+
+Any value other than `read` or `write` is invalid.