Sharing saved objects developer guide

dev_docs/key_concepts/saved_objects.mdx

@@ -72,3 +72,17 @@ Sometimes Saved Objects end up persisted inside another Saved Object. We call th
  issues with edits propagating - since an entity can only exist in a single place.
   Note that from the end user stand point, we don’t use these terms “by reference” and “by value”.
 
+## Sharing Saved Objects
+
+Starting in Kibana 7.12, saved objects can be shared to multiple spaces. The "space behavior" is determined for each object type depending
+on how it is registered.
+
+If you are adding a **new** object type, when you register it:
+
+1. Use `namespaceType: 'multiple-isolated'` to make these objects exist in exactly one space
+2. Use `namespaceType: 'multiple'` to make these objects exist in one *or more* spaces
+3. Use `namespaceType: 'agnostic'` if you want these objects to always exist in all spaces
+
+If you have an **existing** "legacy" object type that is not shareable (using `namespaceType: 'single'`), see the [legacy developer guide
+for Sharing Saved Objects](https://www.elastic.co/guide/en/kibana/master/sharing-saved-objects.html) for details on steps you need to take
+to make sure this is converted to `namespaceType: 'multiple-isolated'` or `namespaceType: 'multiple'` in the 8.0 release.

dev_docs/tutorials/saved_objects.mdx

@@ -19,7 +19,7 @@ import { SavedObjectsType } from 'src/core/server';
 export const dashboardVisualization: SavedObjectsType = {
   name: 'dashboard_visualization', [1]
   hidden: false,
-  namespaceType: 'single',
+  namespaceType: 'multiple-isolated', [2]
   mappings: {
     dynamic: false,
     properties: {
@@ -41,6 +41,10 @@ export const dashboardVisualization: SavedObjectsType = {
 [1] Since the name of a Saved Object type forms part of the url path for the public Saved Objects HTTP API, 
 these should follow our API URL path convention and always be written as snake case.
 
+[2] This field determines "space behavior" -- whether these objects can exist in one space, multiple spaces, or all spaces. This value means
+that objects of this type can only exist in a single space. See
+<DocLink id="kibDevDocsSavedObjectsIntro" section="sharing-saved-objects" text="Sharing Saved Objects"/> for more information.
+
 **src/plugins/my_plugin/server/saved_objects/index.ts**
 
 ```ts

docs/api/saved-objects/resolve.asciidoc

@@ -70,6 +70,8 @@ The `outcome` field may be any of the following:
 * `"aliasMatch"` -- One document with a legacy URL alias matched the given ID; in this case the `saved_object.id` field is different than the given ID.
 * `"conflict"` -- Two documents matched the given ID, one was an exact match and another with a legacy URL alias; in this case the `saved_object` object is the exact match, and the `saved_object.id` field is the same as the given ID.
 
+If the outcome is `"aliasMatch"` or `"conflict"`, the response will also include an `alias_target_id` field. This means that an alias was found for another object, and it describes that other object's ID.
+
 Retrieve a dashboard object in the `testspace` by ID:
 
 [source,sh]
@@ -125,6 +127,7 @@ The API returns the following:
       "dashboard": "7.0.0"
     }
   },
-  "outcome": "conflict"
+  "outcome": "conflict",
+  "alias_target_id": "05becb88-e214-439a-a2ac-15fc783b5d01"
 }
 --------------------------------------------------

docs/developer/advanced/index.asciidoc

@@ -5,11 +5,14 @@
 * <<development-es-snapshots>>
 * <<development-basepath>>
 * <<upgrading-nodejs>>
+* <<sharing-saved-objects>>
 
 include::development-es-snapshots.asciidoc[leveloffset=+1]
 
 include::running-elasticsearch.asciidoc[leveloffset=+1]
 
 include::development-basepath.asciidoc[leveloffset=+1]
 
-include::upgrading-nodejs.asciidoc[leveloffset=+1]
+include::upgrading-nodejs.asciidoc[leveloffset=+1]
+
+include::sharing-saved-objects.asciidoc[leveloffset=+1]