Merge pull request #498 from raml-org/raml-10

Release of RAML 1.0 GA

.gitignore

@@ -0,0 +1,3 @@
+# MAC OS
+
+.DS_Store

README.md

@@ -1,66 +1,20 @@
 # The RESTful API Modeling Language (RAML) Spec
 
-## Note - Updated version
+[![Gitter](https://img.shields.io/gitter/room/nwjs/nw.js.svg?maxAge=2592000)](https://gitter.im/raml-org/raml-spec)
 
-The RAML Workgroup is currently working on a newer version of the specification. All progress can be monitored inside the `raml-10` branch. Please switch to that branch for any information about RAML 1.0.
+RAML is a language for the definition of HTTP-based APIs that embody most or all of the principles of Representational State Transfer (REST). The RAML specification (this document) defines an application of the [YAML 1.2 specification](http://yaml.org/spec/1.2/spec.html) that provides mechanisms for the definition of practically-RESTful APIs, while providing provisions with which source code generators for client and server source code and comprehensive user documentation can be created.
 
-###Licensing
+## Contributing
 
-[Branding Guidelines](http://raml.org/licensing.html)
-
-## Index
-
-###[Introduction:](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#introduction)
-[RAML Overview](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#overview)  
-[RAML Markup Language](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#markup-language)
-
-####[Includes](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#includes)
-
-Named Parameters:
-
-[Named Parameters with Multiple Types](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#named-parameters-with-multiple-types)
-
-Basic Information:
-
-[Root](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#root-section)  
-[Base URI and baseUriParameters](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#base-uri-and-baseuriparameters)  
-[Protocols](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#protocols)  
-[Default Media Type](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#default-media-type)  
-[Schemas](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#schemas)  
-[URI Parameters](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#uri-parameters)  
-[User Documentation](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#user-documentation)
+We welcome any contributions from the community! You can contribute or provide feedback for the RAML Specification in different ways depending on your intentions. The following table illustrates the different ways to help us not only to improve the documentation of the specification, but also RAML itself.
 
-Resources and Methods:
+|Your Intention  |What to do?|
+|:----------|:----------|
+|You see a spelling or grammar mistake, or an error in our examples? | Fork this repository, make edits, and then submit a pull request. We will respond to your request as quickly as possible.
+|You want to suggest a new feature, improve existing features, ask questions, or things general around the RAML specification? | File an issue. Please be as specific as possible about your intentions or what you’d like to see.
 
-[Resources and Nested Resources](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#resources-and-nested-resources)  
-[Template URIs and URI Parameters](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#template-uris-and-uri-parameters)
-[Absolute URI](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#absolute-uri)  
-[Query Parameters](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#query-strings)  
-[Body](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#body)  
-[Web Forms](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#web-forms)  
+You can also directly get in touch with us. Simply send us an email to: info@raml.org
 
-Schemas and Responses:
+## Licensing
 
-[Schemas](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#schema)  
-[Responses](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#responses)  
-[Headers](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#headers)
-
-Security:
-
-[Declaration](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#declaration)  
-[Type](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#type)  
-[OAuth 1.0](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#oauth-10)  
-[OAuth 2.0](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#oauth-20)  
-[Usage: Applying a Security Scheme to an API](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#usage-applying-a-security-scheme-to-an-api)
-
-###[References:](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#references)
-[Normative References](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#normative-references)  
-[Informative References](https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#informative-references)
-
-##Contributing
-
-Please [submit issues in this repository](https://github.com/raml-org/raml-spec/issues) to contribute to the evolution of the RAML specification.
-
-## Logos
-
-Download the RAML Logos in [JPG](https://github.com/raml-org/raml-spec/raw/master/logos/RAML-logo.jpg) and [EPS](https://github.com/raml-org/raml-spec/raw/master/logos/RAML-logo.eps) format. (For usage questions email [info@raml.org](mailto:info@raml.org)).
+[Branding Guidelines](http://raml.org/licensing.html)

raml-0.8.md → versions/raml-08/raml-08.md

@@ -1,7 +1,5 @@
 RAML™ Version 0.8: RESTful API Modeling Language
-===================================
-
-A [newer version of RAML (1.0)](http://raml.org/spec.html) is available.
+==================================
 
 Abstract
 --------
@@ -584,7 +582,7 @@ baseUriParameters:
       enum: [ "api-content" ]
 ```
 
-In a resource structure of resources and nested resources with their methods, the most specific baseUriParameter fully overrides any baseUriParameter definition made before. In the following example the resource `/user/{userId}/image` overrides the definition made in `/users`.
+In a resource structure of resources and nested resources with their methods, the most specific baseUriParameter fully overrides any baseUriParameter definition made before. In the following example the resource `/users/{userId}/image` overrides the definition made in `/users`.
 
 ```
 #%RAML 0.8
@@ -603,7 +601,7 @@ baseUri: https://{apiDomain}.someapi.com
         enum: [ "static" ]
 ```
 
-In the following example, the `PUT` method overrides the definition made in `/user/{userId}/image`.
+In the following example, the `PUT` method overrides the definition made in `/users/{userId}/image`.
 
 ```
 #%RAML 0.8
@@ -621,9 +619,9 @@ baseUri: https://{apiDomain}.someapi.com
       apiDomain:
         enum: [ "static" ]
     get:
-      displayName: retrieve a user's picture
+      description: retrieve a user's picture
     put:
-      displayName: update a user's picture
+      description: update a user's picture
       baseUriParameters:
         apiDomain:
           enum: [ "content-update" ]
@@ -937,7 +935,7 @@ The *schema* key CANNOT be specified if a body's media type is *application/x-ww
 
 All parsers of RAML MUST be able to interpret JSON Schema [JSON_SCHEMA] and XML Schema [XML_SCHEMA].
 
-Schema MAY be declared inline or in an external file. However, if the schema is sufficiently large so as to make it difficult for a person to read the API definition, or the schema is reused across multiple APIs or across multiple miles in the same API, the !include user-defined data type SHOULD be used instead of including the content inline.
+Schema MAY be declared inline or in an external file. However, if the schema is sufficiently large so as to make it difficult for a person to read the API definition, or the schema is reused across multiple APIs or across multiple files in the same API, the !include user-defined data type SHOULD be used instead of including the content inline.
 
 This example shows an inline schema declaration.
 
@@ -975,7 +973,7 @@ This example shows an inline schema declaration.
           }
 ```
 
-Alternatively, the value of the *schema* field MAY be the name of a schema specified in the root-level *schemas* property (see [Named Parameters](#named-parameters), or it MAY be declared in an external file and included by using the by using the RAML !include user-defined data type.
+Alternatively, the value of the *schema* field MAY be the name of a schema specified in the root-level *schemas* property (see [Named Parameters](#named-parameters), or it MAY be declared in an external file and included by using the RAML !include user-defined data type.
 
 This example repeats the /jobs resource definition, but with the schemas defined in the external files job.xsd and job.schema.json.
 
@@ -1052,8 +1050,6 @@ For APIs without *a priori* knowledge of the response types for their responses,
       200:
         body:
           "*/*":
-            description: |
-                Returns the media file.
 ```
 
 Responses MAY contain a *description* property that further clarifies why the response was emitted. Response descriptions are particularly useful for describing error conditions.
@@ -1119,7 +1115,7 @@ This example shows a 503 error response that includes a custom header.
             description: |
               The number of seconds to wait before you can attempt to make a request again.
             type: integer
-            required: yes
+            required: true
             minimum: 1
             maximum: 3600
             example: 34
@@ -1191,7 +1187,7 @@ traits:
           required: true
 ```
 
-The following example builds on the previous one, but the the resource types and traits are defined in external files that are included by using the RAML !include data type.
+The following example builds on the previous one, but the resource types and traits are defined in external files that are included by using the RAML !include data type.
 
 ```yaml
 #%RAML 0.8
@@ -1266,8 +1262,8 @@ title: Example API
 version: v1
 mediaType: application/json
 schemas:
-  users: !include schemas/users.json
-  user: !include schemas/user.json
+  - users: !include schemas/users.json
+  - user: !include schemas/user.json
 resourceTypes:
   - collection:
       get: