Spec fragments & dependencies

Factor out what repeats

A spec fragment is a reusable piece of a specification published to Exchange as its own asset — a data type, a trait, a security scheme, a library. Other specs declare it as a dependency and pull it in.

RAML example — a shared library consumed via uses

#%RAML 1.0
title: Orders API
uses:
  common: exchange_modules/com.acme/common-types/1.0.0/common-types.raml
/orders:
  post:
    body:
      application/json:
        type: common.Order

Why it matters

• One definition of Order, Error, or Pagination across every API.
• Fix a shared type once; dependents adopt the new version deliberately.
• Smaller, cleaner specs that are easier to review and govern.

Dependencies are versioned

When you add a fragment, Exchange records the exact version as a dependency. Upgrading is an explicit act — you bump the dependency, you do not get silently changed underneath.

Coaching note

Start fragments with the obvious shared shapes — common error envelope, pagination, standard headers. Over-fragmenting early creates ceremony; let reuse emerge from real repetition.