How can I create JSON schemas from YAML types?


#21

Phase 1 explicitly says that inheritance will not be supported.


#22

The “no inheritance” is referred to the canonical form that will be produced in-memory, not the input of data types. The input can have any structure and the output will be a single JSON schema. I think the confusion you have was my fault putting the description of the canonical form behind the “data types” text. I changed that inside the description.

Again, inheritance will be perfectly supported in phase 1 also.


#23

Just got off another call with my customer. They are asking for us to deliver JSON schemas ASAP. Unfortunately since ramldt2jsonschema has not been released, I’ll probably have to buy an Altova tool and model all my classes over again to create the JSON schemas. It has been horribly frustrating to work with RAML. In hindsight, I should have chosen some other platform last year because this feels like a hobby tool, not something for professional enterprise use.


#24

I am really sorry that you feel that way. The team and the community does everything they can to provide everyone with the things they need. That, unfortunately, does take some time since people dedicate their own private time to projects like that.

I would still love to hear why it’s being frustrating to work with RAML. Maybe something in the direction what tools you are currently missing to successfully work with RAML.

I, and everyone else, understands your frustration; and again I am really sorry to hear that. Why not trying the current v1 branch for the ramldt2jsonschema that should work already and still give us feedback?


#25

Hi Christian,

I didn’t see the test branches, only master which is empty. I’ll check that out and get back to you with the results.

Any suggestions on getting HTML/PDF/Word/younameit documentation generated from my RAML 1.0 files? I don’t mind paying a fee since I use RAML for professional use. I can’t expect API consumers to learn RAML syntax and just publish the RAML files. Ideally the documentation should be in interactive HTML like what raml2html produces.


#26

I completely agree and I am not sure if you have seen the updates to raml2html here. There is some work still to do on the new template but it should give you what you need. I think Kevin would be very happy to have you take a look and give him feedback. :wink:


#27

I need help to get ramldt2jsonschema app working. Please describe each step in more detail.
I am not a developer so I need all the prerequisites and step-by-step instructions.
I need to generate the JSON schema from almost 500 Raml files!


#28

Hi nwelna, Would you be willing to share your PyYaml script with me? I am a technical writer not a developer and I need to generate JSON requests from 200 or more REST endpoints. The API is generated using RAML and the RAML contains the schema. So I am seeking an automated way to generate the JSON. Hope you can post your script! Thanks.


#29

@bschramm you said you are trying to create JSON Schema from 500 RAML files? Is the schema defined IN the RAML files and you are trying to extract it to separate .json files? I cant imagine that many RAML files and not a single include using broken out JSON Schema files?


#30

Yes that is right. The RAML files contain the schemas and I want to generate JSON from them.
Have you used: the following: ramldt2jsonschema as described here:


I am seeking detailed instructions for setting this up and running it.


#31

Sorry for late reply… I have not used that library.


#32

@bschramm, what do you want to know?


#33

