### Define Basic RAML 1.0 API with Hello World Endpoint

Source: https://context7.com/raml-org/raml-examples/llms.txt

Demonstrates the minimal structure for a RAML 1.0 API, including the required title and a basic resource with a GET method that returns a JSON response.

```yaml
#%RAML 1.0
title: Hello world # required title

/helloworld: # optional resource
  get: # HTTP method declaration
    responses: # declare a response
      200: # HTTP status code
        body: # declare content of response
          application/json: # media type
            type: |
              {
                "title": "Hello world Response",
                "type": "object",
                "properties": {
                  "message": {
                    "type": "string"
                  }
                }
              }
            example: |
              {
                "message": "Hello world"
              }
```

--------------------------------

### Defining Examples

Source: https://context7.com/raml-org/raml-examples/llms.txt

Shows how to define examples for request and response bodies, as well as for individual fields, aiding documentation and testing.

```APIDOC
## Defining Examples

Examples provide sample data for documentation and testing, supporting both single and multiple named examples.

### POST /organisation

**Description**: Creates a new organization with specified details.

**Method**: POST

**Endpoint**: `/organisation`

**Parameters**:

**Headers**:
- **UserID** (string) - Required - The identifier for the user that posts a new organisation. Example: `SWED-123`

**Request Body**:
- **schema**: `Org` (object) - The organization details.
  - **name** (string) - The name of the organization.
  - **address** (string) - Optional - The address of the organization.
  - **value** (string) - Optional - A value associated with the organization.

**Request Example**:
```json
{
  "name": "Doe Enterprise",
  "value": "Silver"
}
```

### Response

#### Success Response (200)
- **schema**: `Org` (object) - The created organization object.

#### Response Example
```json
{
  "name": "Doe Enterprise",
  "value": "Silver"
}
```

### GET /organisation

**Description**: Returns an organization entity.

**Method**: GET

**Endpoint**: `/organisation`

**Parameters**:

**Query Parameters**:

**Request Body**:

### Response

#### Success Response (201)
- **schema**: `Org` (object) - The organization details.
  - **name** (string) - The name of the organization.
  - **address** (string) - Optional - The address of the organization.
  - **value** (string) - Optional - A value associated with the organization.

**Examples**:
- **acme**: `{"name": "Acme"}`
- **softwareCorp**: `{"name": "Software Corp", "address": "35 Central Street", "value": "Gold"}`

#### Response Example
```json
{
  "name": "Acme",
  "address": null,
  "value": null
}
```
```

--------------------------------

### API with Traits

Source: https://context7.com/raml-org/raml-examples/llms.txt

An example API demonstrating the application of secured, orderable, and pageable traits to different HTTP methods.

```APIDOC
## API with Traits

This API showcases the usage of defined traits for securing and managing endpoints.

### API Definition

```yaml
#%RAML 1.0
title: Example API
version: v1
traits:
  secured: !include secured.raml
  orderable: !include orderable.raml
  pageable: !include pageable.raml

/users:
  is: [ secured ]
  get:
    is: [ orderable, pageable ]
  post:
  patch:
  put:
  delete:
```
```

--------------------------------

### RAML Defining Single and Multiple Named Examples

Source: https://context7.com/raml-org/raml-examples/llms.txt

Shows how to define example data for API endpoints, supporting both single inline examples and multiple named examples. This is useful for documentation, testing, and client-side development.

```yaml
#%RAML 1.0
title: API with Examples

types:
  User:
    type: object
    properties:
      name: string
      lastname: string
    example:
      name: Bob
      lastname: Marley
  Org:
    type: object
    properties:
      name: string
      address?: string
      value? : string
/organisation:
  post:
    headers:
      UserID:
        description: the identifier for the user that posts a new organisation
        type: string
        example: SWED-123 # single scalar example
    body:
      application/json:
        type: Org
        example: # single request body example
          value: # needs to be declared since type contains 'value' property
            name: Doe Enterprise
            value: Silver
  get:
    description: Returns an organisation entity.
    responses:
      201:
        body:
          application/json:
            type: Org
            examples:
              acme:
                name: Acme
              softwareCorp:
                value: # validate against the available facets for the map value of an example
                  name: Software Corp
                  address: 35 Central Street
                  value: Gold # validate against instance of the `value` property

```

--------------------------------

### API with Resource Types

Source: https://context7.com/raml-org/raml-examples/llms.txt

An example API that utilizes the 'collection' resource type for its '/products' endpoint.

```APIDOC
## API with Resource Types

This API demonstrates the use of a defined resource type for managing product collections.

### API Definition

```yaml
#%RAML 1.0
title: Products API

