RAML API defining issues

25 views
Skip to first unread message

Paweł Nawrocki

unread,
Oct 10, 2016, 11:53:26 AM10/10/16
to OpenLMIS Dev
Hello everybody!

Recently, I was trying to update our raml files by adding response body schemas. This seem to have been already mentioned before on this group, but I guess no one found the way to solve it (https://groups.google.com/forum/#!topic/openlmis-dev/_7GciBqHLfU). There seems to be a problem with defining "arrays of objects of specified type". We define a schema like this:

- facilityArray: |
 {
 "type": "array",
 "items": { "type": "object", "$ref":"#/schemas/facility" }

 }

Then, if we put this as a schema for response body, the integration test would fail on following line:

assertThat(RAML_ASSERT_MESSAGE, restAssured.getLastReport(), RamlMatchers.hasNoViolations());

saying, that "the reference schema could not be resolved" (more info in the topic linked above).


I have not found any solution or live example in official raml docs, though I found a post on their official forum with similar issue (http://forums.raml.org/t/set-body-to-be-array-of-defined-schema-objects/1566).
From what is suggests, RAML 0.8 does not fully support that kind of declaration, or at least it's related tools do not.

Does anyone know a solution to this issue?

If we can't come up with a solution to this, we may switch to RAML 1.0 (although we might also need to revise if our tools support it), or have some workaround (like defining the above facilityArray as array of objects without referencing schema (so we're losing consistency), or copy-paste facility's definition in place of reference (making redundant declaration) - those two are proven to work).

Best regards,
Paweł

Chongsun Ahn

unread,
Oct 12, 2016, 8:39:56 AM10/12/16
to Paweł Nawrocki, OpenLMIS Dev
Hey Paweł,

From doing some research, it appears that it would be ideal to go to RAML 1.0, since it introduces the idea of something called “data types,” which appears to do what we want in defining JSON schemas. Then we could define our schemas in the more readable RAML format instead of using JSON Schema format. However, our RAML testing tool does not have support for RAML 1.0 yet, and it’s not clear when that support will be implemented.

One way we could do it is try to (via a script or tool) replace all JSON objects that contain the $ref property and expand them to their JSON Schema definitions. This seems like it might take some work. I don’t think I would recommend trying it this way.

Another way we could do it is to define our JSON Schemas in external JSON files and then reference them in the RAML like so:

  - facility: !include schemas/facility.json

  - facilityArray: |
      {
          "type": "array",
          "items": { "type": "object", "$ref": "schemas/facility.json" }
      }

That would create a number of extra files, but I haven’t determined a way to reference JSON Schemas in RAML.

Shalom,
Chongsun
​
-- ​
There are 10 kinds of people in this world; those who understand binary, and those who don’t.

Software Development Engineer
 
VillageReach Starting at the Last Mile
2900 Eastlake Ave. E, Suite 230,  Seattle, WA 98102, USA
DIRECT: 1.206.512.1536   CELL: 1.206.910.0973   FAX: 1.206.860.6972
SKYPE: chongsun.ahn.vr
Connect on Facebook, Twitter and our Blog

--
You received this message because you are subscribed to the Google Groups "OpenLMIS Dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to openlmis-dev...@googlegroups.com.
To post to this group, send email to openlm...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/openlmis-dev/b42f68cc-9798-4568-b049-172c0b8ba858%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Paweł Nawrocki

unread,
Oct 24, 2016, 1:43:38 PM10/24/16
to OpenLMIS Dev, pnaw...@soldevelo.com
Hey!

It seems that we keep referencing schemas the wrong way, and it works only because we don't validate raml in those controller tests.
Schemas are still being references directly, instead of switching to the style you suggested.
I'm curious if we're leaving this for now as it is, or should we should start enforcing the proper style somehow?

Cheers,
Paweł

To post to this group, send email to openl...@googlegroups.com.

Chongsun Ahn

unread,
Oct 24, 2016, 2:16:53 PM10/24/16
to Paweł Nawrocki, OpenLMIS Dev
Hey Paweł,

Yes, we should be switching over to the style I’ve suggested. As for how we will be refactoring the current source code, our team here is working on a ticket to give guidance on how to document this new way in the RAML when working on a ticket. Instead of having one person try to refactor the entire RAML to the new way, we’ll probably be refactoring parts of it over time, as we work on different parts of the code. I welcome any feedback you have for this process.


Shalom,
Chongsun
​
-- ​
There are 10 kinds of people in this world; those who understand binary, and those who don’t.

Software Development Engineer
 
VillageReach Starting at the Last Mile
2900 Eastlake Ave. E, Suite 230,  Seattle, WA 98102, USA
DIRECT: 1.206.512.1536   CELL: 1.206.910.0973   FAX: 1.206.860.6972
SKYPE: chongsun.ahn.vr
Connect on Facebook, Twitter and our Blog

Chongsun Ahn

unread,
Nov 9, 2016, 7:51:35 PM11/9/16
to OpenLMIS Dev
Hey everyone,

I have been working on establishing the new pattern of JSON schemas for our RAML (OLMIS-894) for OpenLMIS v3 and have checked in some changes to the RAML in the Reference Data Service. You can see an example of how JSON schema is defined in the RAML (for a right and a rightArray, a list of rights) at the following link:


The actual JSON schema definition for a right is in a separate file at this link:


As we make changes to the API definition in the RAML for v3, we should try to follow this pattern in defining JSON schemas. Please let me know if you have any feedback.


Shalom,
Chongsun
​
-- ​
There are 10 kinds of people in this world; those who understand binary, and those who don’t.

Software Development Engineer
 
VillageReach Starting at the Last Mile
2900 Eastlake Ave. E, Suite 230,  Seattle, WA 98102, USA
DIRECT: 1.206.512.1536   CELL: 1.206.910.0973   FAX: 1.206.860.6972
SKYPE: chongsun.ahn.vr
Connect on Facebook, Twitter and our Blog

On Oct 24, 2016, at 10:43 AM, Paweł Nawrocki <pnaw...@soldevelo.com> wrote:

Chongsun Ahn

unread,
Nov 9, 2016, 7:53:20 PM11/9/16
to OpenLMIS Dev
Hey everyone,

I also forgot to mention that this pattern is documented in our style guide (https://github.com/OpenLMIS/openlmis-template-service/blob/master/STYLE-GUIDE.md).

Shalom,
Chongsun
​
-- ​
There are 10 kinds of people in this world; those who understand binary, and those who don’t.

Software Development Engineer
 
VillageReach Starting at the Last Mile
2900 Eastlake Ave. E, Suite 230,  Seattle, WA 98102, USA
DIRECT: 1.206.512.1536   CELL: 1.206.910.0973   FAX: 1.206.860.6972
SKYPE: chongsun.ahn.vr
Connect on Facebook, Twitter and our Blog

Reply all
Reply to author
Forward
0 new messages