DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Refcards Trend Reports
Events Video Library
Refcards
Trend Reports

Events

View Events Video Library

Zones

Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks

Generative AI has transformed nearly every industry. How can you leverage GenAI to improve your productivity and efficiency?

SBOMs are essential to circumventing software supply chain attacks, and they provide visibility into various software components.

Related

  • Modify JSON Data in Postgres and Hibernate 6
  • How To Get Cell Data From an Excel Spreadsheet Using APIs in Java
  • Doubly Linked List in Data Structures and Algorithms
  • Linked List in Data Structures and Algorithms

Trending

  • How My AI Agents Learned to Talk to Each Other With A2A
  • Advanced Insight Generation: Revolutionizing Data Ingestion for AI-Powered Search
  • Software Specs 2.0: An Elaborate Example
  • MCP and The Spin-Off CoT Pattern: How AI Agents Really Use Tools
  1. DZone
  2. Data Engineering
  3. Data
  4. Common Problems Found in RAML 0.8 API Specifications

Common Problems Found in RAML 0.8 API Specifications

Let's view some common problems found in RAML 0.8 API specifications.

By 
Ramesh janga user avatar
Ramesh janga
·
Aug. 01, 19 · Tutorial
Likes (1)
Comment
Save
Tweet
Share
9.9K Views

Join the DZone community and get the full member experience.

Join For Free

As of June 10, 2019, the code editor (one of the two editors in Design Center’s API Designer) uses stricter validation by default for RAML API-specification projects that were created before this date. If you open in the code editor a published API specification that is written in RAML 0.8, and you see violation (red) or warning (orange) messages. This list might help you to resolve the problems in your RAML.

Using a reserved name for a schema

If you use a reserved name as the name of a schema, the editor displays this message:

‘schemaName’ cannot be used to name a custom schema

Examples of reserved names are string, integer, number, and object. Any name that is used in the RAML specification cannot be used as the name for a schema.

For example, this API specification would cause the editor to display the message:

#%RAML 0.8

title: Example API Spec

schemas:
 string:
   type: string

To resolve the problem, you would need to use a different name in the schema declaration:

#%RAML 0.8

title: Example API Spec

schemas:
 customString:
   type: string

Problems when validating examples

Not using a data type of string for the example of a Boolean enum

Whether the values for a Boolean enum are both strings or Boolean values, the example of the enum must be a string. To illustrate the violation, this API specification shows an example using the wrong data type.

#%RAML 0.8
title: ExampleRAML
/nob:
  head:
    responses:
      204:
        headers:
          X-NOB-Exists:
            enum: [true, false]
            example: true

RAML 0.8 supports enum values as strings only, not as boolean values. Also, in the example RAML above, no data type for the enum is declared. In RAML 0.8, when a data type is not declared, it is assumed to be string.

Therefore, the values in the enum in the incorrect example above must be in quotation marks. That’s because the data type of an example must be the same as the data type of the element that it is an example of.

The last two lines of the example RAML above should then be as they are in this correction:

            enum: ["true", "false"]
            example: "true"

Not using a required property in the example of a schema that defines that property

If a schema defines a required property, the example of that schema must use that property. In this example of the problem, the following API specification defines a response for the endpoint /order/{id}. The definition includes two files: get_order_response_schema.json and get_order_response.json.

#%RAML 0.8
title: ExampleRAML
version: 1.0
...
/order:
  displayName: Orders API
  /create:
    ...

  /{id}:
    displayName: Get Order by OrderId
    description: This operation will get an order by order ID from Salesforce.
    get:
      description: This operation returns the order from Salesforce by Fulfillment Order ID, not by the Salesforce unique ID.
      responses:
        200:
          body:
            application/json:
              schema: !include get_order_response_schema.json
              example: !include get_order_response.json

The file get_order_response_schema.json defines the property's OrderId as a required property.