resourceTypes:
  collection: !include collection.resourceType.raml # include ResourceType fragment

/products:
  type: collection # reference to global resource type declaration
```
```

--------------------------------

### RAML 1.0 Array Type Definitions with Constraints

Source: https://context7.com/raml-org/raml-examples/llms.txt

Demonstrates defining array types in RAML 1.0 using both full syntax and shortcut notation, including constraints like `minItems` and `uniqueItems`, along with an example.

```yaml
#%RAML 1.0 Library

types:
  Email: # normal object type declaration
    type: object
    properties:
      subject: string
      body: string
  EmailsLong: # array type declaration
    type: array
    items: Email
    minItems: 1
    uniqueItems: true
  EmailsShort: # array type declaration using type expression shortcut
    type: Email[] # '[]' expresses an array
    minItems: 1
    uniqueItems: true
    example: # example that contains array
      - # start item 1
        subject: My Email 1
        body: This is the text for email 1.
      - # start item 2
        subject: My Email 2
        body: This is the text for email 2.
```

--------------------------------

### Libraries

Source: https://context7.com/raml-org/raml-examples/llms.txt

Demonstrates how to use libraries to share types, traits, and resource types across multiple API specifications.

```APIDOC
## GET /person

### Description
This endpoint retrieves person information, utilizing the `Person` type defined in an external library.

### Method
GET

### Endpoint
/person

### Parameters
None

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (200)
- **Person** (object) - A Person object with name and age properties.

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### DataType Fragments

Source: https://context7.com/raml-org/raml-examples/llms.txt

Explains how to define reusable data types in separate files for better organization, using `!include`.

```APIDOC
## Main API - User Type

### Description
This API includes a `User` data type defined in a separate fragment, which in turn includes an `Email` data type fragment.

### Method
None

### Endpoint
None

### Parameters
None

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (200)
- **User** (object) - A User object with name, email, and homepage properties.

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### Overlays for Localization

Source: https://context7.com/raml-org/raml-examples/llms.txt

Explains how overlays can be used to adapt an API specification for localization purposes without altering the core structure.

```APIDOC
## Overlays for Localization

Overlays modify an API specification for localization without changing structure.

### Base API (`librarybooks.raml`)

**Title**: Book Library API

**Documentation**:
- **title**: Introduction
  **content**: Automated access to books
- **title**: Licensing
  **content**: Please respect copyrights on our books.

### GET /books

**Description**: The collection of library books.

**Method**: GET

**Endpoint**: `/books`

**Response**:

#### Success Response (200)
- **schema**: object - Represents a book.

#### Response Example
```json
[
  {
    "title": "Example Book",
    "author": "Author Name"
  }
]
```

### Overlay Example (Conceptual)

An overlay would typically define localized strings or alternative resource paths for different regions, without changing the fundamental structure of the `librarybooks.raml` specification.
```

--------------------------------

### Discriminators for Polymorphism

Source: https://context7.com/raml-org/raml-examples/llms.txt

Demonstrates how to use discriminators to handle polymorphic type variations in RAML.

```APIDOC
## Discriminators for Polymorphism

Discriminators enable polymorphic type handling by specifying which property identifies the concrete type.

### Type Definitions

```yaml
#%RAML 1.0
title: My API With Types
types:
  Person:
    type: object
    discriminator: kind
    properties:
      name: string
      kind: string
  Employee:
    type: Person
    discriminatorValue: employee # override default
    properties:
      employeeId: string
  User:
    type: Person
    discriminatorValue: user # override default
    properties:
      userId: string
```
```

--------------------------------

### Resource Types with Optional Properties

Source: https://context7.com/raml-org/raml-examples/llms.txt

Demonstrates how to use optional properties in resource types to conditionally define methods, using the `?` suffix.

```APIDOC
## POST /servers

### Description
This endpoint allows posting information about servers. It requires an `X-Chargeback` header and the `TextAboutPost` parameter.

### Method
POST

### Endpoint
/servers

### Parameters
#### Query Parameters
- **TextAboutPost** (string) - Required - Description of the post method.

#### Request Body
None

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (200)
- **description** (string) - Some info about the post method.

#### Response Example
```json
{
  "example": "response body"
}
```

## GET /servers

### Description
This endpoint retrieves server information.

### Method
GET

### Endpoint
/servers

### Parameters
None

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (200)
- **description** (string) - Description of the server.

#### Response Example
```json
{
  "example": "response body"
}
```

## GET /queues

### Description
This endpoint retrieves queue information.

### Method
GET

### Endpoint
/queues

### Parameters
None

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (200)
- **description** (string) - Description of the queue.

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### RAML Traits for Reusable API Properties

Source: https://context7.com/raml-org/raml-examples/llms.txt

Demonstrates the use of RAML traits to define reusable method-level properties. Examples include security headers (`secured`), pagination (`pageable`), and sorting (`orderable`), which can be applied across different endpoints.

```yaml
#%RAML 1.0 Trait
# secured.raml
usage: Apply this to any method that needs to be secured
headers:
  access_token:
    description: Access Token
    example: 5757gh76
    required: true

```

```yaml
#%RAML 1.0 Trait
# pageable.raml
queryParameters:
  offset:
    description: Skip over a number of elements by specifying an offset value for the query
    type: integer
    required: false
    example: 20
    default: 0
  limit:
    description: Limit the number of elements on the response
    type: integer
    required: false
    example: 80
    default: 10

```

```yaml
#%RAML 1.0 Trait
# orderable.raml
queryParameters:
  orderBy:
    description: Order by field
    type: string
    required: false
  order:
    description: Order
    enum: [desc, asc]
    default: desc
    required: false

```

```yaml
#%RAML 1.0
title: Example API
version: v1
traits:
  secured: !include secured.raml
  orderable: !include orderable.raml
  pageable: !include pageable.raml

/users:
  is: [ secured ]
  get:
    is: [ orderable, pageable ]
  post:
  patch:
  put:
  delete:

```

--------------------------------

### Extensions

Source: https://context7.com/raml-org/raml-examples/llms.txt

Demonstrates how to use RAML extensions to create environment-specific API variations, such as development servers or additional endpoints.

```APIDOC
## Extensions

Extensions allow environment-specific API variations like development servers or additional endpoints.

### Production API (`api.raml`)

**Description**: Production version of the API.

**Base URI**: `https://production.com`

**Protocols**: `HTTPS`

### Development Extension (`dev-api.raml`)

**Description**: Development-specific extension for the API.

**Extends**: `api.raml`

**Title**: My Dev API

**Base URI**: `http://localhost`

**Protocols**: `HTTP`, `HTTPS`

**Types**:
- **User** (object): Extends `lib.User` with additional properties.
  - **id** (integer)
  - **role** (string)

### GET /users (Production)

**Description**: Retrieves a list of users from the production API.

**Method**: GET

**Endpoint**: `/users`

**Response**:

#### Success Response (200)
- **schema**: `lib.User[]` (array of User objects)

### POST /users (Development Extension)

**Description**: Adds a new user, specific to the development environment.

**Method**: POST

**Endpoint**: `/users`

**Request Body**:
- **schema**: `User` (object) - The user object to create.

### GET /users/{id} (Development Extension)

**Description**: Retrieves detailed data for a specific user in the development environment.

**Method**: GET

**Endpoint**: `/users/{id}`

**Parameters**:

**Path Parameters**:
- **id** (integer) - Required - The ID of the user.

**Response**:

#### Success Response (200)
- **schema**: `User` (object) - The detailed user object.
```

--------------------------------

### Resource Types: Collection

Source: https://context7.com/raml-org/raml-examples/llms.txt

Defines a reusable resource type for collections, including GET and POST methods with parameterized descriptions.

```APIDOC
## Resource Types: Collection

Resource types define reusable resource patterns with parameterized descriptions using reserved parameters like `resourcePathName`.

### Resource Type Definition

```yaml
#%RAML 1.0 ResourceType
# collection.resourceType.raml
usage: Use this to describe resource that list items # explains the purpose of this fragment

description: A collection of <<resourcePathName>> # resource-level description
get:
  description: Retrieve all <<resourcePathName>> # method-level description
post:
  description: Add an <<resourcePathName | !singularize>> # method-level description
  responses:
    201:
      headers:
        Location:
```
```

--------------------------------

### Annotations

Source: https://context7.com/raml-org/raml-examples/llms.txt

Illustrates the use of annotations to add custom metadata to API elements for documentation, testing, or code generation.

```APIDOC
## GET /users

### Description
This endpoint retrieves user information. It is tagged with `testHarness`, `badge`, and `clearanceLevel` annotations.

### Method
GET

### Endpoint
/users

### Parameters
None

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (200)
- **description** (string) - Description of the user.

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### RAML Discriminators for Polymorphism

Source: https://context7.com/raml-org/raml-examples/llms.txt

Demonstrates how to use discriminators in RAML to enable polymorphic type handling. It specifies a 'kind' property to identify the concrete type of an object, with examples for 'Person', 'Employee', and 'User'.

```yaml
#%RAML 1.0
title: My API With Types
types:
  Person:
    type: object
    discriminator: kind
    properties:
      name: string
      kind: string
  Employee:
    type: Person
    discriminatorValue: employee # override default
    properties:
      employeeId: string
  User:
    type: Person
    discriminatorValue: user # override default
    properties:
      userId: string

```

--------------------------------

### Annotation Targets

Source: https://context7.com/raml-org/raml-examples/llms.txt

Shows how to restrict annotations to specific API elements using `allowedTargets`.

```APIDOC
## GET /users

### Description
This endpoint retrieves user information. The resource and the GET method are annotated with `meta-resource-method`. The response body is annotated with `meta-data`.

### Method
GET

### Endpoint
/users

### Parameters
None

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (200)
- **User[]** (array) - An array of User objects.

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### RAML Date and Time Types

Source: https://context7.com/raml-org/raml-examples/llms.txt

Illustrates RAML's support for various date and time formats, including date-only, time-only, datetime-only, and datetime with RFC formatting. Examples show different formats and their corresponding `format` specifications.

```yaml
#%RAML 1.0 Library

types:
  birthday:
    type: date-only # no implications about time or offset
    example: 2015-05-23
  lunchtime:
    type: time-only # no implications about date or offset
    example: 12:30:00
  fireworks:
    type: datetime-only # no implications about offset
    example: 2015-07-04T21:00:00
  created:
    type: datetime
    example: 2016-02-28T16:41:41.090Z
    format: rfc3339 # the default, so needn't be specified
  If-Modified-Since:
    type: datetime
    example: Sun, 28 Feb 2016 16:41:41 GMT
    format: rfc2616 # this time it's required as otherwise the example is in an invalid format

```

--------------------------------

### RAML File Types with MIME and Size Restrictions

Source: https://context7.com/raml-org/raml-examples/llms.txt

Defines file types in RAML, specifying allowed MIME types and maximum file sizes. This example shows how to restrict uploads to JPEG and PNG images, or allow any file type with a size limit.

```yaml
#%RAML 1.0
title: My Sample API

types:
  userPicture:
    type: file
    fileTypes: ['image/jpeg', 'image/png'] # only JPEG and PNG allowed
    maxLength: 307200
  customFile:
    type: file
    fileTypes: ['*/*'] # any file type allowed
    maxLength: 1048576

/files:
  post:
    body:
      multipart/form-data:
        properties:
          files:
            description: The file(s) to be uploaded
            required: true
            type: File[]

```

--------------------------------

### RAML Resource Types for Reusable Resource Patterns

Source: https://context7.com/raml-org/raml-examples/llms.txt

Illustrates RAML resource types, which define reusable resource patterns with parameterized descriptions. This example shows a `collection` resource type that can be applied to define API endpoints for collections of items.

```yaml
#%RAML 1.0 ResourceType
# collection.resourceType.raml
usage: Use this to describe resource that list items # explains the purpose of this fragment

description: A collection of <<resourcePathName>> # resource-level description
get:
  description: Retrieve all <<resourcePathName>> # method-level description
post:
  description: Add an <<resourcePathName | !singularize>> # method-level description
  responses:
    201:
      headers:
        Location:

```

```yaml
#%RAML 1.0
title: Products API

resourceTypes:
  collection: !include collection.resourceType.raml # include ResourceType fragment

/products:
  type: collection # reference to global resource type declaration

```

--------------------------------

### Traits: Pageable

Source: https://context7.com/raml-org/raml-examples/llms.txt

Defines a reusable trait for implementing pagination with offset and limit query parameters.

```APIDOC
## Trait: Pageable

Traits define reusable method-level properties like security headers, pagination, and sorting that can be applied across multiple endpoints.

### Trait Definition

```yaml
#%RAML 1.0 Trait
# pageable.raml
queryParameters:
  offset:
    description: Skip over a number of elements by specifying an offset value for the query
    type: integer
    required: false
    example: 20
    default: 0
  limit:
    description: Limit the number of elements on the response
    type: integer
    required: false
    example: 80
    default: 10
```
```

--------------------------------

### Query Parameters

Source: https://context7.com/raml-org/raml-examples/llms.txt

Illustrates the use of query parameters in RAML for filtering and validating requests, including support for nested fields and pattern matching.

```APIDOC
## Query Parameters

Query parameters support pattern matching for nested field filtering and query string validation.

### GET /search

**Description**: Searches for items based on provided query parameters.

**Method**: GET

**Endpoint**: `/search`

**Parameters**:

**Query Parameters**:
- **id** (integer) - Optional - The ID to filter search results.
- **name** (string) - Optional - The name to filter search results.
- **q** (string) - Optional - A general query string.

**Request Body**:

### Response

#### Success Response (200)
- **schema**: array - An array of search results.

#### Response Example
```json
[
  {
    "id": 1,
    "name": "Example Item"
  }
]
```

### GET /books

**Description**: Retrieves a list of books, with filtering options for author details.

**Method**: GET

**Endpoint**: `/books`

**Parameters**:

**Query Parameters**:
- **/^author\[[a-zA-Z]+\]$/** (string) - Optional - Allows filtering by nested author properties (e.g., `author[name]`).

**Request Body**:

### Response

#### Success Response (200)
- **schema**: object - Represents a book with title and author details.
  - **title** (string) - The title of the book.
  - **author** (object)
    - **name** (string) - The name of the author.
    - **origin** (string) - The origin country of the author.
    - **awarded** (boolean) - Indicates if the author has received awards.

#### Response Example
```json
{
  "title": "The Great Novel",
  "author": {
    "name": "Jane Doe",
    "origin": "USA",
    "awarded": true
  }
}
```
```

--------------------------------

### RAML API Extension for Environment-Specific Variations

Source: https://context7.com/raml-org/raml-examples/llms.txt

Demonstrates how to use RAML extensions to create environment-specific API variations, such as different base URIs or additional endpoints for development. This promotes flexibility and maintainability.

```yaml
#%RAML 1.0
# api.raml - Production API
title: My API
mediaType: application/json
baseUri: https://production.com
protocols: [ HTTPS ]

uses:
  lib: types.lib.raml

/users:
  get:
    responses:
      200:
        body: lib.User[]

```

```yaml
#%RAML 1.0 Extension
# dev-api.raml - Development extension
extends: api.raml # RAML API definition to extend

title: My Dev API # DEVELOPMENT-only API definition
baseUri: http://localhost # "localhost" baseUri
protocols: [ HTTP, HTTPS ] # allow unsecured HTTP

uses:
  lib: types.lib.raml

types:
  User: # add a few development-only properties to the "User" type
    type: lib.User
    properties:
      id: integer
      role: string

/users:
  post: # add a POST method to be able to create "test users"
    body: User

  /{id}: # /users/{id} resource to view all of a given user's data set
    get:
      responses:
        200:
          body: User

```

--------------------------------

### Advanced Annotations with Nil Types

Source: https://context7.com/raml-org/raml-examples/llms.txt

Demonstrates advanced annotation usage, including nil types for flags and union types for optional values.

```APIDOC
## GET /groups

### Description
This endpoint retrieves group information. It is marked as experimental and feedback is requested.

### Method
GET

### Endpoint
/groups

### Parameters
None

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (200)
- **description** (string) - Description of the group.

#### Response Example
```json
{
  "example": "response body"
}
```

## GET /users

### Description
This endpoint retrieves user information. It is tagged with `testHarness` and `clearanceLevel` annotations, and the GET method is marked as deprecated, experimental, and has feedback requested.

### Method
GET

### Endpoint
/users

### Parameters
None

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (200)
- **description** (string) - Description of the user.

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### RAML Resource Types with Optional Properties

Source: https://context7.com/raml-org/raml-examples/llms.txt

Demonstrates how to define resource types with optional properties using the `?` suffix in RAML. This allows for conditional method definitions, enabling more flexible API designs.

```yaml
#%RAML 1.0
title: Example of Optional Properties
resourceTypes:
   corpResource:
      post?: # optional property
        description: Some info about <<TextAboutPost>>. # contains custom parameter
        headers:
          X-Chargeback:
            required: true
/servers:
  type:
    corpResource:
      TextAboutPost: post method # post defined which will force to define the TextAboutPost parameter
  get:
  post: # will require the X-Chargeback header
/queues:
  type: corpResource
  get:
  # will not have a post method defined which means one MUST not have to define
  # the TextAboutPost parameter

```

--------------------------------

### JSON Schema Integration

Source: https://context7.com/raml-org/raml-examples/llms.txt

Demonstrates how to integrate JSON Schema for defining data types within RAML, supporting both inline schemas and external file includes.

```APIDOC
## JSON Schema Integration

RAML supports JSON Schema for type definitions, either inline or via include.

### GET /person

**Description**: Retrieves person data.

**Method**: GET

**Endpoint**: `/person`

**Parameters**:

**Query Parameters**:

**Request Body**:

### Response

#### Success Response (200)
- **schema**: `PersonInline` (object) - Defines the structure of the person object.

#### Response Example
```json
{
  "firstName": "John",
  "lastName": "Doe",
  "age": 30
}
```

### POST /person

**Description**: Creates a new person.

**Method**: POST

**Endpoint**: `/person`

**Parameters**:

**Query Parameters**:

**Request Body**:
- **schema**: `Body Declaration Schema` (object) - Defines the structure of the request body for creating a person.

**Request Example**:
```json
{
  "firstName": "Jane",
  "lastName": "Doe"
}
```

### Response

#### Success Response (200)
- **schema**: `Body Declaration Schema` (object) - The created person object.

#### Response Example
```json
{
  "firstName": "Jane",
  "lastName": "Doe"
}
```
```

--------------------------------

### RAML Monetary Value Types with Precision

Source: https://context7.com/raml-org/raml-examples/llms.txt

Showcases complex number types in RAML for monetary values, including precision constraints. It defines types for zero values, values with hundredths, and a comprehensive `MonetaryValue` type with minimum, maximum, and examples.

```yaml
#%RAML 1.0 Library
usage: Types to be used for monetary values

types:
  ZeroValue:
    description: zero-value numbers, accepting either the 0 or 0.00 (hundreths) forms
    type: number
    enum:
      - 0
      - 0.00
  HundredthsValue:
    description: non-zero two-decimal place values (positive and negative)
    type: number
    multipleOf: 0.01
  MonetaryValue:
    description: this type describes any monetary value comprised between -9,999,999,999,999.99 and 9,999,999,999,999.99
    type: ZeroValue | HundredthsValue
    default: 0.00
    minimum: -9999999999999.99
    maximum: 9999999999999.99
    examples:
      zero: 0
      zerozero: 0.00
      tenten: 10.10
      negative: -0.10

```

--------------------------------

### Traits: Secured

Source: https://context7.com/raml-org/raml-examples/llms.txt

Defines a reusable trait for securing endpoints with an access token header.

```APIDOC
## Trait: Secured

Traits define reusable method-level properties like security headers, pagination, and sorting that can be applied across multiple endpoints.

### Trait Definition

```yaml
#%RAML 1.0 Trait
# secured.raml
usage: Apply this to any method that needs to be secured
headers:
  access_token:
    description: Access Token
    example: 5757gh76
    required: true
```
```

--------------------------------

### File Types

Source: https://context7.com/raml-org/raml-examples/llms.txt

Defines how to specify file types in RAML, including MIME type restrictions and maximum file size limits.

```APIDOC
## File Types

File types define binary content with MIME type restrictions and size limits.

### Type Definitions

```yaml
#%RAML 1.0
title: My Sample API

types:
  userPicture:
    type: file
    fileTypes: ['image/jpeg', 'image/png'] # only JPEG and PNG allowed
    maxLength: 307200
  customFile:
    type: file
    fileTypes: ['*/*'] # any file type allowed
    maxLength: 1048576

