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

RAML 1.0 RC1 vs RC2

Jump to bottom
Christian Vogel edited this page May 5, 2016 · 1 revision

This section highlights the main differences between RC1 and RC2. It only covers the features that has been either changed or added; nothing else. So clarification issues that has been introduced in RC2 or, for example, the fact that including a library using uses behaves differently internally inside a RAML processor in RC2 are not part of this.

Feature RC1 RC2
Resource Type Parameters Defining an optional method in a resource type plus a parameter somewhere in its node hierarchy, forced you to declare the parameter when that resource type is being used, even if the method is not explicitly used. So the following was not valid in RC1: 
resourceTypes:
  collection:
    get?:
      Description: <<TextAbout>>
/resource:
  type: collection
  # invalid bc missing <<TextAbout>>
When an optional method is not explicitly declared in a resource; the parameter does not have to be defined. The following is fully valid in RC2: 
resourceTypes:
  collection:
    get?:
      Description: <>
/resource:
  type: collection
  # valid since ‘get’ is not declared explicitly
XML and JSON Schemas in RAML Types RC1 did not really restrict to define XML or JSON schemas in any place inside the RAML type declaration hierarchy. You could even mix them all together in the same type. RC2 is more clear about the fact that you can’t add additional facets other than example, annotations, and description to types that are defined with XML or JSON schemas. Those type are also not allowed to take part in any type expression. Hence you can’t mix them.
Value of the `type` facet. You could not have a type declaration as the value of `type`, or include it from an external source. So the following is invalid in RC1: 
types:
  Next:
    type:
      properties:
        another: string
    properties:
      name: string
With regards to a consistent approach throughout the specification and how we handle different types/schemas, RC2 allows to define a type declaration inside the `type` facet. So the following is valid in RC2: 
types:
  Next:
    type:
      properties:
        another: string
    properties:
      name: string
Facets RC1 spec restricted facets to object types only. Facets in RC2 can be defined on object, any scalar, or array type.
Map Types RC1 defined a map type and a shortcut for that number{}. RC2 removed that since that was a leftover and actually related to additional properties.
Referencing Libraries In RC1, referencing libraries using uses was restricted to only a sub-set of fragments and you were able to use uses inline in, for example, trait and resource type definition. So the following example is valid RC1: 
resourceTypes:
  collection:
    uses:
In RC2, uses is only allowed at the root-level of every fragment. So the following example is invalid in RC2: 
resourceTypes:
  collection:
    uses: # invalid, not root-level
Using Discriminator In RC1, you were able to define the discriminator on union types, and also discriminator and discriminator in a body. So in RC1 the following is fully valid: 
application/json:
   type: Phone | Notebook
   discriminator: kind
RC2 removes the support for the following:
  • discriminator facet on union types
  • discriminator and discriminatorValue on non global type definitions
The following is not valid in RC2: 
application/json:
   type: Phone | Notebook
   discriminator: kind
However the following is fully valid in RC2: 
types:
  Person:
    type: object
    discriminator: kind
    properties:
      kind: string
      name: string
xml facet n/a RC2 adds an additional xml facet to type declarations to support use cases that needs to serialize XML instances.
Support for inline definitions of traits, resource types, and security schemes In RC1, and also 0.8, you could define traits, resource types, and security schemes inline w/o using global definitions. For example, that is fully valid: 
/users:
  type: !include types/collectionBase.raml
In RC2, you are not allowed to do inline declaration of traits, resource types, and security schemes anymore. Only references to global definitions are possible.
Simplified inheritance rules RC1 is really strict on how inheritance works for types. So the following example is invalid in RC1: 
types:
  Number1:
   type: number
   minimum: 4
  Number2:
   type: number
   maximum: 10
  Number3: [ Number1, Number2]
RC2 has more simplistic rules and allows a bit more freedom on inheritance. The following example is valid in RC2: 
types:
  Number1:
   type: number
   minimum: 4
  Number2:
   type: number
   maximum: 10
  Number3: [ Number1, Number2]
Question Mark in type property names n/a RC2 introduces mechanism to allow the question mark `?` to be part of the property name, and not only to indicate that the property is optional.
Additional properties (pattern properties) In RC1, pattern, or additional, properties can be defined using `[]` or with a pattern between the open and closed brackets to restrict the names for the additional patterns. For example, the following is fully valid in RC1: 
types:
  Person:
    properties:
      a: string
      [a]: number
