{"id":28376681,"url":"https://github.com/apiaryio/api-blueprint-ast","last_synced_at":"2025-08-16T10:44:43.924Z","repository":{"id":13380743,"uuid":"16068699","full_name":"apiaryio/api-blueprint-ast","owner":"apiaryio","description":"API Blueprint AST Serialization Media Types [adhd, apib]","archived":true,"fork":false,"pushed_at":"2017-03-31T10:12:41.000Z","size":95,"stargazers_count":32,"open_issues_count":0,"forks_count":3,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-06-26T14:50:55.580Z","etag":null,"topics":["deprecated"],"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/apiaryio.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}},"created_at":"2014-01-20T11:20:17.000Z","updated_at":"2024-11-08T09:03:56.000Z","dependencies_parsed_at":"2022-08-22T23:50:25.225Z","dependency_job_id":null,"html_url":"https://github.com/apiaryio/api-blueprint-ast","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/apiaryio/api-blueprint-ast","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apiaryio%2Fapi-blueprint-ast","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apiaryio%2Fapi-blueprint-ast/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apiaryio%2Fapi-blueprint-ast/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apiaryio%2Fapi-blueprint-ast/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/apiaryio","download_url":"https://codeload.github.com/apiaryio/api-blueprint-ast/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apiaryio%2Fapi-blueprint-ast/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270702471,"owners_count":24630873,"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","status":"online","status_checked_at":"2025-08-16T02:00:11.002Z","response_time":91,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["deprecated"],"created_at":"2025-05-30T00:07:33.788Z","updated_at":"2025-08-16T10:44:43.872Z","avatar_url":"https://github.com/apiaryio.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"![logo](https://raw.github.com/apiaryio/api-blueprint/master/assets/logo_apiblueprint.png)\n\n# API Blueprint AST\n\n## Deprecation Notice\n\nAs of 2015-12-02 the API Blueprint AST is deprecated and should not be used for new development. The API Blueprint AST has been superseded by [API Elements](https://github.com/apiaryio/api-elements).\n\n### JSON \u0026 YAML face of the API Blueprint\nAPI Blueprint AST is JSON or YAML, machine-friendly, face of API Blueprint suitable for use in [tools](http://apiblueprint.org/#tooling) consuming (or producing) API Blueprint.\n\nThis document defines serialization formats for [API Blueprint](http://apiblueprint.org) abstract syntax tree, or AST for short.\n\nFor the definition of API Blueprint AST Source Map see the [API Blueprint AST Source Map definition][Source Map Definition].\n\nConverting API Blueprint to AST and its serialization is the task of API Blueprint Parser – [Drafter](https://github.com/apiaryio/drafter) or one of its [bindings](https://github.com/apiaryio/drafter#bindings). Reverse process from AST (serialization) to API Blueprint is also possible thanks to the [Matter Compiler](https://github.com/apiaryio/matter_compiler).\n\n## Don't like to design APIs in JSON or YAML?\nIf you are looking for a way to describe your Web API without using JSON or YAML see [API Blueprint](https://github.com/apiaryio/api-blueprint).\n\n## Version\n+ **Version**: 4.0\n+ **Created**: 2013-08-30\n+ **Updated**: 2015-09-07\n\n## Future Development\nAs of version 3.0 the API Blueprint AST is in the *interim* transition period\ntowards unified document-structure based on the concept of DOM elements\n(see the [Element][] object). Please refrain from using AST elements marked as\n*\"deprecated\"*.\n\n## Quick Links\n+ [AST Description](#ast-definition)\n+ [Media Types](#media-types)\n+ [Keys description](#keys-description)\n+ [Example: JSON serialization](#example-json-serialization)\n+ [Serialization in Drafter](#serialization-in-drafter)\n+ [Serialized Parsing Result Media Types][parsing media types]\n\n## AST Definition\nFollowing is the definition of API Blueprint AST media types using the [MSON](https://github.com/apiaryio/mson) syntax.\n\n\u003e **NOTE:** Most of the keys corresponds to their counter parts in API Blueprint Specification. Where applicable, refer to the relevant entry [API Blueprint Language Specification](https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md) for details.\n\n### Blueprint (object)\n+ `_version` (string) - Version of the AST Serialization as [defined](#version) in this document\n+ `metadata` (array) - Ordered array of API Blueprint [metadata](https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#MetadataSection)\n    - (object)\n        - `name` (string) - Name of the metadata\n        - `value` (string) - Value of the metadata\n\n+ `name` (string) - Name of the API\n+ `description` (string) - Top-level description of the API in Markdown (`.raw`) or HTML (`.html`)\n+ `resourceGroups` (array[[Resource Group][]]) - **Deprecated**\n\n    Note this property is **deprecated** and will be removed in a future.\n    Replaced by `category` elements of the `content` property.\n\n+ `element`: `category` (fixed, required)\n+ `content` (array[[Element][]]) - Section elements of the blueprint\n\n### Element (object)\nA component of an API description.\n\n#### Properties\n+ `element` (enum[string]) - Element name\n    + `category` - Element is a group of other elements\n    + `copy` - Element is a human readable text\n    + `resource` - Element is a Resource\n    + `dataStructure` - Element is a Data Structure definition\n    + `asset` - Element is an asset of API description\n+ `attributes` (object) - Element-specific attributes\n    + `name` (string, optional) - Human readable name of the element\n+ `content` (enum)\n    + (array[[Element][]]) - Ordered array of nested elements (for element `category`)\n    + (string) - Markdown-formatted text (for element `copy` and `asset` type)\n    + ([Resource][]) - Resource definiton (for element `resource`)\n    + ([Data Structure][]) - Data structure (for element `dataStructure`)\n\n### Resource Group (object)\n**Deprecated**, replaced by the `category` [Element][].\n\nLogical group of resources.\n\n#### Properties\n+ `name` (string) - Name of the Resource Group\n+ `description` (string) - Description of the Resource Group (`.raw` or `.html`)\n+ `resources` (array[[Resource][]]) - Ordered array of the respective resources belonging to the Resource Group\n\n### Resource (object)\nDescription of one resource, or a cluster of resources defined by its URI template.\n\n#### Properties\n+ `name` (string) - Name of the Resource\n+ `description` (string) - Description of the Resource (`.raw` or `.html`)\n+ `element`: `resource` (fixed, required)\n+ `uriTemplate` (string) - URI Template as defined in [RFC6570](http://tools.ietf.org/html/rfc6570)\n+ `model` ([Payload][]) - [Resource Model](https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#ResourceModelSection), a reusable payload representing the resource\n+ `parameters` (array[[Parameter][]]) - Ordered array of URI parameters\n+ `actions` (array[[Action][]]) - Ordered array of actions available on the resource each defining at least one complete HTTP transaction\n+ `content` (array[[Data Structure][]]) - Array of Resource's elements\n\n    In the interim period this may contain at maximum one\n    element of the `dataStructure` type - the definition of the of the Resource\n    attributes.\n\n### Action (object)\nAn HTTP transaction (a request-response transaction). Actions are specified by an HTTP request method within a resource.\n\n#### Properties\n+ `name` (string) - Name of the Action\n+ `description` (string) - Description of the Action (`.raw` or `.html`)\n+ `method` (string) - HTTP request method defining the action\n+ `parameters` (array[[Parameter][]]) - Ordered array of resource's URI parameters descriptions specific to this action\n+ `examples` (array[[Transaction Example][]]) - Ordered array of HTTP transaction [examples](#example-section) for the relevant HTTP request method\n+ `attributes` (object) - Action-specific attributes\n    + `uriTemplate` (string) - URI Template as defined in [RFC6570](http://tools.ietf.org/html/rfc6570)\n    + `relation` (string) - Link relation identifier of the action as defined in [Relation section][]\n+ `content` (array[[Data Structure][]])  - Array of Action's elements\n\n    In the interim period this may contain at maximum one\n    element of the `dataStructure` type - the definition of the of the action input\n    attributes.\n\n### Payload (object)\nAn [API Blueprint payload](https://github.com/apiaryio/api-blueprint/blob/master/Glossary%20of%20Terms.md#payload).\n\n#### Properties\n+ `name` (string) - Name of the payload\n\n    The content of this key depends on the type of payload:\n\n    + **model** payload: name of the resource, if any\n    + **request** payload: name of the request, if any\n    + **response** payload: HTTP status code\n\n+ `reference` ([Reference][]) - Present if and only if a reference to a [Resource Model](https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#ResourceModelSection) is present in the payload and it has been resolved correctly\n+ `description` (string) - Description of the payload (`.raw` or `.html`)\n+ `headers` (array[[Header][]]) - Ordered array of HTTP headers that are expected to be transferred with HTTP message represented by this payload\n+ `body` (string) - **Deprecated**\n\n    An entity body to be transferred with HTTP message represented by this payload\n\n    Note this property is **deprecated** and will be removed in a future.\n    Replaced by `bodyExample` [Asset][] element.\n\n+ `schema` (string) - **Deprecated**\n\n    A validation schema for the entity body as defined in `body`.\n\n    Note this property is **deprecated** and will be removed in a future.\n    Replaced by `bodySchema` `asset` element.\n\n+ `content` (array) - Array of Payloads's elements\n\n    In the interim period this may contain only:\n    + At maximum one element of the `dataStructure` type - the definition of the message-body\n    attributes\n    + Up to two asset elements one for body example other for body schema\n\n    + Items\n        + ([Data Structure][])\n        + ([Asset][])\n\n### Header\nA HTTP header that are expected to be transferred with an HTTP message.\n\n#### Properties\n+ `name` (string, required) - The name of the header\n+ `value` (string, required) - The value of the header\n\n### Asset (Element)\nAn [API Blueprint asset][]. The content is an Asset in its textual\nrepresentation as written in the source API Blueprint.\n\n#### Properties\n+ `element`: `asset` (fixed, required)\n+ `attributes`\n    + `role` - Role of the asset\n        + `bodyExample` - Asset is an example of message-body\n        + `bodySchema` - Asset is an schema for message-body\n\n### Parameter (object)\nDescription of one URI template parameter.\n\n#### Properties\n- `name` (string) - Name of the parameter\n- `description` (string) - Description of the parameter (`.raw` or `.html`)\n- `type` (string) - An arbitrary type of the parameter (a string)\n- `required` (boolean) - Boolean flag denoting whether the parameter is required (true) or not (false)\n- `default` (string) - A default value of the parameter (a value assumed when the parameter is not specified)\n- `example` (string) - An example value of the parameter\n- `values` (array) - An array enumerating possible parameter values\n    - (object)\n        - `value` (string) - Value choice of for the parameter\n\n### Transaction Example (object)\nAn HTTP transaction example with expected HTTP message request and response payload(s).\n\n#### Properties\n+ `name` (string) - Name of the Transaction Example\n+ `description` (string) - Description of the Transaction Example (`.raw` or `.html`)\n+ `requests` (array[[Payload][]]) - Ordered array of example transaction request payloads\n+ `responses` (array[[Payload][]]) - Ordered array of example transaction response payloads\n\n### Reference (object)\nA reference object which is used whenever there is a reference to a [Resource Model](https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#ResourceModelSection).\n\n#### Properties\n+ `id` (string) - The identifier (name) of the reference\n\n## Media Types\nThe `application/vnd.apiblueprint.ast` is the media type for API Blueprint AST. The media type serialization format is specified in the `+\u003cserialization format\u003e` appendix.\n\n### Serialization formats\nTwo supported, feature-equal serialization formats are JSON and YAML:\n\n+ `application/vnd.apiblueprint.ast.json`\n+ `application/vnd.apiblueprint.ast.yaml`\n\n### Example: JSON Serialization\n`application/vnd.apiblueprint.ast.json; version=4.0`\n\n```json\n{\n  \"_version\": \"\u003cAST version\u003e\",\n  \"metadata\": [\n    {\n      \"name\": \"\u003cmetadata key name\u003e\",\n      \"value\": \"\u003cmetadata value\u003e\"\n    }\n  ],\n  \"name\": \"\u003cAPI name\u003e\",\n  \"description\": \"\u003cAPI description\u003e\",\n  \"element\": \"category\",\n  \"content\": [\n    {\n      \"element\": \"category\",\n      \"attributes\": {\n        \"name\": \"\u003cresource group name\u003e\"\n      },\n      \"content\": [\n        {\n          \"element\": \"copy\",\n          \"content\": \"\u003cresource group description\u003e\"\n        },\n        {\n          \"name\": \"\u003cresource name\u003e\",\n          \"description\": \"\u003cresource description\u003e\",\n          \"element\": \"resource\",\n          \"uriTemplate\": \"\u003cresource URI template\u003e\",\n          \"model\": {\n            \"name\": \"\u003cresource model name\u003e\",\n            \"description\": \"\u003cresource model description\u003e\",\n            \"headers\": [\n              {\n                \"name\": \"\u003cHTTP header field name\u003e\",\n                \"value\": \"\u003cHTTP header field value\u003e\"\n              }\n            ],\n            \"content\": [\n              {\n                \"element\": \"dataStructure\",\n                \"content\":{\n                  \"element\": \"object\",\n                  \"meta\": {\n                    \"ref\": \"\u003csub-type\u003e\"\n                  },\n                  \"content\": []\n                }\n              },\n              {\n                \"element\": \"asset\",\n                \"attributes\":  {\n                  \"role\": \"bodyExample\"\n                },\n                \"content\": \"\u003cresource model body\u003e\"\n              },\n              {\n                \"element\": \"asset\",\n                \"attributes\":  {\n                  \"role\": \"bodySchema\"\n                },\n                \"content\": \"\u003cresource model schema\u003e\"\n              }\n            ]\n          },\n          \"parameters\": [\n            {\n              \"name\": \"\u003cname\u003e\",\n              \"description\": \"\u003cdescription\u003e\",\n              \"type\": \"\u003ctype\u003e\",\n              \"required\": \"\u003crequired parameter flag\u003e\",\n              \"default\": \"\u003cdefault value\u003e\",\n              \"example\": \"\u003cexample value\u003e\",\n              \"values\": [\n                {\n                  \"value\": \"\u003cenum element\u003e\"\n                }\n              ]\n            }\n          ],\n          \"actions\": [\n            {\n              \"name\": \"\u003caction name\u003e\",\n              \"description\": \"\u003caction description\u003e\",\n              \"method\": \"\u003caction HTTP request method\u003e\",\n              \"parameters\": [\n                {\n                  \"name\": \"\u003cname\u003e\",\n                  \"description\": \"\u003cdescription\u003e\",\n                  \"type\": \"\u003ctype\u003e\",\n                  \"required\": \"\u003crequired parameter flag\u003e\",\n                  \"default\": \"\u003cdefault value\u003e\",\n                  \"example\": \"\u003cexample value\u003e\",\n                  \"values\": [\n                    {\n                      \"value\": \"\u003cenum element\u003e\"\n                    }\n                  ]\n                }\n              ],\n              \"examples\": [\n                {\n                  \"name\": \"\u003ctransaction example name\u003e\",\n                  \"description\": \"\u003ctransaction example description\u003e\",\n                  \"requests\": [\n                    {\n                      \"name\": \"\u003crequest name\u003e\",\n                      \"description\": \"\u003crequest description\u003e\",\n                      \"headers\": [\n                        {\n                          \"name\": \"\u003cHTTP header field name\u003e\",\n                          \"value\": \"\u003cHTTP header field value\u003e\"\n                        }\n                      ],\n                      \"content\": [\n                        {\n                          \"element\": \"dataStructure\",\n                          \"content\": {\n                            \"element\": \"object\",\n                            \"meta\": {\n                              \"ref\": \"\u003csub-type\u003e\"\n                            },\n                            \"content\": []\n                          }\n                        },\n                        {\n                          \"element\": \"asset\",\n                          \"attributes\": {\n                            \"role\": \"bodyExample\"\n                          },\n                          \"content\": \"\u003crequest body\u003e\"\n                        },\n                        {\n                          \"element\": \"asset\",\n                          \"attributes\": {\n                            \"role\": \"bodySchema\"\n                          },\n                          \"content\": \"\u003crequest schema\u003e\"\n                        }\n                      ]\n                    }\n                  ],\n                  \"responses\": [\n                    {\n                      \"name\": \"\u003cresponse HTTP status code\u003e\",\n                      \"description\": \"\u003cresponse description\u003e\",\n                      \"headers\": [\n                        {\n                          \"name\": \"\u003cHTTP header field name\u003e\",\n                          \"value\": \"\u003cHTTP header field value\u003e\"\n                        }\n                      ],\n                      \"content\": [\n                        {\n                          \"element\": \"dataStructure\",\n                          \"content\": {\n                            \"element\": \"object\",\n                            \"meta\": {\n                              \"ref\": \"\u003csub-type\u003e\"\n                            },\n                            \"content\": []\n                          }\n                        },\n                        {\n                          \"element\": \"asset\",\n                          \"attributes\": {\n                            \"role\": \"bodyExample\"\n                          },\n                          \"content\": \"\u003crequest body\u003e\"\n                        },\n                        {\n                          \"element\": \"asset\",\n                          \"attributes\": {\n                            \"role\": \"bodySchema\"\n                          },\n                          \"content\": \"\u003crequest schema\u003e\"\n                        }\n                      ]\n                    }\n                  ]\n                }\n              ],\n              \"content\": [\n                {\n                  \"element\": \"dataStructure\",\n                  \"content\": {\n                    \"element\": \"object\",\n                    \"meta\": {\n                      \"ref\": \"\u003csub-type\u003e\"\n                    },\n                    \"content\": []\n                  }\n                }\n              ]\n            },\n            {\n              \"name\": \"\u003caction name\u003e\",\n              \"description\": \"\u003caction description\u003e\",\n              \"method\": \"\u003caction HTTP request method\u003e\",\n              \"parameters\": [],\n              \"examples\": [\n                {\n                  \"name\": \"\u003ctransaction example name\u003e\",\n                  \"description\": \"\u003ctransaction example description\u003e\",\n                  \"responses\": [\n                    {\n                      \"name\": \"\u003cresponse HTTP status code\u003e\",\n                      \"reference\": {\n                        \"id\": \"\u003cresource model name\u003e\"\n                      },\n                      \"description\": \"\u003cresource model description\u003e\",\n                      \"headers\": [\n                        {\n                          \"name\": \"\u003cHTTP header field name\u003e\",\n                          \"value\": \"\u003cHTTP header field value\u003e\"\n                        }\n                      ],\n                      \"content\": [\n                        {\n                          \"element\": \"asset\",\n                          \"attributes\": {\n                            \"role\": \"bodyExample\"\n                          },\n                          \"content\": \"\u003cresource model body\u003e\"\n                        },\n                        {\n                          \"element\": \"asset\",\n                          \"attributes\": {\n                            \"role\": \"bodySchema\"\n                          },\n                          \"content\": \"\u003cresource model schema\u003e\"\n                        }\n                      ]\n                    }\n                  ]\n                }\n              ]\n            }\n          ],\n          \"content\": [\n            {\n              \"element\": \"dataStructure\",\n              \"content\": {\n                \"element\": \"object\",\n                \"meta\": {\n                  \"id\": \"\u003cresource-name\u003e\",\n                  \"ref\": \"\u003csub-type\u003e\"\n                },\n                \"content\": []\n              }\n            }\n          ]\n        }\n      ]\n    },\n    {\n      \"element\": \"category\",\n      \"content\": [\n        {\n          \"element\": \"dataStructure\",\n          \"content\": {\n            \"element\": \"object\",\n            \"meta\": {\n              \"id\": \"\u003cdata-structure-name\u003e\",\n              \"ref\": \"\u003csub-type\u003e\"\n            },\n            \"content\": []\n          }\n        }\n      ]\n    }\n  ]\n}\n```\n\n## Related Media Types\n- [**Serialized Parsing Result Media Types**][Parsing media types] - Media types for the serialization of complete parsing results (including warnings and errors)\n\n## Serialization in Drafter\nThe `drafter` [command-line tool](https://github.com/apiaryio/drafter#drafter-command-line-tool) supports serialization of [API Blueprint AST](https://github.com/apiaryio/snowcrash/blob/master/src/Blueprint.h) via the `--format` option. Similarly, it also supports serialization of [API Blueprint Source Map](https://github.com/apiaryio/snowcrash/blob/master/src/BlueprintSourcemap.h) using the `--format` and `--sourcemap` option.\n\n## License\nMIT License. See the [LICENSE](LICENSE) file.\n\n[Parsing media types]: Parse%20Result.md\n\n[MSON]: https://github.com/apiaryio/mson\n\n[API Blueprint asset]: https://github.com/apiaryio/api-blueprint/blob/master/Glossary%20of%20Terms.md#asset\n\n[Attribute section]: https://github.com/apiaryio/api-blueprint/blob/zdne/attributes-description/API%20Blueprint%20Specification.md#def-attributes-section\n[Resource section]: https://github.com/apiaryio/api-blueprint/blob/zdne/attributes-description/API%20Blueprint%20Specification.md#def-resource-section\n[Relation section]: https://github.com/apiaryio/api-blueprint/blob/zdne/attributes-description/API%20Blueprint%20Specification.md#def-relation-section\n\n[Blueprint]: #blueprint-object\n[Element]: #element-object\n[Resource Group]: #resource-group-object\n[Resource]: #resource-object\n[Action]: #action-object\n[Payload]: #payload-object\n[Reference]: #reference-object\n[Asset]: #asset-element\n[Parameter]: #parameter-object\n[Transaction Example]: #transaction-example-object\n[Attributes]: #attributes-data-structure\n[Data Structure]: https://github.com/refractproject/refract-spec/blob/master/namespaces/api-description-namespace.md#data-structure-element\n[Data Structures]: #data-structures-object\n\n[Source Map Definition]: Source%20Map.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapiaryio%2Fapi-blueprint-ast","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapiaryio%2Fapi-blueprint-ast","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapiaryio%2Fapi-blueprint-ast/lists"}