How am I supposed to consume the MailChimp JSON Schema for its API?

Question

On the developer portion of its site, MailChimp links to a JSON schema describing its API.

http://developer.mailchimp.com/documentation/mailchimp/guides/get-started-with-mailchimp-api-3/#json-schema

I am familiar with JSON schemas (Draft v4). I understand their role in API payload validation, documentation generation, etc. I am also familiar with how they contrast with Swagger (OpenAPI) schemas (which are similar in some ways but more comprehensively document an API).

It seems MailChimp's schema is a Swagger-like API description, but based on a JSON schema syntax. At first, it looks like a JSON Hyper-Schema, but it has 'schema' and 'targetSchema' fields referencing other JSON files without using JSON Pointers (https://spacetelescope.github.io/understanding-json-schema/structuring.html). It also mixes in some HATEOAS concepts?

What tooling will allow me to consume this JSON schema without manually reconciling all the JSON schema files published by MailChimp?

My goal is ultimately to create a Swagger 2.0 (OpenAPI) definition of MailChimp's API. I have a tool for converting from JSON Hyper-Schemas to Swagger 2.0.

Answer 1

I took TooMuchPete's suggestion.

Here's what MailChimp said:

Hi Jordan,

Thanks for reaching out. At the current time, we use a mix of both of these specifications. We currently use Swagger to lay out our schema for documentation purposes, however, we use the JSON schemas for other functions such as request validation and other parts of the API. That said, we are currently in the process of transitioning these functions over to Swagger. With that said, below is a URL that should be helpful in consuming our schemas.

http://api.mailchimp.com/schema/3.0/Swagger.json

Answer 2

My understanding is that MailChimp is transitioning from JSON Hyperschema to Swagger, as that's how they generate their documentation. You might want to contact their API helpdesk and see if the swagger is available publicly yet.