How can I create JSON schemas from YAML types?


#1

Hi everybody,

I’ve been using RAML for about 3 months now, When we were about to publish our first API spec, RAML 1.0 was released and we decided to delay delivery and migrate to 1.0 due to the new data types system which is much better than 0.8’s types.

So now I have all my types declared in YAML, but I still need to publish JSON schemas for my clients so they can validate the JSONs coming in and out of the API.

Is there a tool that will convert a YAML type to a JSON schema automatically?

Thanks in advance,
rojocapo


#2

@rojocapo, cool the wait was definitely worth as it seems :blush:

Indeed there will be tools coming out over the next couple of weeks that does exactly that. I’ll let you know when I have more news on that. There is a team working on this in our workgroup.


#3

@christian_vogel That’s fantastic news! I was spending 80% of my time writing the schemas instead of focusing on the API itself. I find YAML types much more intuitive than JSON schemas, so easy to read and write.

You can’t imagine how much I hate writing JSON schemas with such a ridiculous amount of quotation marks, even for keywords. JSON schemas have horrible style, they make my eyes hurt when I read them. Good riddance!


#4

Amazing! I was coming here to ask this question as well. Will this be a separate tool or part of an existing one? Which language will be used to run it? Node.js?


#5

It will most likely Nodejs application that you will be able to run separately and in the near future inside the api-workbench.


#6

I can’t wait for this as well!! If we can convert XML Schema and JSON Schema to YAML types… then back again, both in the API workbench and as a standalone tool… RAML will have elevated itself to a whole new level that as far as I can tell nothing else touches!


#7

Yes! Glad to hear it! Is there any timeline for when you expect this to be out or a public repo which has a work in progress version?


#8

Hi, any news about this? I am also looking for a RAML 1.0 HTML generator. Thanks


#9

There is a separate thread on the RAML2HTML project going on. @Mike_Stowe is leading the effort for 1.0 support with that project.


#10

Hi,

I am following up on the JSON schema auto-generator with RAML 1.0 support. Any news?

Thanks


#11

Nothing yet, a lot of efforts from different people are currently going into finalizing 1.0 and with that the first tooling that supports 1.0 such as raml2html, MuleSoft’s API Designer/Console, parser, and more.


#12

Has there been any progress on this? I also need to be able to generate JSON Schemas from YAML types.


#13

We are planning and scoping that out at the moment. I will let you know when I have something more concrete. If I do not come back in the next few days, please send another note here and mention my name :wink:


#14

I actually found an easy way to do it! Since the YAML Types have almost a 1 to 1 mapping of info to JSON Schema, you can use the library PyYaml to import the type from a separate .raml file, add the needed schema headers, and spit out a json! You do need to be a bit more verbose than RAML requires to get around the limitations that PyYaml has (not being able to handle !include) and to get the information to map 1 to 1, but its a solution for now!


#15

@christian_vogel
Hi Christian,

Has there been any news regarding this issue? I have just had a meeting with my customer and they have decided that the API documentation must include JSON schemas. The companies that consume the APIs are not interested in RAML. They want HTML documentation, JSON schemas that they can use to validate the messages and JSON examples. So now basically RAML is just for my own use so I can write the documentation, but I need to generate JSON schemas for publication.

Can you help me solve this issue? I need both RAML2HTML working and JSON schema generation ASAP.

Please advise,

Thanks


#16

We will work on that out of the following repo https://github.com/raml-org/ramldt2jsonschema, and you can also find a story about what we try to achieve here. It will take some time and in phase 1 you will have a canonical JSON schema since everything else might be a bit more difficult. The guys who will work on all that give their best to provide that by the time indicated inside the story.


#17

Unfortunately I use inheritance everywhere so phase 1 does not apply to my use case. Your response really has me worried now.


#18

You can still use inheritance within your data type no worries.

For example, lets assume you have the following type and you want to create a JSON schema for “InheritanceSong”.

types:
  InheritanceSong:
    type: Song
    properties:
      somethingElse: string
  Song:
    properties:
      title:
        type: string
        example: Great
      length: string

You would basically generate the following JSON schema:

{
  "additionalProperties": true,
  "type": "object",
  "required": true,
  "properties": {
    "title": {
      "type": "string",
      "example": "Great",
      "required": true
    },
    "length": {
      "type": "string",
      "required": true
    },
    "somethingElse": {
      "type": "string",
      "required": true
    }
  }
}

Isn’t that what you want?


#19

I want a utility to create the schemas for me. Doing this manually for all my types is not trivial at all considering the amount of classes and complexity.


#20

Maybe I was not very clear about that. So sorry.

Of course, you will not have to do anything. The tool which I have linked in here will do generate the schema for you.