In RC2, we changed the syntax from `[]` to `//` since that introduced conflicts with YAML, but also clarified restrictions. So the following example is valid: 
types:
  Person:
    properties:
      a: string
      //: number
But, the next example is invalid since the pattern property matches to an existing property name: 
types:
  Person:
    properties:
      a: string
      /a/: number
Mutual Exclusiveness between schema and type RC1 did not explicitly state that schema and type are mutually exclusive. So the following could be done w/o any problems: 
types:
  Person:
    schema:
    type: object
RC2 explicitly states that schema and type are mutually exclusive. The following is invalid in RC2: 
types:
  Person:
    schema:
    type: object
Syntax for global definitions such as trait, resource types, and security schemes In RC1, the syntax to declare a resource type, trait, or a security scheme was either a sequence (like in 0.8) or map (new in 1.0). So you could do either: 
resourceTypes:
  - collection: # sequence
      description: fkdshfkldfg
or 
resourceTypes:
  collection: # map
    description: fkdshfkldfg
To create a more consistent approach that fits into 1.0 in general, RC2 removes the ability to define sequences and only concentrates on maps. Valid: 
resourceTypes:
  collection: # map
    description: fkdshfkldfg
With that change, RC2 also not allows for any composition since that could only be done using sequences. For example the following is invalid: 
resourceTypes:
  - others: !include file.raml
  - collection: # sequence
      description: fkdshfkldfg
Inheritance of traits In RC1, a trait was not able to inherit properties from another trait. So the following example is invalid in RC1: 
traits:
  test:
    is: [ pageable ]
  pageable:
    headers:
      asynch:
        properties:
          name: string
RC2 allows a trait to also inherit from another trait. The following is valid in RC2: 
traits:
  test:
    is: [ pageable ]
  pageable:
    headers:
      asynch:
        properties:
          name: string
Optional Properties in resource types and traits RC1 allowed any property inside a trait and resource type to be declared as optional. That is valid in RC1: 
      traits:
        pageable:
          headers?:
RC2 does only allow to declare a method in a resource type to be optional. That is invalid in RC2: 
traits:
  pageable:
    headers?:
And only the following is valid: 
resourceTypes:
  corpResource:
    post?:
Mark Relative URI as optional RC1 stated that a relative URI is required. (bug) RC2 fixes that and relative URI’s are optional now.
Remove allowMultiple facet from an annotation type declaration RC1 defines an additional facet called allowMultiple for annotation type declarations. The following is valid in RC1: 
annotationTypes:
  test:
    allowMultiple: true
RC2 removes the allowMultiple facet from any annotation type declaration since multiple keys with the same name are not allowed in YAML.
parameter facet on traits or resource types RC1 introduced an additional optional facet called parameter. In RC2, we removed the parameter facet since it has never been really applied.
Documentation facets in Security Schemes In RC1, you are allowed to define a displayName and description inside the describeBy facet of a security scheme. The following is valid in RC1: 
securitySchemes:
  test:
    type: x-{other}
    describedBy:
      displayName: something
      description: something
In RC2, we removed displayName and description from describeBy and only added displayName to the security scheme node. The only valid example in RC2 is: 
securitySchemes:
  test:
    type: x-{other}
    displayName: something
    describedBy:
Examples/Example RC1 added new capabilities to define multiple examples following the syntax below. 
types:
  Org:
    type: object
    properties:
      name: string
      address?: string
    examples:
      acme:
        content:
          name: Acme
      softwareCorp:
        content:
          name: Software Corp
          address: 35 Central Street
Or 
types:
  Org:
    type: object
    properties:
      name: string
      address?: string
    Examples: # using sequences w/o keys (ids)
      - content:
          name: Acme
      - content:
          name: Software Corp
          address: 35 Central Street
In RC2 we made the syntax more consistent with the overall RAML 1.0 specification and replaced content with value and also removed sequences. It’s also optional to use value and should only be used if you have to add additional facets to your definition such as strict or an annotation. So any example in examples has a unique identifier. The following examples are valid in RC2 now: 
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
Default Media Types In RC1 you could define a single default media type. 
#%RAML 1.0
title: Stormpath REST API
version: v1
mediaType: application/json
In RC2 you are able to define multiple default media types either using a single string if it’s only one or a sequence of media type strings. The following examples are both valid in RC2: 
#%RAML 1.0
title: Stormpath REST API
version: v1
mediaType: application/json