{
"type":"object",
"$schema": "http://json-schema.org/draft-03/schema",
"id": "http://com.mulesoft.demo.orders.get.json.order",
"required":false,
"properties":{
      ...
      "sfOrderId": {
        "type":"string",
        "id": "http://com.mulesoft.demo.orders.create.json.get.sfOrderId",
        "required":true
      },

The example of the schema is in get_order_response.json. However, the name of the required property is misspelled as sOrderId.

{
  "orderId": 14523,
  "sOrderId": "fadfead3524523",
  "sfAccountId": "fedfes3653635",
  "orderName": "Order From Manufacturing-Company, Inc.",
  "total": 174.92,
  "orderType": "E-Commerce Order",
  "description": "8 widgets",
  "orderDate": "04-03-2018"
}

Not using in an example of a schema the data type that the schema defines

For example, the schema in the following API specification defines the data type for the property title as an object; however, an array is used in the example of the schema.

#%RAML 0.8
title: ExampleRAML
schemas:
  - presentation: |
      {  "$schema": "http://json-schema.org/draft-03/schema",
         "type": "object",
         "properties": {
           "title":  { "type": "string" }
         }
      }

/presentations: &presentations
  type: { typedCollection: { schema: presentation } }
  get:
    responses:
      200:
       body:
         application/json:
           example: |
             [
              {
                  "title": "Presentation Video"
              },
              {
                  "title": "Environment Spec Report"
              }
              ]

Using 0 or 1 as the value of an example of a Boolean

An example for a Boolean must have a value of "true" or "false". In this API specification illustrating the violation, the value of the example for the form parameter is_public is incorrect.

#%RAML 0.8
title: ExampleRAML

/upload:
  post:
    description: |
      Upload a photo
    body:
      multipart/form-data:
        formParameters:
          title:
            description: The title of the photo.
          is_public:
            type: boolean
            example: 1

Not including a property in an example

If an example is missing a property of the type that it is exemplifying, the editor displays this violation message:

should have required property 'property name'

For example, the property age is missing in the example:

#%RAML 0.8
title: Example API Spec

/clients:
  get:
    responses:
      200:
        body:
          application/json:
            schema: |
              {
                "$schema": "http://json-schema.org/draft-03/schema",
                "properties": {
                    "firstName": {
                      "type": "string"
                    },
                    "lastName": {
                      "type": "string"
                    },
                    "age": {
                      "type": "number",
                      "required": true
                    }
                },
                "required": false,
                "type": "object"
              }
            example:
              firstName: John
              lastName: Smith

Either add the property to the example or, in the type declaration, declare the property as optional.

In this case, the property is added to the example:

#%RAML 0.8
title: Example API Spec

/clients:
  get:
    responses:
      200:
        body:
          application/json:
            schema: |
              {
                "$schema": "http://json-schema.org/draft-03/schema",
                "properties": {
                    "firstName": {
                      "type": "string"
                    },
                    "lastName": {
                      "type": "string"
                    },
                    "age": {
                      "type": "number",
                      "required": true
                    }
                },
                "required": false,
                "type": "object"
              }
            example:
              firstName: John
              lastName: Smith
              age: 30

In this case, the property is declared as optional:

#%RAML 0.8
title: Example API Spec

/clients:
  get:
    responses:
      200:
        body:
          application/json:
            schema: |
              {
                "$schema": "http://json-schema.org/draft-03/schema",
                "properties": {
                    "firstName": {
                      "type": "string"
                    },
                    "lastName": {
                      "type": "string"
                    },
                    "age": {
                      "type": "number",
                      "required": false
                    }
                },
                "required": false,
                "type": "object"
              }
            example:
              firstName: John
              lastName: Smith

Thank you!

To get in-depth knowledge on Mulesoft API, you can enroll for live Mulesoft training by OnlineITGuru with 24/7 support and lifetime access

API Data Types Property (programming) Schema Data (computing)

Opinions expressed by DZone contributors are their own.

Related

  • Modify JSON Data in Postgres and Hibernate 6
  • How To Get Cell Data From an Excel Spreadsheet Using APIs in Java
  • Doubly Linked List in Data Structures and Algorithms
  • Linked List in Data Structures and Algorithms

Partner Resources

×

Comments

The likes didn't load as expected. Please refresh the page and try again.

ABOUT US

  • About DZone
  • Support and feedback
  • Community research
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Core Program
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 3343 Perimeter Hill Drive
  • Suite 100
  • Nashville, TN 37211
  • [email protected]

Let's be friends: