Update reference-spec.md

articles/modeling/polymorphic-objects.md

@@ -1,44 +0,0 @@
-# Polymorphic Objects 
-
-## What 
-
-- Resources in your API are polymorphic. They can be returned as XML or JSON and can have a flexible amount of fields. You can also have requests and responses in your API design that can be depicted by a number of alternative schemas. 
-- **Polymorphism** is the capacity to present the same interface for differing underlying forms. 
-- The **discriminator** keyword is used to designate the name of the property that decides which schema definition validates the structure of the model. 
-
-## Why 
-- Polymorphism permits combining and extending model definitions. 
-
-## Best Practices
-
-<!-- theme: warning -->
->The discriminator property **must** be a mandatory or required field. When it is used, the value **must** be the name of the schema or any schema that inherits it. 
-
-### Example 
-
-```
-{
-  definitions:
-  Vehicle:
-    type: object, 
-    discriminator: brand
-    properties:
-      model:
-        type: string
-      color:
-        type: string
-      required:
-    model
-    
-  Sedan: # Sedan is used as the discriminator value 
-  
-    allOf:
-      $ref: '#/definitions/Vehicle'
-      type: object
-        properties:
-          dateManufactured: 
-            type: date
-          required: 
-            dateManufactured
-}
-```

articles/modeling/reference-spec.md

@@ -1 +1,43 @@
+# Referencing Another API Specification
 
+<!-- REFBUILDER GIF/VIDEO-->
+
+## What
+
+Referencing another specification allows for cleaner and more organized code. Some use cases are as follows:
+
+* Generate API documentaion in Hubs
+* Deduplicate common structures like responses or shared parameters in Modeling
+* Test a connected API specification in Scenarios
+* Setup a mock server for an API in Prism
+
+## How
+
+1.  Choose the **source**
+
+    * This File
+
+    * This Project
+
+      * Select a **file**
+
+    * Shared/Common
+
+    * External URL
+
+      * Enter a valid **URL** to an existing specification
+
+2.  Select a **target**, if required
+
+3.  Confirm your choice. (Only required if there is a confirm button)
+
+4.  View the referenced specification by clicking the book icon
+
+---
+**Related Links**
+
+* [Reference other Sources](../hubs/ref-other-sources-hubs.md)
+* [Creating Models](../modeling/how-to-create-models.md#How-to-Create-Models-using-the-Stoplight-Modeling-Editor)
+* [Shared Parameters and Responses](../modeling/shared-params-responses.md)
+* [Contract Testing](../testing/contract-testing.md#connecting-the-spec)
+* [Setting Up a Prism Mock Server](../prism/mocking.md)