MSON AST Serialization Media Types
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
assets Naming & clarification Dec 16, 2014
LICENSE LICENSE origin Jul 31, 2014
README.md [README] MSON AST has been superseded by Refract Dec 2, 2015
Source Map.md

README.md

MSON AST & Source Map

This document defines serialization formats for MSON abstract syntax tree. For the definition of MSON AST Source Map see the MSON AST Source Map definition.

Deprecation Notice

As of 2015-08-10 the AST is deprecated and should not be used for new development. The MSON AST has been superseded by Data Structure Refract Namespace. The Data Structure Refract Namespace will be offered by API Blueprint parser harness – Drafter.

If you are relying on MSON AST please contact @zdne as soon as possible.

Version

  • Version: 2.0
  • Created: 2014-07-31
  • Updated: 2014-12-22

Quick Links

AST Definition

Following is the definition of MSON AST serializations data structures using the MSON syntax.

NOTE: Refer to the MSON Specification for the explanation of terms used throughout this document.

Document (object)

Top-level MSON document or block.

Properties

Named Type (object)

User-defined named type.

Properties

Type Name (enum)

Base or named type's name.

Members

  • boolean (string)
  • string (string)
  • number (string)
  • array (string)
  • enum (string)
  • object (string)
  • (Symbol)

Symbol (object)

Type symbol (identifier).

Properties

  • literal (Literal) - Name of the symbol
  • variable: false (boolean, default) - Boolean flag to denote Variable Type Name, true for variable type name, false otherwise

Type Definition (object)

Definition of an instance value type.

Properties

  • typeSpecification (object)

    • name (Type Name) - Name of the value type in an MSON instance
    • nestedTypes (array[Type Name]) - Array of nested value types, applicable only for types of an array or enum base type
  • attributes (array) - List of attributes associated with the type

    • (enum[string])
      • required
      • optional
      • default
      • sample
      • fixed

Type Section (object)

Section of a type. The section can be any of the Type Sections as described in the MSON Specification.

Properties

  • class (enum[string]) - Denotes the class of the type section

    • blockDescription - Section is a markdown block description
    • memberType - Section holds member type(s) elements
    • sample - Section defines alternate value(s) for member types
    • default - Section defines the default value(s) for member types
    • validation - Reserved for future use
  • content (enum) - Content of the section based on its class

    • (Markdown) - Markdown formatted content of the section (for class blockDescription)
    • (Literal) - Literal value for a sub-type of a primitive base type (for sample or default classes)
    • (Elements) - Section elements for a sub-type of a structured base type (for memberType, sample or default classes)

Element (object)

An element of a type section. The element holds either a member type (value or property), Mixin type, One Of type or groups elements in a collection of Elements.

Properties

  • class (enum[string]) - Class of the member object

    • property - Property member type
    • value - Value member type
    • mixin - Mixin type
    • oneOf - One Of type
    • group - Group of other elements
  • content (enum)

    • (Property Member) - Property member type (for class property)
    • (Value Member) - Value member type (for class value)
    • (Mixin) - Mixin type (for class mixin)
    • (One Of) - One Of type (for class oneOf)
    • (Elements) - Group of elements (for class group)

Elements (array[Element])

Collection of elements.

Property Member (Value Member)

Individual member of an object type structure.

Properties

Property Name (object)

Name of a property member.

Properties

  • One Of

Value Member (object)

Individual member of an array or enum type structure.

Properties

  • description (Markdown) - Inline description of the member type
  • valueDefinition (Value Definition) - The definition of the member's value
  • sections (array[Type Section]) - List of member's type sections

Mixin (Type Definition)

Mixin type.

One Of (Elements)

One Of type. List of mutually exclusive elements.

Note the only allowed Element classes are are property, mixin, oneOf and group.

Value Definition (object)

Value definition of a type instance.

Properties

  • values (array[Value]) - List of values specified in the definition
  • typeDefinition (Type Definition) - Type of the value

Value (object)

Sample or actual value of a type instance

Properties

  • literal (Literal) - The literal value
  • variable: false (boolean, default) - true to denote variable value, false otherwise

Markdown (string)

Markdown formatted plain text string.

Literal (string)

Literal value in the form of a plain-text.

Media Types

The base type media type is application/vnd.mson.ast.

Serialization formats

Two supported, feature-equal, serialization formats are JSON and YAML:

  • application/vnd.mson.ast+json
  • application/vnd.mson.ast+yaml

Example: JSON Serialization

Given the following MSON

- id: 1 (required)
- name: A green door
- price: 12.50 (number)
- tags: home, green
- vector (array)
    - 1
    - 2
    - 3

application/vnd.mson.ast+json; version=2.0

{
  "types": [
    {
      "name": null,
      "typeDefinition": {
        "typeSpecification": {
          "name": "object"
        }
      },
      "sections": [
        {
          "class": "memberType",
          "content": [
            {
              "class": "property",
              "content": {
                "name": {
                  "literal": "id"
                },
                "valueDefinition": {
                  "values": [
                    {
                      "literal": "1"
                    }
                  ],
                  "typeDefinition": {
                    "attributes": [
                      "required"
                    ]
                  }
                }
              }
            },
            {
              "class": "property",
              "content": {
                "name": {
                  "literal": "name"
                },
                "valueDefinition": {
                  "values": [
                    {
                      "literal": "A green door"
                    }
                  ]
                }
              }
            },
            {
              "class": "property",
              "content": {
                "name": {
                  "literal": "price"
                },
                "valueDefinition": {
                  "values": [
                    {
                      "literal": "12.50"
                    }
                  ],
                  "typeDefinition": {
                    "typeSpecification": {
                      "name": "number"
                    }
                  }
                }
              }
            },
            {
              "class": "property",
              "content": {
                "name": {
                  "literal": "tags"
                },
                "valueDefinition": {
                  "values": [
                    {
                      "literal": "home"
                    },
                    {
                      "literal": "green"
                    }
                  ]
                }
              }
            },
            {
              "class": "property",
              "content": {
                "name": {
                  "literal": "vector"
                },
                "valueDefinition": {
                  "typeDefinition": {
                    "typeSpecification": {
                      "name": "array"
                    }
                  }
                },
                "sections": [
                  {
                    "class": "memberType",
                    "content": [
                      {
                        "class": "value",
                        "content": {
                          "valueDefinition": {
                            "values": [
                              {
                                "literal": "1"
                              }
                            ]
                          }
                        }
                      },
                      {
                        "class": "value",
                        "content": {
                          "valueDefinition": {
                            "values": [
                              {
                                "literal": "2"
                              }
                            ]
                          }
                        }
                      },
                      {
                        "class": "value",
                        "content": {
                          "valueDefinition": {
                            "values": [
                              {
                                "literal": "3"
                              }
                            ]
                          }
                        }
                      }
                    ]
                  }
                ]
              }
            }
          ]
        }
      ]
    }
  ]
}

License

MIT License. See the LICENSE file.