Generate JSON Schema custom keys

[jmatsushita]

Hi there,

I was wondering if it was possible to add arbitrary keys in the generated JSON Schema. For instance:

# Test

- text (string) - My string

Currently generates:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "description": "My string"
    }
  }
}

But how could I generate for instance?

{
  "id": "https://example.org/test",
  "description": "My test schema",
  "$myothercustomkey": true,
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "description": "My string"
    }
  }
}

[kylef]

There isn't a way to do this other than overriding the generated JSON Schema with your own. For example:

+ Response 200 (application/json)
    + Attributes
        + text (string) - My string

    + Schema

            { "id": "https://example.org/test" }

[jmatsushita]

Unless I'm doing something wrong with Drafter this replaces the Schema with the value of + Schema rather than merging the key. It doesn't work for my use case since I want to use MSON as the Schema DSL. Thanks though!

[kylef]

I've just confirmed the behaviour I mentioned still works:

# GET /

+ Response 200 (application/json)
    + Attributes
        + text (string) - My string

    + Schema

            { "id": "https://example.org/test" }

With the current version of Drafter API Blueprint parser (3.1.1) the correct JSON Schema is present in the parse result:

[  
   {  
      "element":"asset",
      "meta":{  
         "classes":[  
            "messageBody"
         ]
      },
      "attributes":{  
         "contentType":"application/json"
      },
      "content":"{\n  \"text\": \"\"\n}"
   },
   {  
      "element":"asset",
      "meta":{  
         "classes":[  
            "messageBodySchema"
         ]
      },
      "attributes":{  
         "contentType":"application/json"
      },
      "content":"{ \"id\": \"https://example.org/test\" }\n"
   }
]

[w-vi]

If there are more folks who would like to extend the JSON Schema let us know, it looks like valid feature request.

[jmatsushita]

You're generating application/json rather than application/schema+json.

I get the same thing as you (with the same version of Drafter), but compare with

# GET /
+ Response 200 (application/json)
    + Attributes (Test)

# Data Structures

# Test

 - text (string) - My string

Which generates the properly typed application/schema+json

[
 {
   "element": "dataStructure",
   "content": [
     {
       "element": "Test"
     }
   ]
 },
 {
   "element": "asset",
   "meta": {
     "classes": [
       "messageBody"
     ]
   },
   "attributes": {
     "contentType": "application/json"
   },
   "content": "{\n  \"text\": \"\"\n}"
 },
 {
   "element": "asset",
   "meta": {
     "classes": [
       "messageBodySchema"
     ]
   },
   "attributes": {
     "contentType": "application/schema+json"
   },
   "content": "{\n  \"$schema\": \"http://json-schema.org/draft-04/schema#\",\n  \"type\": \"object\",\n  \"properties\": {\n    \"text\": {\n      \"type\": \"string\",\n      \"description\": \"My string\"\n    }\n  }\n}"
 }
]

[jmatsushita]

Hey thanks @w-vi I understand that MSON has in fact a different expressive power than JSON Schema and it's quite useful for that, but indeed the ability to add arbitrary keys would help a lot.

FYI, my use case is that I use MSON to drive the generation of UI component using https://github.com/mozilla-services/react-jsonschema-form

[pksunkara]

The application/json schema bug is being tracked at https://github.com/apiaryio/drafter/issues/392.

[zdne]

@jmatsushita

FYI, my use case is that I use MSON to drive the generation of UI component using https://github.com/mozilla-services/react-jsonschema-form

This is very interesting. Are you saying that MSON can be represented as HTML/forms? What is all needed in order to get there?

Is #71 related to it?

[jmatsushita]

Hi @zdne

Are you saying that MSON can be represented as HTML/forms?

Indeed it can, for the subset of JSON Schema it supports. And it does have unique expressiveness particularly with inheritance which means a lot of DRY.

Our use case it to have most of the input side of our application be "schema-directed" (i.e. require minimal code changes to evolve data structures) so that we can make our schemas evolve with domain expert input.

What is all needed in order to get there?

We have protagonist/drafter wrapped in a microservice which takes MSON in and generates JSON Schema (we first used the Refract.py script but later replaced it when we understood the schema was just a deeply nested key/value of the output of drafter).

We then use a JSON Schema form generator, https://github.com/mozilla-services/react-jsonschema-form (there's a number of these, including https://github.com/ismaelga/react-json-editor and I've used alpacajs in the past).

We can then piggy back on the live validation of the form generator on the client side, and also reuse the schema for backend validation. We're using Graphql on the query side and there's been some non-DRYness there that I've been thinking about which need some (going a bit deeper than here.

We're still pondering on what to do with the MSON edition. Our current thinking is to use Gitlab (to have both Markdown rendering, collaboration and version control). We were also interested in Hercule to do transclusion. And maybe something like Prose to lower the barrier to entry for non technical users.

Is #71 related to it?

Yes! As well as couple of small other ones.

I've been thinking of extracting the part of our application that does the MSON conversion and form rendering as one of these playgrounds. Let me know if there's interest. Thanks to this very recent fix in Drafter we now have multi-choice list generation for free!

Please keep supporting JSON Schema generation! :)

[zdne]

Thanks for this detailed answer @jmatsushita, I love it!

I've been thinking of extracting the part of our application that does the MSON conversion and form rendering as one of these playgrounds.

That would be totally awesome. Even as a prototype. Also the microservice way you host and run parser is interesting!

---

So the way I understand it the additions (title, custom keys etc.) aren't the needed for form to generate but if present they would provide much better control and user experience?

---

We're still pondering on what to do with the MSON edition. Our current thinking is to use Gitlab (to have both Markdown rendering, collaboration and version control). We were also interested in Hercule to do transclusion. And maybe something like Pros

Here, if I pick this correctly, you are thinking about building a stand-alone (live?) MSON editor?

Here is my money 💰! I want it all! 😄

[jmatsushita]

Hi @zdne,

Re playground, please don't hold your breath, it will come eventually but there are some deadlines in the way. Here's a screenshot at the bottom though :)

So the way I understand it the additions (title, custom keys etc.) aren't the needed for form to generate but if present they would provide much better control and user experience?

The issue I just linked is arguably a more fundamental than UX, but generally things like allowing titles and descriptions will indeed help for UX (although you could argue that self-documenting schemas are a feature of schemas too).

Things like JSON Schema formats (as discussed here https://github.com/apiaryio/mson/issues/43) are also both a fundamental validation feature that turns out to be quite useful on the form rendering side too.

you are thinking about building a stand-alone (live?) MSON editor?

We have a basic one: