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 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 look 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:


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.

{% raw %} {% endraw %}

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.

{% raw %} {% endraw %}

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.

{% raw %} {% endraw %}

Example #4: Using $ref within options

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

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

{% raw %} {% endraw %}