---
schema_version: "1"
id: 7a0cdca65d61bd950c005022cad5c072c74f3fe910411cc89d06d8ba8efd1df0
title: Early Access RAML 1.0
collection: mulesoft
version: current
locale: ja-jp
portal_url: https://docs.salesforce.com/mulesoft/current/ja-jp/release-notes/platform/raml-1-early-access-support.md
canonical_url: https://docs.mulesoft.com/jp/release-notes/platform/raml-1-early-access-support
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 1d15e6d706d14b9cb2bbca313798c1a59a8ad58fd4d6ebf2624a756fc3c2b197
description: MuleSoft Documentation Site
latest: true
---
# Early Access RAML 1.0

With the latest releases of the tooling and Anypoint Platform, MuleSoft introduces early access based on the official [RAML 1.0 specification](https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md). The new version introduces a number of new features listed in the RAML.org [comparison of releases](https://github.com/raml-org/raml-spec/wiki/RAML-1.0-RC1-vs-RC2).

After months of working closely with the RAML workgroup, MuleSoft is synchronizing the MuleSoft product releases with the RAML 1.0 GA release. MuleSoft customers can explore 1.0 concepts in Anypoint Platform using RAML release candidates. In most cases, customers should be able to write API definitions using RAML 1.0 without issues, despite known gaps in the early access version, which this document describes.

<table><tbody><tr><td class="icon"><i class="fa icon-note" title="Note"></i></td><td class="content">Mule 3.8.1 and later provides full RAML 1.0 support.</td></tr></tbody></table>

## [](#migration-notice)Migration Notice

Since RAML 1.0 is early access, the default version used in the tooling is 0.8. To try version 1.0, you have to change the version.

To migrate from RAML 0.8 to RAML 1.0, see the list of [breaking changes](https://github.com/raml-org/raml-spec/wiki/Breaking-Changes) between RAML 0.8 and RAML 1.0.

<table><tbody><tr><td class="icon"><i class="fa icon-important" title="Important"></i></td><td class="content">RAML proxies based on RAML files written using the 1.0 version are valid only for Mule 3.8.0 runtimes. Previous Gateway versions don’t support RAML 1.0.</td></tr></tbody></table>

## [](#underlying-parsers-and-known-gaps)Underlying Parsers and Known Gaps

For RAML 1.0 a new version of the [JavaScript](https://github.com/raml-org/raml-js-parser-2/tree/0.2.10) and [Java](https://github.com/raml-org/raml-java-parser/tree/v2) parsers have been implemented. MuleSoft tooling relies on these parsers to validate the RAML and expose the required APIs. The following table shows the tooling dependencies for the parser implementations:

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 30%;">
<col style="width: 70%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Parser</th>
<th class="tableblock halign-left valign-top">Tooling</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top" rowspan="5"><div class="content"><div class="paragraph">
<p>JavaScript</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist">
<ul>
<li>
<p>API Designer</p>
</li>
</ul>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist">
<ul>
<li>
<p>Mocking Service</p>
</li>
</ul>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist">
<ul>
<li>
<p>API Console</p>
</li>
</ul>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist">
<ul>
<li>
<p>Notebook</p>
</li>
</ul>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist">
<ul>
<li>
<p>API Console in Studio</p>
</li>
</ul>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top" rowspan="4"><div class="content"><div class="paragraph">
<p>Java</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist">
<ul>
<li>
<p>Mule 3.8.0</p>
</li>
</ul>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist">
<ul>
<li>
<p>APIkit 3.8.0</p>
</li>
</ul>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist">
<ul>
<li>
<p>RAML Editor in Studio</p>
</li>
</ul>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist">
<ul>
<li>
<p>HTTP Connector</p>
</li>
</ul>
</div></div></td>
</tr>
</tbody>
</table>

## [](#javascript-parser-known-gaps)JavaScript Parser Known Gaps

The current JavaScript parser is 100% compliant with the specification, without any known gaps.

## [](#java-parser-known-gaps)Java Parser Known Gaps

The current Java parser is not yet fully compliant with the specification. The following table lists feature gaps:

<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 30%;">
<col style="width: 70%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Text</th>
<th class="tableblock halign-left valign-top">Parameter</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>uses key</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>The <a href="https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md#applying-libraries">spec</a> supports the <code>uses</code> node in any fragment. Currently, the parser only allows the <code>uses</code> node in root level RAML documents and libraries.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Annotations for scalar fields</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>The <a href="https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md#annotating-scalar-valued-nodes">spec</a> allows applying annotations to scalar nodes in addition to certain mapping nodes. Annotations at the scalar level are not supported.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Overlays restrictions</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Overlay application is not enforcing all the required restrictions. The extra restrictions that Overlays enforce versus Extensions are not validated.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top" rowspan="2"><div class="content"><div class="paragraph">
<p>Security Schemes gaps</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist">
<ul>
<li>
<p>OAuth 1.0 <code>signatures</code> setting is not supported</p>
</li>
</ul>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist">
<ul>
<li>
<p>OAuth 2.0 <code>authorizationUri</code> is always optional, regardless of authorization grants.</p>
</li>
</ul>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>XML Examples validations against YAML types</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>Validation of XML examples against types defined in YAML are not supported. XML validations are only supported for schemas defined in XSD format.</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top" rowspan="8"><div class="content"><div class="paragraph">
<p>type system gaps</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>These features, related to the definition, are not supported:</p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist">
<ul>
<li>
<p>Inheritance of primitive types</p>
</li>
</ul>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist">
<ul>
<li>
<p><code>discriminator</code> field</p>
</li>
</ul>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist">
<ul>
<li>
<p>Examples nested in a value</p>
</li>
</ul>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist">
<ul>
<li>
<p>Xml Facet field</p>
</li>
</ul>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist">
<ul>
<li>
<p>Additional properties</p>
</li>
</ul>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist">
<ul>
<li>
<p><code>null</code> type</p>
</li>
</ul>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist">
<ul>
<li>
<p>Properties named with trailing question marks</p>
</li>
</ul>
</div></div></td>
</tr>
</tbody>
</table>

Refer to [“RAML 1.0 Features Gap”](https://github.com/raml-org/raml-java-parser/blob/0.1.0-alpha-2/MISSING.md) for the latest list.

## [](#support-gaps-by-product)Support Gaps by Product

### [](#api-console-and-mocking-service)API Console and Mocking Service

API Console and Mocking Service depends on the JavaScript parser for parsing out data types and overall API behaviors. API Console and Mocking Service currently don’t support [annotations](https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md#annotations). When you run a RAML file with RAML 1.0 annotations in API Console, annotations do not appear in the Console documentation and Try It tab. Annotations are visible only from the RAML definition in API Designer, and have no effect in API Console and Mocking Service tools.

### [](#api-notebook)API Notebook

API Notebook supports RAML 1.0 with the following limitations:

- Data types are not meaningful in this context.
- Overlays are not meaningful in this context.

### [](#apikit)APIkit

APIkit depends on the Java parser for validating and scaffolding the RAML file, therefore it inherits the limitations of the Java parser listed above in the “Java Parser Known Gaps” section. When you try to scaffold a RAML file that contains elements not yet supported by the Java parser, validation fails and the flows are not generated.

OData APIkit extension beta does not support RAML 1.0 or the new APIkit integrated within Studio 6.0. Customers using the OData extension, should postpone upgrading and continue to use Studio 5.4. The GA version of the OData implementation feature with Studio will be released in the near future.

### [](#studio)Studio

Studio’s embedded RAML editor depends on the Java parser for validating and suggesting RAML 1.0 syntax. The embedded APIkit also depends also on the Java parser for the scaffolding feature (see below). The embedded API Console depends on the JavaScript parser, and has parity with the standalone API Console:

- Suggester for RAML 1.0 does not support RAML types or RAML files without a header. Users might not benefit fully from the editor suggesting certain tags and auto-completion.
- The embedded RAML 1.0 editor validation feature has parity with the Java parser. Using the syntax related to RAML 1.0 listed above in the “Java Parser Known Gaps” section, might cause incorrect validations.
- MUnit RAML-to-Test auto-generation feature does not support RAML 1.0. We are actively working to evolve the feature.
- DataSense currently does not support RAML 1.0 types. When the customer uses RAML 1.0, the metadata is not passed and leveraged by DataSense.

### [](#api-manager)API Manager

Mule 3.8.0 depends on the Java parser. API Manager relies on Mule 3.8.0 support for auto-generated proxies based on RAML 1.0. In most cases, the proxy generation feature works well on API Manager for RAML 1.0-defined APIs. However, if a user tries to auto-generate proxies based on a RAML 1.0 file, and definition has known gaps, which are not covered by the Java parser on API Manager, the deployed proxy fails.

## [](#details-on-known-validation-discrepancies-among-products)Details on Known Validation Discrepancies among Products

API Designer supports RAML 1.0 based on the JavaScript (JS) parser, while Studio RAML editor and APIkit use the Java parser instead. Due to incomplete support of the Java parser in RAML 1.0, users might see discrepancies among products.

The following sections describe known discrepancies in validation behavior.

### [](#a-annotating-scalar-annotations)A. Annotating scalar annotations

The [spec](https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md#annotating-scalar-valued-nodes) allows applying annotations to scalar nodes in addition to certain mapping nodes. If a user specifies the following:

baseUri:
  value: http://www.example.com/api
  (redirectable): true

- In current RAML spec: VALID
- In JavaScript parser (i.e. API Designer): VALID
- In Java parser (i.e. RAML editor in Studio, APIkit): INVALID

### [](#b-uses-in-any-fragment)B. uses in any fragment

The [spec](https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md#applying-libraries) allows using uses in any fragment. The Java parser allows its use only in root level RAML documents and libraries.

#%RAML 1.0 ResourceType
# This file is located at files-resource.raml
uses:
  files: libraries/files.raml
get:
  is: files.drm

- In current RAML spec: VALID
- In JavaScript parser (i.e. API Designer): VALID
- In Java parser (i.e. RAML editor in Studio, APIkit): INVALID

### [](#c-null-type)C. Null type

RAML 1.0 introduced the null type. If a user specifies the following:

annotationTypes:
  deprecated: null
  testHarness: null | string
  badge: string? # equivalent to ‘null | string’

- In current RAML spec: VALID
- In JavaScript parser (i.e. API Designer): VALID
- In Java parser (i.e. RAML editor in Studio, APIkit): INVALID

### [](#d-examples-example)D. Examples / Example

RAML 1.0 loosened the syntax requirements for examples / example and replaced “content” with “value”. If a user specifies the following:

types:
  Org:
    type: object
    properties:
      name: string
      address?: string
    examples:
      acme:
        name: Acme
      softwareCorp:
        value:
          name: Software Corp
          address: 35 Central Street

-----
example:
  height: 12
  width: 4

-----
example:
  (pii): true
  strict: false
  value:
    height: 12
    width: 4

- In current RAML spec: VALID
- In JavaScript parser (i.e. API Designer, API Console): VALID
- In Java parser (i.e. RAML editor in Studio, APIkit): INVALID

### [](#e-additional-properties-pattern-properties)E. Additional properties (pattern properties)

This is a change from RC1 to RC2 that changed the syntax from `[]` to `//` since because it introduced conflicts with YAML. If a user specifies the following:

types:
  Person:
    properties:
      a: string
      \[a\]: number

- In current RAML spec: INVALID
- In JavaScript parser (i.e. API Designer, API Console): INVALID
- In Java parser (i.e. RAML editor in Studio, APIkit): VALID

If a user specifies the following:

types:
  Person:
    properties:
      a: string
      //: number

- In current RAML spec: VALID
- In JavaScript parser (i.e. API Designer, API Console): VALID
- In Java parser (i.e. RAML editor in Studio, APIkit): INVALID

### [](#f-question-mark)F. Question Mark

If a user specifies the following:

types:
  profile:
    properties:
      preference?:
        required: true

- In current RAML spec: VALID
- In JavaScript parser (i.e. API Designer, API Console): VALID
- In Java parser (i.e. RAML editor in Studio, APIkit): INVALID

### [](#g-inheritance-of-primitive-values)G. Inheritance of primitive values

If a user specifies the following:

types:
  Number1:
   type: number
   minimum: 4
  Number2:
   type: number
   maximum: 10
  Number3: \[ Number1, Number2\]

- In current RAML spec: VALID
- In JavaScript parser (i.e. API Designer, API Console): VALID
- In Java parser (i.e. RAML editor in Studio, APIkit): INVALID

### [](#h-discriminator)H. Discriminator

If a user specifies the following:

application/json:
   type: Phone | Notebook
   discriminator: kind

- In current RAML spec: INVALID
- In JavaScript parser (i.e. API Designer, API Console): INVALID
- In Java parser (i.e. RAML editor in Studio, APIkit): VALID

### [](#i-type-within-types)I. Type within Types

If a user specifies the following:

types:
  Next:
    type:
      properties:
        another: string
    properties:
      name: string

- In current RAML spec: VALID
- In JavaScript parser (i.e. API Designer, API Console): VALID
- In Java parser (i.e. RAML editor in Studio, APIkit): INVALID