Guide to Defining Examples in RAML 1.0

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"