External References ($ref)

Referencing Schemas

The $ref keyword lets you reuse definitions instead of duplicating them. Reference schemas within the same file, from external files, or from URLs.

Key Concepts
  • • Internal refs - Point to definitions in the same file
  • • External file refs - Point to separate YAML/JSON files
  • • URL refs - Point to hosted specifications
  • • JSON Pointer - The path syntax after the #

Internal References

Most Common

Reference definitions within the same OpenAPI document using JSON Pointer notation.

Standard Paths
# Reference a schema
$ref: '#/components/schemas/User'
# Reference a response
$ref: '#/components/responses/NotFound'
# Reference a parameter
$ref: '#/components/parameters/PageSize'
# Reference a request body
$ref: '#/components/requestBodies/UserInput'
# Reference a security scheme
$ref: '#/components/securitySchemes/BearerAuth'
Complete Example
components:
schemas:
User:
type: object
properties:
id:
type: integer
name:
type: string
paths:
/users/{id}:
get:
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/User'

External File References

Modular

Reference schemas from separate files. Useful for organizing large specifications or sharing common schemas across multiple APIs.

Relative Path
# Reference schema in sibling file
$ref: './schemas/User.yaml'
# Reference specific definition
$ref: './common.yaml#/definitions/Error'
# Parent directory
$ref: '../shared/types.yaml#/Address'
File Structure Example
api/
openapi.yaml # Main spec
schemas/
User.yaml
Order.yaml
responses/
errors.yaml
parameters/
common.yaml
Main Spec with External Refs
# openapi.yaml
openapi: '3.0.3'
info:
title: My API
version: '1.0.0'
paths:
/users:
get:
responses:
'200':
content:
application/json:
schema:
$ref: './schemas/User.yaml'
'404':
$ref: './responses/errors.yaml#/NotFound'

URL References

Remote

Reference schemas from remote URLs. Useful for shared organizational schemas or referencing third-party type definitions.

Examples
# Full URL to a schema
$ref: 'https://api.example.com/schemas/User.yaml'
# With JSON Pointer
$ref: 'https://api.example.com/common.yaml#/definitions/Error'
# Reference from GitHub raw content
$ref: 'https://raw.githubusercontent.com/org/repo/main/schemas/Address.yaml'

Considerations

  • • URL must be accessible (CORS enabled for browser-based tools)
  • • Consider caching - remote changes affect your spec
  • • For stability, pin to specific versions or commits

JSON Pointer Syntax

The path after # uses JSON Pointer (RFC 6901) syntax to navigate the document structure.

Syntax Rules
  • /Separates path segments
  • ~0Escaped tilde (~)
  • ~1Escaped forward slash (/)
  • 0, 1, 2...Array index (zero-based)
Examples
/components/schemas/User
/paths/~1users~1{id}/get
/info/contact/email
/servers/0/url

Referenceable Components

OpenAPI defines specific locations where $ref can be used:

Component TypePathUse For
Schemas#/components/schemas/...Data models
Responses#/components/responses/...Common responses (errors)
Parameters#/components/parameters/...Query/path parameters
Request Bodies#/components/requestBodies/...Shared request payloads
Headers#/components/headers/...Response headers
Security Schemes#/components/securitySchemes/...Auth definitions
Links#/components/links/...Response links
Callbacks#/components/callbacks/...Async callbacks

Circular References

Handle With Care

Schemas can reference themselves (self-referential) or form cycles. This is valid but requires tools to handle recursion properly.

Self-Reference (Tree Node)
TreeNode:
type: object
properties:
value:
type: string
children:
type: array
items:
$ref: '#/components/schemas/TreeNode'
Mutual Reference
Person:
properties:
spouse:
$ref: '#/components/schemas/Person'
employer:
$ref: '#/components/schemas/Company'
Company:
properties:
employees:
type: array
items:
$ref: '#/components/schemas/Person'

Tigrister Handling

Tigrister properly resolves circular references for validation and display. The Preview and Visual Designer show the structure without infinite loops.

Tigrister Resolution Features

Tigrister includes a full-featured $ref resolver with the following capabilities:

Resolution Behavior
  • •Max depth: 10 - Nested refs are resolved up to 10 levels deep
  • •Caching - External documents are cached to prevent duplicate fetches
  • •Circular detection - Circular refs return empty schema to prevent infinite loops
  • •Auto-detect - YAML and JSON are automatically detected and parsed
Error Handling
  • •Graceful fallback - On error, original $ref is preserved
  • •Error collection - All resolution errors are collected and reported
  • •Nested refs - Refs inside external docs are recursively resolved
  • •Network errors - HTTP errors are caught with descriptive messages

Best Practices

Use Descriptive Names

Name schemas clearly: UserResponse vs Userwhen they differ.

Prefer Internal Refs

External refs add complexity. Use them for truly shared schemas, not convenience.

Bundle for Distribution

When sharing your spec, resolve external refs into a single file for reliability.

Avoid Deep Nesting

Keep reference chains shallow. Deep nesting makes specs hard to understand.

Parameter SerializationServer Variables