#%RAML 1.0
title: Stormpath REST API
version: v1
mediaType: [ application/json, application/xml ]
Referencing Overlays and Extensions to its parent RAML In RC1, we introduced the facet masterRef is used to reference to a root RAML document, or to another overlay or extension. The following is valid in RC1: 
#%RAML 1.0 Overlay
masterRef: librarybooks.raml
To make language more consistent inside the specification, we renamed masterRef to extends in RC2. The following is valid in RC2: 
#%RAML 1.0 Overlay
extends: librarybooks.raml
Annotating scalar values n/a In RC2 we added the support to also annotate scalar valued node such as baseUri or example. The following examples are both valid in RC2: 
baseUri: http://www.example.com/api



baseUri:
value: http://www.example.com/api
That ability would support use cases like: 
baseUri:
value: http://www.example.com/api
(redirectable): true
displayName at the root-level of a RAML document In RC1 you were able to define displayName at the root-level of a RAML document. 
#%RAML 1.0
title: Book Library API
displayName: fjdhs
The support in RC1 was clearly a bug and has been fixed by removing displayName at this level.
Date Type RC1 defines a date scalar type using the following syntax: 
types:
DateOfBirth:
type: date
RC2 adds better support for different scenarios defining a date inside a type and adds date-only time-only datetime-only datetime The date type has been removed in favour for datetime in RC2. The following is a valid example: 
types:
DateOfBirth:
type: datetime
Including Libraries In RC1, you are able to include libraries using uses. The value is a map where each key defines a namespace for a library and the value is a library file that will be included. The following is an example to do that in RC1: 
#%RAML 1.0
title: Main API

uses:
types-lib: !include lib-types.raml
In RC2, we changed the behaviour of uses in general to be more close to required and with that we had to change the syntax of pointing to the library file. This included removing !include since its behaviour is different. The following is an example in RC2: 
#%RAML 1.0
title: Main API

uses:
types-lib: lib-types.raml
Mutual Exclusiveness between schemas and types RC1 did not explicitly state that schemas and types are mutually exclusive. So the following could be done w/o any problems: 
types:
schemas:
RC2 explicitly states that schemas and types are mutually exclusive. The following is invalid in RC2: 
types:
schemas:
Support for null-valued properties RC1 only partially had support for properties w/o values. That is reflected inside annotations that could be expressed in the following way: 
annotationTypes:
deprecated: # default type = string

/resource:
(deprecated):
As you can see the annotation has no value. RC1 did not state what the actual value is. Is it an empty string? Is it something else? 		RC2 introduces another type null that can be used to express null-valued properties. The following is an example of that in RC2: 
annotationTypes:
deprecated: null
testHarness: null | string
badge: string? # equivalent to null | string
Add signatures support in OAuth 1.0 n/a In RC2 we added an additional node signatures to an OAuth 1.0 security scheme declaration. The available signatures are restricted to:
  • HMAC-SHA1
  • RSA-SHA1
  • PLAINTEXT
An example: 
securitySchemes:
oauth_1_0:
type: OAuth 1.0
settings:
requestTokenUri: ...
authorizationUri: ...
tokenCredentialsUri: ...
signatures: [ 'HMAC-SHA1', 'PLAINTEXT' ]
Renamed authorization grants In RC1 authorization grants were taken directly from 0.8 and re named like the following:
  • code
  • token
  • owner
  • credentials
 RC2 renames the available authorization grants for more clarity what each does and also so that they reflect the OAuth 2.0 spec:
  • authorization_code
  • password
  • client_credentials
  • implicit
  • any absolute URI
Clarity on OAuth 2.0 Authorization Endpoint URI In RC1, an authorizationUri was mandatory regardless what grant types have been used. That’s not correct according to the OAuth 2.0 spec. RC2 restricts the declaration of the authorizationUri to be mandatory only when using either authorization_code or implicit grant type.

RC2 also introduced other major changes to the type system which are not mentioned in the table above, for example, how a type instance gets validated or in general validation of types. These changes are more about content and defining validation rules which are difficult to compare with the previous RC1 version.

The full list of all changes for RC2 can be viewed here.

News

FAQ

More

Clone this wiki locally