/files:
  post:
    body:
      multipart/form-data:
        properties:
          files:
            description: The file(s) to be uploaded
            required: true
            type: File[]
```
```

--------------------------------

### Traits: Orderable

Source: https://context7.com/raml-org/raml-examples/llms.txt

Defines a reusable trait for implementing sorting with orderBy and order query parameters.

```APIDOC
## Trait: Orderable

Traits define reusable method-level properties like security headers, pagination, and sorting that can be applied across multiple endpoints.

### Trait Definition

```yaml
#%RAML 1.0 Trait
# orderable.raml
queryParameters:
  orderBy:
    description: Order by field
    type: string
    required: false
  order:
    description: Order
    enum: [desc, asc]
    default: desc
    required: false
```
```

--------------------------------

### Define RAML 1.0 API with Reusable Type Definitions

Source: https://context7.com/raml-org/raml-examples/llms.txt

Shows how to define global types in RAML 1.0 that can be reused across the API, illustrating object types with properties and constraints, and referencing them in endpoint responses.

```yaml
#%RAML 1.0
title: API with Types
types: # global type definitions that can be reused throughout this API
  User: # define type named `User`
    type: object
    properties:
      firstName: string
      lastName:  string
      age:
        type: integer
        minimum: 0
        maximum: 125
/users/{id}:
  get:
    responses:
      200:
        body:
          application/json:
            type: User # reference to global type definition
```

--------------------------------

### RAML Libraries for Modular Design

Source: https://context7.com/raml-org/raml-examples/llms.txt

Shows how to create and use RAML libraries for modular API design. Libraries allow sharing types, traits, and resource types across multiple API specifications.

```yaml
#%RAML 1.0 Library
# types.lib.raml
types:
  Person:
    properties:
      name: string
      age: integer

```

```yaml
#%RAML 1.0
title: Main API

uses:
  types-lib: types.lib.raml

/person:
  get:
    responses:
      200:
        body:
          application/json:
            type: types-lib.Person

```

--------------------------------

### Monetary Value Types

Source: https://context7.com/raml-org/raml-examples/llms.txt

Shows how to define complex number types with precision constraints for monetary values in RAML.