Hi Christian,
I am a technical writer not a developer.
I have about 500 RAML files that the Eng team creates.
Within the RAML are schemas, for example:
{
“id” : “http://api.covisint.com/idm/schema/person/v1”,
"$schema" : “http://json-schema.org/draft-04/schema”,
“type” : “object”,
“description” : “Schema representing a person resource.”,
“extends” : {
"$ref" : “http://api.company.com/schema/realmScopedResourceV2#
},
“properties” : {
“id”: {
“maxLength” : 100
},
“version”: {
“description” : “The current version for this resource. Exists once the resource has been saved. This is mandatory for PUT requests, but will be ignore on POST requests.”
},
“status” : {
“enum” : [ “pending”, “rejected”, “active”, “suspended”, “inactive”, “locked”, “expired”, “unactivated”, “preterminated” ],
“description” : “The person’s account status, which is read-only. Statuses can be changed through tasks.”
},
“name” : {
“type” : “object”,
“description” : “A container for the person’s name elements”,
“properties” : {
“prefix” : {
“type” : “string”,
“description” : “The prefix to the person’s name. For example: Mr., Mrs., Rev.”,
“maxLength” : 100,
“required”: false
},
“given” : {
“type” : “string”,
“description” : “The person’s given (first) name.”,
“maxLength” : 150,
“required”: true
},
“middle”: {
“type” : “string”,
“description” : “The person’s middle name(s).”,
“maxLength” : 60,
“required”: false
},
“surname”: {
“type” : “string”,
“description” : “The person’s surname or family name.”,
“maxLength” : 150,
“required”: true
},
“suffix” : {
“type” : “string”,
“description” : “The person’s name suffix. For example: Jr., Ph.D., M.D.”,
“maxLength” : 50,
“required”: false
}
},
“required”: true
},
“username” : {
“type” : “string”,
“maxLength” : 100,
“description” : “The username of the person.”
},
“authDomain” : {
“type” : “string”,
“description” : “This person’s authentication domain.”,
“maxLength” : 50
},
“addresses” : {
“type” : “array”,
“description” : “A container for the person’s addresses.”,
“minItems” : 0,
“items” : { “ref” : “http://api.company.com/idm/schema//address#” },
“required”: false
},
“language” : {
“type” : “string”,
“maxLength” : 2,
“description” : “The person’s preferred language, in ISO639-1 format.”,
“required”: true
},
“timezone” : {
“type” : “string”,
“description” : “The person’s preferred timezone. See http://docs.oracle.com/javase/7/docs/api/java/util/TimeZone.html#getAvailableIDs()”,
“required”: true
},
“phones” : {
“type” : “array”,
“description” : “A container for the person’s phone number(s).”,
“minItems” : 0,
“items” : { “$ref” : “http://api.company.com/idm/schema/phone#” },
“required”: false
},
“title” : {
“type” : “string”,
“maxLength” : 60,
“description” : “The person’s job title”,
“required”: false
},
“email” : {
“type” : “string”,
“maxLength” : 1000,
“description” : “The person’s email address.”,
“required”: true
},
“organization” : {
“description” : “The organization to which the person belongs.”,
"$ref": “http://api.company.com/schema/resourceReference#”,
“required”: true
},
“currency” : {
“type” : “string”,
“maxLength” : 3,
“description” : “The person’s preferred currency. Must be a valid ISO4217 currency code.”,
“required”: false
},
“attributes”:{
“type”: “array”,
“minItems”: 0,
“required”: false,
“description”: “The attribute templates for persons.”,
“items”: {
“id”: { “type”: “string”, “description”: “The key name for the person’s attribute template data.” },
“name”: { “type”: “string”, “description”: “The name of the extended attribute.” },
“value”: { “type”: “string”, “description”: “The text value.” }
}
}
}
}

What I want to do, if possible, is to generate JSON requests from all these schemas embedded in the Raml.
I saw your tool, ramldt2jsonschema, and wanted to implement it. I was not clear in the following command what the values for are supposed to be.
dt2js

The rail types in my included example are “object”, string" and “array” Do you have to enter them one at at a time? Or would the following work: dt2js <myramlfile.raml> <object, string, array>

As I am looking at my raml example, is it already in JSON format?
Sorry if these are “stoopid” questions, but I have about 500 schemas and I need to create sample JSON requests from them!
Thanks for any help!
Barbara


#34

@christian_vogel,

Well, it’s been almost 20 months since my original post. RAML2HTML is working pretty well now, but I still need to autocreate json schemas.

I tried ramldt2jsonschema today and it creates schemas for a raml that does not use “!include” or “uses”. However, all my projects have at least 20 files, with two levels of “uses” depth. My projects share a set of core libraries.

What would be the best way to solve this? Rewriting the projects in a single file is horrible and does not allow for code reuse. There’s also the issue of namespaces, I would be duplicating type names when flattening the types into a single file.

Any suggestions? Is there a plan to add !include and uses to ramldt2jsonschema?

Thanks


#35

Is there a plan to add !include and uses to ramldt2jsonschema?

Yes, we plan that to be done asap. I can’t give you a date yet as the team had to switch gears, but they come back to this soon. Please watch this issue for any updates.