This repository has been archived by the owner on Feb 17, 2024. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 858
RAML 1.0 RC1 vs RC2
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:
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
|
| 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 |
| 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/apiThat 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 |
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 |
| 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 = stringAs 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:
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:
|
RC2 renames the available authorization grants for more clarity what each does and also so that they reflect the OAuth 2.0 spec:
|
| 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.