```APIDOC
## Monetary Value Types

Complex number types with precision constraints for financial applications.

### Type Definitions

```yaml
#%RAML 1.0 Library
usage: Types to be used for monetary values

types:
  ZeroValue:
    description: zero-value numbers, accepting either the 0 or 0.00 (hundreths) forms
    type: number
    enum:
      - 0
      - 0.00
  HundredthsValue:
    description: non-zero two-decimal place values (positive and negative)
    type: number
    multipleOf: 0.01
  MonetaryValue:
    description: this type describes any monetary value comprised between -9,999,999,999,999.99 and 9,999,999,999,999.99
    type: ZeroValue | HundredthsValue
    default: 0.00
    minimum: -9999999999999.99
    maximum: 9999999999999.99
    examples:
      zero: 0
      zerozero: 0.00
      tenten: 10.10
      negative: -0.10
```
```

--------------------------------

### Date and Time Types

Source: https://context7.com/raml-org/raml-examples/llms.txt

Illustrates RAML's support for various date and time formats, including date-only, time-only, datetime-only, and RFC-formatted datetimes.

```APIDOC
## Date and Time Types

RAML supports multiple date/time formats including date-only, time-only, datetime-only, and datetime with RFC formatting.

### Type Definitions

```yaml
#%RAML 1.0 Library

types:
  birthday:
    type: date-only # no implications about time or offset
    example: 2015-05-23
  lunchtime:
    type: time-only # no implications about date or offset
    example: 12:30:00
  fireworks:
    type: datetime-only # no implications about offset
    example: 2015-07-04T21:00:00
  created:
    type: datetime
    example: 2016-02-28T16:41:41.090Z
    format: rfc3339 # the default, so needn't be specified
  If-Modified-Since:
    type: datetime
    example: Sun, 28 Feb 2016 16:41:41 GMT
    format: rfc2616 # this time it's required as otherwise the example is in an invalid format
```
```

--------------------------------

### RAML Overlay for Localizing API Specifications

Source: https://context7.com/raml-org/raml-examples/llms.txt

Explains how to use RAML overlays to modify an API specification for localization purposes without altering the original structure. This is useful for adapting documentation and behavior for different regions.

```yaml
#%RAML 1.0
# librarybooks.raml
title: Book Library API
documentation:
  - title: Introduction
    content: Automated access to books
  - title: Licensing
    content: Please respect copyrights on our books.
/books:
  get:
    description: The collection of library books

```

```yaml
#%RAML 1.0 Overlay

```

--------------------------------

### RAML DataType Fragments for Reusable Types

Source: https://context7.com/raml-org/raml-examples/llms.txt

Illustrates the creation and inclusion of RAML DataType fragments. These fragments define reusable types in separate files, promoting better organization and maintainability.

```yaml
#%RAML 1.0 DataType
# Email.dataType.raml
usage: provides a pattern to validate against an email string

pattern: ^.+@.+\..+$

```

```yaml
#%RAML 1.0 DataType
# User.dataType.raml
usage: provides a type that stores user information

description: A simple User
properties:
  name: string
  email: !include Email.dataType.raml
  homepage:
    description: User's homepage
    type: !include Url.dataType.raml

```

```yaml
#%RAML 1.0
title: DataType Include Example

types:
  User: !include User.dataType.raml # include external type declaration

```

--------------------------------

### RAML 1.0 Type Inheritance, Union Types, and Discriminators

Source: https://context7.com/raml-org/raml-examples/llms.txt

Illustrates advanced type modeling in RAML 1.0, including type inheritance, union types for polymorphism, and discriminators for differentiating between object types.

```yaml
#%RAML 1.0
title: My API with Types
mediaType: application/json
types:
  Person:
    type: object
    discriminator: kind # reference to the `kind` property of `Person`
    properties:
      firstname: string
      lastname: string
      title?: string
      kind: string # may be used to differentiate between classes that extend from `Person`
  Phone:
    type: string
    pattern: "^[0-9|-]+$" # defines pattern for the content of type `Phone`
  Manager:
    type: Person # inherits all properties from type `Person`
    properties:
      reports: Person[] # array type where `[]` is a shortcut
      phone:  Phone
  Admin:
    type: Person # inherits all properties from type `Person`
    properties:
      clearanceLevel:
        enum: [ low, high ]
  AlertableAdmin:
    type: Admin # inherits all properties from type `Admin`
    properties:
      phone: Phone
  Alertable: Manager | AlertableAdmin # union type; either a `Manager` or `AlertableAdmin`
/orgs/{orgId}:
  get:
    responses:
      200:
        body:
          application/json:
            type: Org
            example:
              onCall:
                firstname: nico
                lastname: ark
                kind: AlertableAdmin
                clearanceLevel: low
                phone: "12321"
```

