Can I use JSON schema for Data Structures?

[grncdr]

Apologies if this is a duplicate, but what I'd like to know is if there is a way to use JSON schemas in the Data Structures section instead of MSON. In particular, I'd like to be able to reference schemas by name in Request and Response sections of a Blueprint the same way I can with MSON data structures, but having the ability to specify JSON schema properties that MSON doesn't support (such as validations).

[mNantern]

+1 that would be super-useful !

[zdne]

Interesting idea! I do not think this is a duplicate. Please allow me to break this down into two parts (and let me know if that makes sense):

1. Adding a missing functionality to MSON (e.g. validation)
2. Having a way how to define and reuse assets (JSON blobs, JSON Schema blobs and others)

[grncdr]

For my use case, it's really only the second part. Defining validations in MSON is redundant if I can just use JSON schema.

The approach of swagger2/OAI is close to ideal, and quite similar to the data structures section of an API blueprint. The main differences from API blueprint data structures I see are:

• using JSON schema over MSON
• JSON pointers for schema references like {$ref: ”#/definitions/Whatever”} instead of the "ambient namespace" (my term, not sure if there's an official one) of API blueprint/MSON

As a strawman: what about a "Schemas" section where each named subsection just contains a JSON schema in a code block? They could then point at each other like #/Schemas/Subsection title. With that in place one could write simple {$ref: ”#/Schemas/Whatever”} schemas for requests and responses and have a reasonably DRY blueprint.

[zdne]

@grncdr just a quick question: would having those blobs in external file work for you (I am referring to #20 ) ?

[grncdr]

I haven't read #20 in detail yet, but from a brief skim I think it would cover my needs. I'm concerned that it might leave the process of resolving schema references a little too open so that conflicting conventions arise, but it's probably better to leave that open to experimentation initially.

[philsturgeon]

Hey! I hope you don't mind me swinging by for a bump.

I have built loads of documentation out with API Blueprint, and whilst I'm a big fan, I am starting to see a gap which we could fill.

Contract testing your API is hard. Dredd provides some basic contract testing through the context of "Do the endpoints I've documented react with a validish contract, in regards to the MSON I've buit up."

That is really valuable, but I think for a lot of people, JSON Schema is more valuable.

In my RSpec tests, I'm currently evaluating two things:

1. Exporting my MSON to JSON Schema, so I can validate response contracts in my specs via this matcher
2. Defining everything in JSON Schema first, then importing them into API Blueprint to save needing to write up MSON

I used to be pretty content writing up MSON for the API at work, but I've got into a job where a lot of folks like JSON Schema, and seeing as it has value for all sorts of other purposes, it's starting to make me approach 2 look more ideal.

Sadly, we have to rely on Hercule or build tools like Gulp/Grunt to get this done, and it all feels a little rudimentary.

If anyone is interested in chatting about this, I'll be eagerly watching my emails for a chance to help. I think API Blueprint would be awfully powerful with this addition, leaving the majority of the documentation logic as Markdown text as it is now, but leaving the validation to JSON Schema. A solid combination. :)

[zdne]

@philsturgeon I'm interested in this! But help me to understand it a bit more. Are you suggesting to convert JSON Schemas to MSON? Or are you thinking about having JSON Schema for validation and MSON for description (this is already possible)?

[philsturgeon]

I'm suggesting JSON Schema instead of MSON! About to sleep but basically wanted to throw that out there :)

…

-- Phil Sturgeon Sent from my iPhone and there's probably typos because I'm probably at the pub.

On Dec 3, 2016, at 17:53, Z ***@***.***> wrote: @philsturgeon I'm interested in this! But help me to understand it a bit more. Are you suggesting to convert JSON Schemas to MSON? Or are you thinking about having JSON Schema for validation and MSON for description (this is already possible)? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

[ragmel]

Hi, I'm interested in @philsturgeon proposal of being able to export a JSON schema from the MSON blueprint. Did this get anywhere?

[mikunn]

I'm interested in this as well. I am currently writing specs with API Blueprint with the intent of generating JSON schemas from request bodies for validation purposes. The schema generation is not an issue. The problem is that I have pretty strict rules requiring patterns (for both property names and values) and such. Yes, I could write schemas directly, but then I lose the possibility to reuse properties.

The ability to extend MSON with JSON schema would be an epic feature, although probably very hard to pull off.

Something like this (just from the top of my head)

# Data Structures

## Cat

+ name: Alfred (string, required)
  + _extend: {
    "pattern": "^[a-zA-Z]+$"
  }
+ nickname: Can have numb3rs (string, optional)
+ _extend: {
  "patternProperties": "^[a-z]+$"
}

would turn into something like

{
  "properties": {
    "name": {
      "type": "string",
      "pattern": "^[a-zA-Z]+$"
    },
    "nickname": {
      "type": "string"
    },
  },
  "required": ["name"],
  "patternProperties": "^[a-z]+$"
}

[pksunkara]

This is validation, and we did reserve some keywords in the MSON spec for this so that we can support it in the future.

[demitri]

Just wanted to add a "+1" to this. My blueprint contains very long JSON Schema that describe my responses. In one instance it's a single object, in another it's an array of that object. It would be useful to be able to specify that without copy/pasting the full JSON schema (not to mention just referring to it by name where it’s defined elsewhere).

[philsturgeon]

We had a big chat about this stuff on http://apibusters.com/002-api-blueprint a while back, and privately elsewhere.

Please remember that most folks aren't asking for MSON keywords to handle validation right now, more that they'd absolutely love JSON Schema files to be referenced in API Blueprint as an input, essentially a replacement for MSON.

# Data Structures

## Cat

+ $schema: structures/foo.json

Or whatever. JSON Schema as an input would absolve a lot of concerns for you folks, and you could work on MSON validation keywords in the background for those interested in getting that done. It's been over a year since we started talking about JSON Schema as input, and I've had to switch everything to OpenAPI to get that, even if their JSON Schema support is a little funky :D

I think we as an API community at large should focus on supporting JSON Schema as a very portable contract and validation format. Building alternatives is probably ok, but we need to be ale to support the portable one and specialist homegrown solutions.

If API Blueprint supports MSON and JSON Schema, and OpenAPI decide support their own approach + JSON Schema, and everyone goes on like that... well at least we have one format for all the tools instead of a million formats that have lossy conversions using thousands of different random old unsupported NPM packages... 😅

[philsturgeon]

Gonna go post this on #389

[geoffreywiseman]

If MSON supported more of the validation rules I want to document, I might use that over JSON Schema, but in the meantime, I'd like to be able to use JSON Schema and then re-use parts of it -- in my case in external file probably wouldn't do the trick, because want to use a data structure multiple times within a larger structure, so unless you can use an external file for /part/ of a Schema, that won't help me.

[philsturgeon]

Without meaning to be rude to anyone (everyone is working hard and life is hard) I was requesting this for about two years. These days I use JSON Schema with OpenAPI. Although it is not perfect, I have now managed to turn into a successfull workflow using a little JavaScript to iron out the differences.

https://blog.apisyouwonthate.com/openapi-and-json-schema-divergence-part-2-52e282e06a05

I would be so happy if API Blueprint could add support for referencing JSON Schema files. It could be like the OpenAPI alternate schema draft.