{"id":21301738,"url":"https://github.com/funbox/mson","last_synced_at":"2026-02-02T08:36:59.317Z","repository":{"id":76206121,"uuid":"451953376","full_name":"funbox/mson","owner":"funbox","description":"Markdown Syntax for Object Notation","archived":false,"fork":false,"pushed_at":"2022-02-03T14:43:15.000Z","size":340,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-03-15T18:45:31.382Z","etag":null,"topics":["api-blueprint","apib"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/funbox.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-01-25T16:25:03.000Z","updated_at":"2022-05-06T10:22:31.000Z","dependencies_parsed_at":"2023-03-01T16:30:40.773Z","dependency_job_id":null,"html_url":"https://github.com/funbox/mson","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/funbox/mson","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/funbox%2Fmson","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/funbox%2Fmson/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/funbox%2Fmson/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/funbox%2Fmson/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/funbox","download_url":"https://codeload.github.com/funbox/mson/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/funbox%2Fmson/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263339935,"owners_count":23451517,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-blueprint","apib"],"created_at":"2024-11-21T15:50:38.377Z","updated_at":"2026-02-02T08:36:54.281Z","avatar_url":"https://github.com/funbox.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Markdown Syntax for Object Notation\nThis document provides an introduction to Markdown Syntax for Object Notation (MSON), a Markdown syntax\ncompatible with describing JSON and JSON Schema.\n\n## Disclaimer\n\nThis repository is a fork of the [MSON specification](https://github.com/apiaryio/mson) by Apiary.\nIt includes some changes compared to the original specification that extend existing MSON syntax.\n\n### Reasons for creating a forked version\n\nIn FunBox, we created our tools to work with API documentation. You can look at the [@funboxteam/crafter](https://github.com/funbox/crafter)\nand [@funboxteam/blueprinter-frontend](https://github.com/funbox/blueprinter-frontend) repositories to get a better understanding of what they are.\n\nThese tools are mostly based on the original specification, but some newly implemented features also require changes in the specification.\nMoreover, it seems that the current development of MSON specification and API Blueprint specification is abandoned (proved\nby the comment from the [api-blueprint-rfcs](https://github.com/apiaryio/api-blueprint-rfcs/pull/3#issuecomment-930508443) project).\n\nIn order to take the opportunity for independent developing of features we decided to make a fork and support it on our own.\n\n### Differences between the fork and the original specification\n\n* New type attributes for a string value: `format` and `pattern`. See [Type Attribute](https://github.com/funbox/mson/blob/master/MSON%20Specification.md#353-type-attribute)\n  section for more information. These attributes give you more precise control over the value validation within JSON Schema.\n* New type attributes for an array value to specify array size: `min-length` and `max-length`. See [Size Range](https://github.com/funbox/mson/blob/master/MSON%20Specification.md#3533-size-range)\n  for more information.\n* New type attributes `minimum` and `maximum` for a numeric value to validate a number against the specified range of values.\n  See [Range Of Numbers](https://github.com/funbox/mson/blob/master/MSON%20Specification.md#3534-range-of-numbers) for more information.\n* Removed definition of the `fixed-type` attribute for arrays. Thus, if an array signature contains nested types it means\n  the array must contain items of the specified types.\n* Described opportunity to define description of One Of elements.\n* A few other non-significant improvements.\n\n## What?\nMSON is a plain-text, human and machine readable, description format for describing data structures in common markup\nformats such as JSON, XML or YAML.\n\n## What for?\nThe aim of this description format is to facilitate the discussion (and thus validation) of data structures. The format,\nbeing agnostic to the common markup formats, is well suited for \"resource \u0026 representations\" and \"content negotiation\"\nscenarios.\n\nIn addition, this format also offers (limited) serialization functionality.\n\nSimilar to the original Markdown to HTML (markup) conversion, MSON enables conversion to other markup formats.\n\n## Who \u0026 Why?\nThis format is being developed by [Apiary][] as a part of the [API Blueprint][] syntax to provide a means\nfor description and validation of HTTP payloads and DRY, media-type agnostic, resource descriptions and to simplify\ncontent-negotiation.\n\n\u003e **NOTE**: While this document focuses primarily on JSON and JSON Schema examples, the underlying specification will\n\u003e ultimately allow producing XML or YAML representations from MSON.\n\n## Notational Conventions\nThe key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and\n\"OPTIONAL\" in this document are to be interpreted as described in [RFC2119][].\n\n## Example 1\nA simple `object` structure and its associated JSON expression.\n\n#### MSON\n\n```\n- id: 1\n- name: A green door\n- price: 12.50\n- tags: home, green\n```\n\n#### Rendered Markdown\n\n- id: 1\n- name: A green door\n- price: 12.50\n- tags: home, green\n\n#### JSON\n\n```json\n{\n    \"id\": \"1\",\n    \"name\": \"A green door\",\n    \"price\": \"12.50\",\n    \"tags\": [ \"home\", \"green\" ]\n}\n```\n\n\u003e**NOTE:** By default, a Markdown list item is considered to be a `string` type.\n\n---\n\n## Example 2\nA Named Type with its associated JSON expression and JSON Schema.\n\n#### MSON\n\n```\n# Product\nA product from Acme's catalog\n\n## Properties\n\n- id: 1 (number, required) - The unique identifier for a product\n- name: A green door (string, required) - Name of the product\n- price: 12.50 (number, required)\n- tags: home, green (array[string])\n```\n\n#### Rendered Markdown\n\n##### Product\nA product from Acme's catalog\n\n###### Properties\n\n- id: 1 (number, required) - The unique identifier for a product\n- name: A green door (string, required) - Name of the product\n- price: 12.50 (number, required)\n- tags: home, green (array[string], fixed-type)\n\n#### JSON\n\n```json\n{\n    \"id\": 1,\n    \"name\": \"A green door\",\n    \"price\": 12.50,\n    \"tags\": [ \"home\", \"green\" ]\n}\n```\n\n\u003e**NOTE:** The `id` and `price` sample values are numbers given the explicit declaration of their base type of `number`\n\u003e vs. the default of `string` as in [Example 1](#example-1).\n\n#### JSON Schema\n\n```json\n{\n    \"$schema\": \"http://json-schema.org/draft-04/schema#\",\n    \"title\": \"Product\",\n    \"description\": \"A product from Acme's catalog\",\n    \"type\": \"object\",\n    \"properties\": {\n        \"id\": {\n            \"description\": \"The unique identifier for a product\",\n            \"type\": \"number\"\n        },\n        \"name\": {\n            \"description\": \"Name of the product\",\n            \"type\": \"string\"\n        },\n        \"price\": {\n            \"type\": \"number\"\n        },\n        \"tags\": {\n            \"type\": \"array\",\n            \"items\": {\n                \"type\": \"string\"\n            }\n        }\n    },\n    \"required\": [\"id\", \"name\", \"price\"]\n}\n```\n\n\u003e **NOTE:** This proposal covers only basic features of JSON Schema. At this moment, it is out of the scope of this\n\u003e syntax to support all the JSON Schema keywords (such as `uniqueItems`, `exclusiveMinimum`, etc.).\n\n---\n\n## MSON Language Specification\nThe rest of this document covers some advanced syntax examples. Refer to the [MSON Language Specification][] for the\ncomplete MSON Grammar Reference.\n\n## Quick Links\n\n- [MSON Language Specification][]\n- [Objects \u0026 Arrays](#objects--arrays)\n- [Advanced Objects](#advanced-objects)\n- [Advanced Arrays](#advanced-arrays)\n- [Escaping](#escaping)\n- [Multi-line Descriptions](#multi-line-descriptions)\n- [Variable Property Name](#variable-property-name)\n- [Type Definition](#type-definition)\n- [Referencing](#referencing)\n- [Mixins](#mixins)\n\n## Objects \u0026 Arrays\nBy default, a Markdown list item with a nested Markdown list is considered to be an `object` structure:\n\n#### MSON\n```\n- address\n    - street\n    - city\n    - state\n```\n\n#### JSON\n```json\n{\n    \"address\" : {\n        \"street\": \"\",\n        \"city\": \"\",\n        \"state\": \"\"\n    }\n}\n```\n\nIf a Markdown list's items are intended to be literals (represent array values), the type of the parent list item MUST\nbe explicitly set to `array`:\n\n#### MSON\n```\n- address (array)\n    - street\n    - city\n    - state\n```\n\nOr, alternately:\n\n```\n- address: street, city, state (array)\n```\n\nIn this latter case, using a comma-separated list of values, the type `(array)` is implied and thus MAY be omitted.\n\n#### JSON\n```json\n{\n    \"address\": [ \"street\", \"city\", \"state\" ]\n}\n```\n\n\u003e **NOTE:** The values \"street\", \"city\", and \"state\" are solely sample values of the `address` array in this example.\n\u003e No constraints are implied on the quantity or types of values in such an array other than that they MAY be `string`\n\u003e literals.\n\n## Advanced Objects\n\n### Non-uniform Property\nA Property whose value can be of different types is defined by the `enum` structure type:\n\n#### MSON\n\n```\n- tag (enum)\n    - green (string)\n    - (object)\n        - tag_id: 1\n        - label: green\n```\n\n#### Rendered Markdown\n\n- tag (enum)\n    - green (string)\n    - (object)\n        - tag_id: 1\n        - label: green\n\n#### JSON\n\n```json\n{\n    \"tag\": \"green\"\n}\n```\n\n**or**\n\n```json\n{\n    \"tag\": {\n        \"tag_id\": \"1\",\n        \"label\": \"green\"\n    }\n}\n```\n\n\u003e**NOTE:** In an `enum` structure, in contrast to an `array` type structure, a value like \"green\" is a fully-qualified\n\u003evalue of the enumeration vs. being a sample value.\n\n---\n\n### Mutually Exclusive Properties\nBy default, all properties are optional and may or may not be included in the object. If there is a choice of\nmutually exclusive properties available MSON defines a `One Of` type:\n\n#### MSON\n```\n- city\n- One Of\n    - state\n    - province\n- country\n```\n\n#### Rendered Markdown\n\n- city\n- One Of\n    - province\n    - state\n- country\n\n#### JSON\n```json\n{\n    \"street\": \"\",\n    \"province\": \"\",\n    \"country\": \"\"\n}\n```\n\n**or**\n\n```json\n{\n    \"street\": \"\",\n    \"state\": \"\",\n    \"country\": \"\"\n}\n```\n\n\u003e**NOTE:** Because an `enum` type MUST define a list of types vs. properties and by default an un-nested Markdown list\ndefines properties of an implied `object` structure, the `One Of` type declaration MUST only be used to indicate\nmutually exclusive properties in an `object` structure.\n\n---\n\n## Advanced Arrays\n\n### Array of Mixed Types\n\n#### MSON\n\n```\n- tags (array)\n    - hello (string)\n    - 42 (number)\n```\n\n#### Rendered Markdown\n\n- tags (array)\n    - hello (string)\n    - 42 (number)\n\n#### JSON\n\n```json\n{\n    \"tags\": [ \"hello\", 42 ]\n}\n```\n\n---\n\n#### MSON\n\n```\n- (array)\n    - (object)\n        - name: snow (string)\n        - description (string)\n    - 42 (number)\n```\n\n#### Rendered Markdown\n\n- (array)\n    - (object)\n        - name: snow (string)\n        - description (string)\n    - 42 (number)\n\n#### JSON\n\n```json\n[\n    {\n        \"name\": \"snow\",\n        \"description\": \"\"\n    },\n    42\n]\n```\n\n---\n\n### Array of Arrays\n\n#### MSON\n\n```\n- (array)\n    - 1, 2, 3, 4 (array[number])\n```\n\n#### Rendered Markdown\n\n- (array)\n    - 1, 2, 3, 4 (array[number])\n\n#### JSON\n\n```json\n[\n    [ 1, 2, 3, 4 ]\n]\n```\n\n---\n\n## Multi-line Descriptions\nIn the case where a one-liner description is not sufficient, a multi-paragraph text block is the way to go.\n\n#### MSON\n\n```\n- id: 1 (number, required) - The unique identifier for a product\n- name: A green door (string, required)\n\n    Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n\n    Sed sed lacus a arcu vehicula ultricies sed vel nibh. Mauris id cursus felis.\n\n    Interdum et malesuada fames ac ante ipsum primis in faucibus.\n\n    - unus\n    - duo\n    - tres\n    - quattuor\n\n- price: 12.50 (number, required)\n- tags: home, green (array)\n```\n\nFor a multi-line description of a structure type, an `Items`, `Members` , or `Properties` keyword MUST be used to avoid\nconflict with potential list item values that are part of the description:\n\n```\n- tags (array)\n\n    Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n\n    Sed sed lacus a arcu vehicula ultricies sed vel nibh. Mauris id cursus felis.\n\n    Interdum et malesuada fames ac ante ipsum primis in faucibus.\n\n    - unus\n    - duo\n    - tres\n    - quattuor\n\n    - Items\n        - home\n        - green\n```\n\n\u003e**NOTE:** Unus ... quattuor are considered part of the text block vs. defining items of the array.\n\n## Escaping\nMarkdown [code span][] element syntax (`` ` ` ``) is used to escape reserved Keywords that should just be interpretted\nas literals as well as other constructs that may be erroneously interpreted by an MSON parser as meaningful.\n\nFor non-Keywords, a [code span][] can be used for formatting Markdown as an aesthetic preference.\n\n#### MSON\n\n```\n- listing (object)\n\n    Our real estate listing has different properties available.\n\n    - `Properties`\n        - This one.\n        - That one.\n\n    - Properties\n        - description (string)\n        - date_listed (string)\n        - `some:location`: local (string)\n```\n\n#### Rendered Markdown\n\n- listing (object)\n\n    Our real estate listing has different properties available.\n\n    - `Properties`\n        - This one.\n        - That one.\n\n    - Properties\n        - description\n        - date_listed\n        - `some:location`: local (string)\n\n\u003e**NOTE:** In this example, the first \"Properties\" string is part of the multi-line block description whereas the second\n\u003e defines the properties of the `listing` object.\n\n---\n\n## Variable Property Name\nVariable property name (key) is defined using *italics*. Note that a variable property cannot be required.\n\n#### MSON\n\n```\n- _links\n    - *self*\n        - href: a URI\n```\n\n#### Rendered Markdown\n\n- _links\n    - *self*\n        - href: a URI\n\n#### JSON\n\n```json\n{\n    \"_links\": {\n        \"self\": {\n            \"href\": \"...\"\n        },\n        \"users\": {\n            \"href\": \"...\"\n        }\n    }\n}\n```\n\n---\n\n## Type Definition\nAdditional Named Types can be defined using a Markdown header:\n\n#### MSON\n\n```\n# Address (object)\nDescription is here! Properties to follow.\n\n## Properties\n- street\n- state\n- zip\n```\n\nThe same entity defined as an `address` property:\n\n```\n- address (object)\n\n    Description is here! Properties to follow.\n\n    - Properties\n        - street\n        - state\n        - zip\n```\n\nThe same `address` property referencing the previously Named type:\n\n```\n- address (Address)\n```\n\n## Referencing\nAnywhere a type is expected, a top-level MSON Named Type can be referenced.\n\n#### MSON\n\n```\n# Address (object)\n- street\n- city\n- state\n- zip\n\n# User (object)\n- first_name\n- last_name\n- address (Address)\n```\n\n#### Rendered Markdown\n\n##### Address (object)\n- street\n- city\n- state\n- zip\n\n##### User (object)\n- first_name\n- last_name\n- address (Address)\n\n#### JSON\n\n```json\n{\n    \"first_name\": \"\",\n    \"last_name\": \"\",\n    \"address\": {\n        \"street\": \"\",\n        \"city\": \"\",\n        \"state\": \"\",\n        \"zip\": \"\"\n    }\n}\n```\n\n---\n\n## Mixins\nTo include (mixin) values or properties in another Named Type use the `Include` keyword followed by a reference to the  \nMSON Named Type.\n\n#### MSON\n\n```\n# Address Object\n- street\n- city\n- state\n- zip\n\n# User Object\n- first_name\n- last_name\n- Include Address\n```\n\n#### Rendered Markdown\n\n##### Address Object\n- street\n- city\n- state\n- zip\n\n##### User Object\n- first_name\n- last_name\n- Include Address\n\n#### JSON\n\n```json\n{\n    \"first_name\": \"\",\n    \"last_name\": \"\",\n    \"street\": \"\",\n    \"city\": \"\",\n    \"state\": \"\",\n    \"zip\": \"\"\n}\n```\n\n\u003e**NOTE:** A mixin can only use a Named Type that is derived from the same type of structure including the mixin.\n\u003e Further, the parent structure inherits all the members of the included Named Type and maintains the order the\n\u003e members were originally defined.\n\n[API Blueprint]: https://github.com/apiaryio/api-blueprint\n[code span]: http://daringfireball.net/projects/markdown/syntax#code\n[@zdne]: https://github.com/zdne\n[Apiary]: http://apiary.io\n[RFC2119]: https://www.ietf.org/rfc/rfc2119\n[MSON Language Specification]: MSON%20Specification.md\n\n[![Sponsored by FunBox](https://funbox.ru/badges/sponsored_by_funbox_centered.svg)](https://funbox.ru)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffunbox%2Fmson","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffunbox%2Fmson","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffunbox%2Fmson/lists"}