--------------------------------

### RAML with Inline and Included JSON Schema

Source: https://context7.com/raml-org/raml-examples/llms.txt

Demonstrates how to integrate JSON Schema for type definitions directly within RAML or by including external JSON files. This allows for robust data validation and clear schema definition.

```yaml
#%RAML 1.0
title: Using XML and JSON Schema

schemas: # can also be used with 'types'
  PersonInline: |
    {
      "title": "Person Schema",
      "type": "object",
      "properties": {
        "firstName": {
          "type": "string"
        },
        "lastName": {
          "type": "string"
        },
        "age": {
          "description": "Age in years",
          "type": "integer",
          "minimum": 0
        }
      },
      "required": ["firstName", "lastName"]
    }
  PersonInclude: !include person.json

/person:
  get:
    responses:
      200:
        body:
          application/json:
            schema: PersonInline # can also be used with 'type'
  post:
    body:
      application/json:
        schema: | # can also be used with 'type'
          {
            "title": "Body Declaration Schema",
            "type": "object",
            "properties": {
              "firstName": {
                "type": "string"
              },
              "lastName": {
                "type": "string"
              }
            }
          }

```

--------------------------------

### RAML Annotation Targets

Source: https://context7.com/raml-org/raml-examples/llms.txt

Demonstrates how to restrict annotations to specific API elements in RAML using the `allowedTargets` property. This ensures annotations are applied only where intended.

```yaml
#%RAML 1.0
title: Illustrating allowed targets
mediaType: application/json
annotationTypes:
  meta-resource-method:
    allowedTargets: [ Resource, Method ]
  meta-data:
    allowedTargets: TypeDeclaration
types:
  User:
    type: object
    (meta-data): on an object; on a data type declaration
    properties:
      name:
        type: string
        (meta-data): on a string property
/users:
  (meta-resource-method): on a resource
  get:
    (meta-resource-method): on a method
    responses:
      200:
        body:
          type: User[]
          (meta-data): on a body

```

--------------------------------

### RAML Annotations for Metadata

Source: https://context7.com/raml-org/raml-examples/llms.txt

Illustrates the use of annotations in RAML to add custom metadata to API elements. Annotations can be used for documentation, testing, or code generation purposes.

```yaml
#%RAML 1.0
title: Illustrating annotations
mediaType: application/json
annotationTypes:
  testHarness:
    type: string # This line may be omitted as it's the default type
  badge:         # This annotation type, too, allows string values
  clearanceLevel:
    properties:
      level:
        enum: [ low, medium, high ]
        required: true
      signature:
        pattern: "\\d{3}-\\w{12}"
        required: true
/users:
  (testHarness): usersTest
  (badge): tested.gif
  (clearanceLevel):
    level: high
    signature: 230-ghtwvfrs1itr

```

--------------------------------

### RAML Query Parameters for Filtering and Validation

Source: https://context7.com/raml-org/raml-examples/llms.txt

Illustrates the use of query parameters in RAML for filtering nested fields and validating query strings. This enables dynamic data retrieval and ensures data integrity.

```yaml
#%RAML 1.0
title: My Querying API
mediaType: application/json

/search:
  get:
    queryString: # at least one parameter required
      minProperties: 1
      properties:
        id?: integer
        name?: string
        q?: string
    responses:
      200:
        body: array

/books:
  get:
    queryParameters: # filter results by nested fields, e.g. /books?author[name]=
      /^author\[[a-zA-Z]\]+$/: string
    responses:
      200:
        body:
          properties:
            title: string
            author:
              properties:
                name: string
                origin: string
                awarded: boolean

```

--------------------------------

### RAML Advanced Annotations with Nil and Union Types

Source: https://context7.com/raml-org/raml-examples/llms.txt

Showcases advanced annotation types in RAML, including nil types for flag-style metadata and union types for optional values. This allows for more expressive metadata definitions.

```yaml
#%RAML 1.0
title: Illustrating annotations
mediaType: application/json
annotationTypes:
  deprecated: nil
  experimental: string | nil
  feedbackRequested: string?
  testHarness:
    type: string
  clearanceLevel:
    properties:
      level:
        enum: [ low, medium, high ]
        required: true
      signature:
        pattern: "\\d{3}-\\w{12}"
        required: true
/groups:
  (experimental): 
  (feedbackRequested): 
/users:
  (testHarness): usersTest
  (clearanceLevel):
    level: high
    signature: 230-ghtwvfrs1itr
  get:
    (deprecated): 
    (experimental): 
    (feedbackRequested): Feedback committed! 
    responses:
      200:

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.