This document provides an introduction to Markdown Syntax for Object Notation (MSON), a Markdown syntax compatible with describing JSON and JSON Schema.
This repository is a fork of the MSON specification by Apiary. It includes some changes compared to the original specification that extend existing MSON syntax.
In FunBox, we created our tools to work with API documentation. You can look at the @funboxteam/crafter and @funboxteam/blueprinter-frontend repositories to get a better understanding of what they are.
These tools are mostly based on the original specification, but some newly implemented features also require changes in the specification. Moreover, it seems that the current development of MSON specification and API Blueprint specification is abandoned (proved by the comment from the api-blueprint-rfcs project).
In order to take the opportunity for independent developing of features we decided to make a fork and support it on our own.
- New type attributes for a string value:
formatandpattern. See Type Attribute section for more information. These attributes give you more precise control over the value validation within JSON Schema. - New type attributes for an array value to specify array size:
min-lengthandmax-length. See Size Range for more information. - New type attributes
minimumandmaximumfor a numeric value to validate a number against the specified range of values. See Range Of Numbers for more information. - Removed definition of the
fixed-typeattribute for arrays. Thus, if an array signature contains nested types it means the array must contain items of the specified types. - Described opportunity to define description of One Of elements.
- A few other non-significant improvements.
MSON is a plain-text, human and machine readable, description format for describing data structures in common markup formats such as JSON, XML or YAML.
The aim of this description format is to facilitate the discussion (and thus validation) of data structures. The format, being agnostic to the common markup formats, is well suited for "resource & representations" and "content negotiation" scenarios.
In addition, this format also offers (limited) serialization functionality.
Similar to the original Markdown to HTML (markup) conversion, MSON enables conversion to other markup formats.
This format is being developed by Apiary as a part of the API Blueprint syntax to provide a means for description and validation of HTTP payloads and DRY, media-type agnostic, resource descriptions and to simplify content-negotiation.
NOTE: While this document focuses primarily on JSON and JSON Schema examples, the underlying specification will ultimately allow producing XML or YAML representations from MSON.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119.
A simple object structure and its associated JSON expression.
- id: 1
- name: A green door
- price: 12.50
- tags: home, green
- id: 1
- name: A green door
- price: 12.50
- tags: home, green
{
"id": "1",
"name": "A green door",
"price": "12.50",
"tags": [ "home", "green" ]
}NOTE: By default, a Markdown list item is considered to be a
stringtype.
A Named Type with its associated JSON expression and JSON Schema.
# Product
A product from Acme's catalog
## Properties
- id: 1 (number, required) - The unique identifier for a product
- name: A green door (string, required) - Name of the product
- price: 12.50 (number, required)
- tags: home, green (array[string])
A product from Acme's catalog
- id: 1 (number, required) - The unique identifier for a product
- name: A green door (string, required) - Name of the product
- price: 12.50 (number, required)
- tags: home, green (array[string], fixed-type)
{
"id": 1,
"name": "A green door",
"price": 12.50,
"tags": [ "home", "green" ]
}NOTE: The
idandpricesample values are numbers given the explicit declaration of their base type ofnumbervs. the default ofstringas in Example 1.
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Product",
"description": "A product from Acme's catalog",
"type": "object",
"properties": {
"id": {
"description": "The unique identifier for a product",
"type": "number"
},
"name": {
"description": "Name of the product",
"type": "string"
},
"price": {
"type": "number"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": ["id", "name", "price"]
}NOTE: This proposal covers only basic features of JSON Schema. At this moment, it is out of the scope of this syntax to support all the JSON Schema keywords (such as
uniqueItems,exclusiveMinimum, etc.).
The rest of this document covers some advanced syntax examples. Refer to the MSON Language Specification for the complete MSON Grammar Reference.
- MSON Language Specification
- Objects & Arrays
- Advanced Objects
- Advanced Arrays
- Escaping
- Multi-line Descriptions
- Variable Property Name
- Type Definition
- Referencing
- Mixins
By default, a Markdown list item with a nested Markdown list is considered to be an object structure:
- address
- street
- city
- state
{
"address" : {
"street": "",
"city": "",
"state": ""
}
}If a Markdown list's items are intended to be literals (represent array values), the type of the parent list item MUST
be explicitly set to array:
- address (array)
- street
- city
- state
Or, alternately:
- address: street, city, state (array)
In this latter case, using a comma-separated list of values, the type (array) is implied and thus MAY be omitted.
{
"address": [ "street", "city", "state" ]
}NOTE: The values "street", "city", and "state" are solely sample values of the
addressarray in this example. No constraints are implied on the quantity or types of values in such an array other than that they MAY bestringliterals.
A Property whose value can be of different types is defined by the enum structure type:
- tag (enum)
- green (string)
- (object)
- tag_id: 1
- label: green
- tag (enum)
- green (string)
- (object)
- tag_id: 1
- label: green
{
"tag": "green"
}or
{
"tag": {
"tag_id": "1",
"label": "green"
}
}NOTE: In an
enumstructure, in contrast to anarraytype structure, a value like "green" is a fully-qualified value of the enumeration vs. being a sample value.
By default, all properties are optional and may or may not be included in the object. If there is a choice of
mutually exclusive properties available MSON defines a One Of type:
- city
- One Of
- state
- province
- country
- city
- One Of
- province
- state
- country
{
"street": "",
"province": "",
"country": ""
}or
{
"street": "",
"state": "",
"country": ""
}NOTE: Because an
enumtype MUST define a list of types vs. properties and by default an un-nested Markdown list defines properties of an impliedobjectstructure, theOne Oftype declaration MUST only be used to indicate mutually exclusive properties in anobjectstructure.
- tags (array)
- hello (string)
- 42 (number)
- tags (array)
- hello (string)
- 42 (number)
{
"tags": [ "hello", 42 ]
}- (array)
- (object)
- name: snow (string)
- description (string)
- 42 (number)
- (array)
- (object)
- name: snow (string)
- description (string)
- 42 (number)
- (object)
[
{
"name": "snow",
"description": ""
},
42
]- (array)
- 1, 2, 3, 4 (array[number])
- (array)
- 1, 2, 3, 4 (array[number])
[
[ 1, 2, 3, 4 ]
]In the case where a one-liner description is not sufficient, a multi-paragraph text block is the way to go.
- id: 1 (number, required) - The unique identifier for a product
- name: A green door (string, required)
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Sed sed lacus a arcu vehicula ultricies sed vel nibh. Mauris id cursus felis.
Interdum et malesuada fames ac ante ipsum primis in faucibus.
- unus
- duo
- tres
- quattuor
- price: 12.50 (number, required)
- tags: home, green (array)
For a multi-line description of a structure type, an Items, Members , or Properties keyword MUST be used to avoid
conflict with potential list item values that are part of the description:
- tags (array)
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Sed sed lacus a arcu vehicula ultricies sed vel nibh. Mauris id cursus felis.
Interdum et malesuada fames ac ante ipsum primis in faucibus.
- unus
- duo
- tres
- quattuor
- Items
- home
- green
NOTE: Unus ... quattuor are considered part of the text block vs. defining items of the array.
Markdown code span element syntax (` `) is used to escape reserved Keywords that should just be interpretted
as literals as well as other constructs that may be erroneously interpreted by an MSON parser as meaningful.
For non-Keywords, a code span can be used for formatting Markdown as an aesthetic preference.
- listing (object)
Our real estate listing has different properties available.
- `Properties`
- This one.
- That one.
- Properties
- description (string)
- date_listed (string)
- `some:location`: local (string)
-
listing (object)
Our real estate listing has different properties available.
-
Properties- This one.
- That one.
-
Properties
- description
- date_listed
some:location: local (string)
-
NOTE: In this example, the first "Properties" string is part of the multi-line block description whereas the second defines the properties of the
listingobject.
Variable property name (key) is defined using italics. Note that a variable property cannot be required.
- _links
- *self*
- href: a URI
- _links
- self
- href: a URI
- self
{
"_links": {
"self": {
"href": "..."
},
"users": {
"href": "..."
}
}
}Additional Named Types can be defined using a Markdown header:
# Address (object)
Description is here! Properties to follow.
## Properties
- street
- state
- zip
The same entity defined as an address property:
- address (object)
Description is here! Properties to follow.
- Properties
- street
- state
- zip
The same address property referencing the previously Named type:
- address (Address)
Anywhere a type is expected, a top-level MSON Named Type can be referenced.
# Address (object)
- street
- city
- state
- zip
# User (object)
- first_name
- last_name
- address (Address)
- street
- city
- state
- zip
- first_name
- last_name
- address (Address)
{
"first_name": "",
"last_name": "",
"address": {
"street": "",
"city": "",
"state": "",
"zip": ""
}
}To include (mixin) values or properties in another Named Type use the Include keyword followed by a reference to the
MSON Named Type.
# Address Object
- street
- city
- state
- zip
# User Object
- first_name
- last_name
- Include Address
- street
- city
- state
- zip
- first_name
- last_name
- Include Address
{
"first_name": "",
"last_name": "",
"street": "",
"city": "",
"state": "",
"zip": ""
}NOTE: A mixin can only use a Named Type that is derived from the same type of structure including the mixin. Further, the parent structure inherits all the members of the included Named Type and maintains the order the members were originally defined.
