---
title: "References"
description: "Learn about using JSON Schema $ref markup for referencing and reusing definitions, with Alpaca extensions for enhanced flexibility. (Gitana 4.0)"
product: "Gitana"
version: "4.0"
url: "/documentation/gitana/4.0/forms/api/references"
---

# References

This page shows examples of using JSON schema `$ref` markup to reference definitions and other structures within your JSON schema definition to generate more complex and nested schema documents.

The `$ref` convention used by Alpaca builds on top of JSON schema and allows for the `$ref` value to identify a URI to a remote resource. It also allows you to point to JSON structures within the current document, enabling re-use.

Alpaca extends `$ref` by allowing for additional loaders such as a dictionary definition loader for Cloud CMS. Alpaca lets you register [Connectors](/documentation/gitana/4.0/forms/api/connectors.md) to handle loading of your custom `$ref` values.

Alpaca also lets you use `$ref` structures within your options blocks. This lets you load options from remote sources and reuse configuration across your forms.

By default, if Alpaca encounters a `$ref` in your schema, it looks to see if there is a corresponding `$ref` in your options. That is, unless you provide a specific `$ref` in your options for the same block, in which case it will use that instead.

If you are using alpaca in CloudCMS, you can use references to refer to other content types by their qnames. Learn more here:

[https://gitana.io/documentation/gitana/4.0/forms/cms/references](https://gitana.io/documentation/gitana/4.0/forms/cms/references "https://gitana.io/documentation/gitana/4.0/forms/cms/references")

[https://gitana.io/documentation/gitana/4.0/engine/content-models/references](https://gitana.io/documentation/gitana/4.0/engine/content-models/references "https://gitana.io/documentation/gitana/4.0/engine/content-models/references")

## Examples

### Example #1: Nested Tree (using Array)

This example demonstrates the use of JSON Schema referencing to include or pull in schema definitions from other parts of the document. Alpaca supports referencing within the same document using simple ids.

In this example, we allow the end user to create a tree structure of repeated leaf elements that can be nested as many levels deep as they wish.

### Example #2: Deeply Nested Tree (loaded from data)

This example shows a deeply nested tree loaded with data. Note that unlike the previous example, this example uses a non-'create' view which allows data to bind.

### Example #3: Internal Definitions

Here is an example of an object that derives one of its sub-object properties from a referenced definition. The definition is stored in a special `definitions` sub-object of the schema. This definitions sub-object anticipates support for JSON Schema v4.

### Example #4: Using `$ref` within options

Suppose that you have a remote Author schema and options and that their URIs are:

- [/data/author-schema.json](/data/author-schema.json "/data/author-schema.json")
- [/data/author-options.json](/data/author-options.json "/data/author-options.json")

Let's define an article that reuses the Author schema and options via `$ref` like this: