Skip to content
This repository has been archived by the owner on Feb 17, 2024. It is now read-only.

Official Release of RAML 1.0
Compare
Choose a tag to compare
@sichvoge sichvoge released this 17 May 07:23
· 211 commits to master since this release
1.0
09e6570

With this release, the RAML Workgroup has finalized RAML 1.0 and approves it for general availability (GA) status. Since the first release candidate went out last fall, a tremendous amount of feedback and subsequent work has been invested to reach this milestone. Now that it is stable, and with the release in parallel of reference parsers, we look forward to reaping its benefits across the API landscape.

With 1.0, RAML introduces multiple new concepts that not only increase its core strength around designing APIs using libraries, fragments, and overlays/extensions, but also for documenting APIs.

New Features

  • Data types: a unified, streamlined, and powerful way to model data wherever it appears in an API.
    • Uniformly covers bodies, URI parameters, headers, and query parameters and eliminates the need for a separate formParameters construct
    • Supports wrapping XML Schema and JSON Schema and even referring to sub-schemas, but in many cases just obviates the schemas
    • Simplifies coding, compared to the JSON Schema or XML Schema, by being YAML-based
  • Multiple Examples: expressible in YAML, and annotatable so that semantics can be injected
  • Annotations: a tried-and-tested, strongly-typed mechanism for extensibility
  • Libraries: improved modularity for broad reuse of API artifacts
  • Overlays and Extensions: increased extensibility through separated files
  • Improved Security Schemes:
    • Wider OAuth support
    • Support for pass-through (key-based) security schemes
    • Support for signatures

Besides new features, the main focus for RAML 1.0 was also to create a more consistent and expressive specification. For that, we made several smaller changes, and some with a much bigger impact regarding the compatibility with the previous version.

Did anything change between GA and the latest release candidate?

Yes, we had some feedback from the community that we found crucial to change before we felt comfortable to release 1.0. The changes includes:

  • resourcePathName gets resolved into the rightmost non-URI-parameter-contained resource path (issue #489) to be compatible with the behaviour in RAML 0.8
  • overlays and extension get applied after expansion (issue #488)
  • items in the documentation node cannot be removed using overlays (issue #496)

Other than these three, we only improved content and added some more clarification.

Will that be the last change in 1.0

Obviously we will continue to improve content and add clarification where we see the need to. Although, new features and/or changes to existing will be added to the candidates for our next release.

Where can you go from here?

And if you have any other question, please send us an email to [email protected], post something to our forum, or use our Gitter chat.

All changes during each release candidate and GA can be viewed here.

Assets 3
Loading