It's Time to Move to OAS: What ACB's New Fragment Scaffolding Changes

For a while now, I've been telling teams the same thing: move from RAML to OAS. It's the direction MuleSoft is pushing, and it's the industry standard. But every time someone asked me "what about Data Type Fragments?", I had a weak answer. RAML made schema reuse easy. OAS, until now, made it harder — especially inside Anypoint Code Builder.

That gap just closed.

The update#

Anypoint Code Builder now scaffolds OAS 3.0 API specifications that use $ref to reference Anypoint Exchange fragments.

• ACB release notes
• Creating and using API Spec Fragments

The scenario I tested#

I wanted to see the full flow, not just read about it.

Step 1 — Build the fragment

I created an API Fragment in ACB, type OAS, called Financial Account. Inside it, I defined one schema with the properties I'd expect on a shared CDM entity:

openapi: 3.0.0
info:
  version: 1.0.0
  title: Financial Account
paths: {}
components:
  schemas:
    FinancialAccount:
      type: object
      description: Represents a financial account held at a financial institution.
      properties:
        accountId:
          type: string
        accountNumber:
          type: string
        accountType:
          type: string
        currency:
          type: string
        balance:
          type: number
          format: double
        ownerId:
          type: string
        institutionName:
          type: string
        openedDate:
          type: string
          format: date
        status:
          type: string
        interestRate:
          type: number
          format: double

I published it to Anypoint Exchange.

Step 2 — Reuse it in a Process API

Next, I created a Financial Account Process API, also OAS, and imported the fragment directly from Exchange by searching for "Financial Account." In my POST /accounts and GET /accounts/{accountNumber} operations, I referenced the shared schema like this:

schema:
  $ref: 'exchange_modules/b9e77a07-589b-4461-aa60-5f8ca0b647fb/financial-account/1.0.0/financial-account.yaml#/components/schemas/FinancialAccount'

This is the same pattern I used to build with RAML Data Type Fragments: one CDM model, referenced everywhere it's needed, instead of the same schema copy-pasted and drifting apart across specs.

Step 3 — Scaffold the implementation

After I published the Process API, ACB asked if I wanted to move to implementation. I said yes. ACB scaffolded a new project directly from the OAS spec — with the fragment reference intact.

Step 4 — Validate it

I ran the generated stub and called it from Bruno. The requests validated correctly against the referenced schema. No manual patching, no surprises.

The verdict#

This is the moment to move to OAS. It's not the newest version of the spec on the market, but it's the industry standard, it's more widely adopted than RAML, and it now has a clear path for fragment reuse inside ACB.

One more observation from testing this: I ran the whole scenario with the help of MuleSoft Vibes, and it handled both the fragment and the API spec without issues. OAS is already well understood by the model — an advantage over RAML when you pair AI assistance with spec design.

Links#

• ACB release notes
• Creating and using API Spec Fragments
• Source code