Missing description property in generated JSON Schema

[Gasol]

Hi,

I am working on consume API Element Parse Result instead of AST Parse Result by updating drafter from 3.2.7 to 4.0.0, and notice that have a little bit different JSON schema between two Parse Result, after digging into source, I found it is breaking changes since 4.0.0-pre.1, says from changelog

Descriptions for MSON structures are no longer found in generated JSON Schemas.

I don't know why because of poor commit message, To me, It's a good practice to generate description for specific field from MSON attributes, and it also makes JSON schema self-documenting 1.

If you have good reason to drop description in JSON schema, maybe add some option for description appearance.

$ bin/drafter -v
v4.0.0-pre.4
$ bin/drafter test/fixtures/schema/description.apib -f json | jq -r '.content[0].content|..|select(.meta?.classes.content[0].content == "messageBodySchema")|.content'

OK.
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number"
    },
    "name": {
      "type": "string"
    },
    "price": {
      "type": "number"
    },
    "tags": {
      "type": "array"
    }
  },
  "required": [
    "id",
    "name",
    "price"
  ]
}

$ drafter -v
v3.2.7
$ drafter test/fixtures/schema/description.apib -f json | jq -r '.content[0].content|..|select(.meta?.classes[0] == "messageBodySchema")|.content'

OK.
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The unique identifier for a product"
    },
    "name": {
      "type": "string",
      "description": "Name of the product"
    },
    "price": {
      "type": "number"
    },
    "tags": {
      "type": "array",
      "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n\nSed sed lacus a arcu vehicula ultricies sed vel nibh. Mauris id cursus felis.\n\nInterdum et malesuada fames ac ante ipsum primis in faucibus.\n\n- unus\n\n- duo\n\n- tres\n\n- quattuor"
    }
  },
  "required": [
    "id",
    "name",
    "price"
  ]
}

[kylef]

We've been asked this before on our API Blueprint slack so I'll share the answer @tjanc gave before:

Currently, JSON Schema generated from API Blueprint doesn't attempt anything more than to validate against the same class of values the original API Blueprint would. The missing default can be seen as a regression if your use case depends on more than just validation (the "annotation" part of JSON Schema). That is because default in JSON Schema doesn't have meaning with respect to validation.

In general, we are not trying to find a bijection between JSON Schema and API Blueprint (+MSON). However, I'm really interested in your use case now, and I'm open to reintroduce default rendering at request.

[kylef]

I'm going to close this as we didn't hear back from you. If you could explain more about you're use case we would still love to hear it though.

[Djo-djo]

Hi. I'm faced with the same problem while using bukalapak/snowboard. I would like to show description field in JSON Schema for users. Have you any workaround to parse description field?