---
schema_version: "1"
id: 9afa69f579e9a5aa53870073d43b0265d9574adf484df68500cc639ab57aae53
title: Guide to Defining Examples in RAML 1.0
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/design-center/design-named-examples.md
canonical_url: https://docs.mulesoft.com/design-center/design-named-examples
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 722179889eea5fa6096e01ddd04760bd0c9f6cd25dc7113c0bbafb019f3fe048
description: MuleSoft Documentation Site
latest: true
---
---
product: Design Center
---

# Guide to Defining Examples in RAML 1.0

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

When defining examples in external files for a type, trait, or resource type in your RAML 1.0 API
specification, follow these rules:

- For a single example, either use the `example` facet and include a .yaml file or use the
  `examples` facet and include a .raml NamedExample fragment file.

- For multiple examples, always use the `examples` facet and either:

  - Define multiple examples, each pointing to individual .yaml files, with a single example per
    file

  - Include a .raml file containing two or more examples defined in a single NamedExample fragment

## Using a Single Example That Is in a .yaml File

In your specification, include the file with an `example` facet. In your .yaml file, ensure that the
example is at the root level.

The files api.raml and fragment.yaml illustrate the correct way to use a single example that is in a
.yaml file:

api.raml

#%RAML 1.0 title: test types: A: properties: givenName: string familyName: string example: !include
fragment.yaml

fragment.yaml

givenName: ”Chiaki” familyName: "Mukai"

## Using a Single Example That Is in a .raml NamedExample Fragment File

In your specification, include the file with an `example` facet. In your NamedExample fragment,
ensure that the example is not at the root level of the file. The fragment must contain a key that
is the name of the example.

The files api.raml and fragment.raml illustrate the correct way to use a single example that is in a
.raml file:

api.raml

#%RAML 1.0 title: test types: A: properties: givenName: string familyName: string examples: !include
fragment.raml

fragment.raml

#%RAML 1.0 NamedExample fullName: givenName: ”Chiaki” familyName: "Mukai"

Do not use a fragment that looks like this:

fragment.raml

#%RAML 1.0 NamedExample givenName: ”Chiaki” familyName: "Mukai"

In this case, API Designer ignores the header and uses the example. However, if you validate a
specification with any other RAML processors, NamedExample fragments that define only one example
should generate errors, in accordance with the RAML 1.0 specification.

## Naming Two Examples That Are in .yaml Files

In your specification, include the file with the `examples` facet and name each example. In your
.yaml files, ensure that each example is at the root level.

The files api.raml, fragment1.yaml, and fragment2.yaml illustrate the correct way to use two
examples that are in .yaml files:

api.raml

#%RAML 1.0 title: test types: A: properties: givenName: string familyName: string examples:
fullName: !include fragment1.yaml otherFullName: !include fragment2.yaml

fragment1.yaml

givenName: ”Chiaki” familyName: "Mukai"

fragment2.yaml

givenName: "Kyung-won" familyName: "Park"

## Naming Two Examples That Are in a NamedExample Fragment

In your specification, include the file with an `examples` facet. In your NamedExample fragment,
ensure that neither example is at the root level of the file. The fragment must contain two keys
that are each the name of an example.

The files api.raml, and fragment.raml illustrate the correct way to use a two examples that are in a
.raml file:

api.raml

#%RAML 1.0 title: test types: A: properties: givenName: string familyName: string examples: !include
fragment.raml

fragment.raml

#%RAML 1.0 NamedExample fullName: givenName: ”Chiaki” familyName: "Mukai"

otherFullName: givenName: "Kyung-won" familyName: "Park"