├── LICENSE ├── Parse Result.md ├── README.md └── Source Map.md /LICENSE: -------------------------------------------------------------------------------- 1 | (The MIT License) 2 | 3 | Copyright (c) 2014 Apiary Inc. . 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining 6 | a copy of this software and associated documentation files (the 7 | 'Software'), to deal in the Software without restriction, including 8 | without limitation the rights to use, copy, modify, merge, publish, 9 | distribute, sublicense, and/or sell copies of the Software, and to 10 | permit persons to whom the Software is furnished to do so, subject to 11 | the following conditions: 12 | 13 | The above copyright notice and this permission notice shall be 14 | included in all copies or substantial portions of the Software. 15 | 16 | THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, 17 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 18 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 19 | IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 20 | CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 21 | TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 22 | SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -------------------------------------------------------------------------------- /Parse Result.md: -------------------------------------------------------------------------------- 1 | ![logo](https://raw.github.com/apiaryio/api-blueprint/master/assets/logo_apiblueprint.png) 2 | 3 | # Parse Result Media Types 4 | This document describes API Blueprint Serialized Parse Result Media Types – the media type used to serialize a result of parsing an API Blueprint document. In addition to parsed [API Blueprint AST](README.md) this media types bear the information on any and source annotations – warnings and errors - issued by the parser during parsing. 5 | 6 | ## Version 7 | 8 | + **Version**: 2.2 9 | + **Created**: 2014-06-09 10 | + **Updated**: 2015-09-07 11 | + **AST Serialization Media Types**: 4.0 12 | 13 | --- 14 | 15 | ## Quick Links 16 | 17 | + [Parse Result Description](#parse-result-description) 18 | + [Media Types](#media-types) 19 | + [JSON serialization](#json-serialization) 20 | + [Keys description](#keys-description) 21 | 22 | --- 23 | 24 | ## Parse Result Description 25 | Following is the description of Parse Result media types using the [MSON](https://github.com/apiaryio/mson) syntax. 26 | 27 | ### Parse Result Object 28 | 29 | - `_version` (string) - Version of the Parse Result Media Type as [defined](#version) in this document 30 | - `ast` ([AST](#ast)) - This is the abstract syntax tree (AST) of the parsed blueprint 31 | - `sourcemap` ([Source Map](#source-map)) - This is the sourcemap tree of the parsed blueprint whose content may not be present if the option to export source maps is not present 32 | - `error` ([Error](#error)) - Parsing error, if any 33 | - `warnings` (array[[Warning](#warning)]) - Ordered array of warnings occurred during the parsing, if any 34 | 35 | ### AST 36 | This object is the [Blueprint](README.md#blueprint-object) object as defined in the [AST Blueprint serialization Media Type](https://github.com/apiaryio/api-blueprint-ast). 37 | 38 | ### Source Map 39 | This object is the [Blueprint Source Map](README.md#blueprint-source-map) object as defined in [AST Blueprint serialization Media Type](https://github.com/apiaryio/api-blueprint-ast). 40 | 41 | ### Error 42 | 43 | Description of a parsing error as occurred during parsing. If this field is present and `code` different from `0` then the content of `ast` field should be ignored. 44 | 45 | #### Properties 46 | 47 | + `code` (number) - Error code. The `0` means success – no error occurred 48 | + `message` (string) - Error message 49 | + `location` ([Source Map](README.md#source-map)) – Error source map 50 | 51 | ### Warning 52 | 53 | Description of a warning from the parser. 54 | 55 | #### Properties 56 | 57 | + `code` (number) - Warning [group code](https://github.com/apiaryio/snowcrash/blob/master/src/SourceAnnotation.h#L115) 58 | + `message` (string) - Warning message 59 | + `location` ([Source Map](README.md#source-map)) – Warning source map 60 | 61 | --- 62 | 63 | ## Media Types 64 | 65 | The media type for API Blueprint Parsing result is `application/vnd.apiblueprint.parseresult`. The media type serialization format is specified in the `+` appendix. 66 | 67 | ### Serialization formats 68 | 69 | Two supported, feature-equal serialization formats are JSON and YAML: 70 | 71 | + `application/vnd.apiblueprint.parseresult+json` 72 | + `application/vnd.apiblueprint.parseresult+yaml` 73 | 74 | Parser Result Media Types inherit from the respective [AST Serialization Type](README.md): 75 | 76 | + [`application/vnd.apiblueprint.ast+json`](#json-serialization) 77 | + `application/vnd.apiblueprint.ast+yaml` 78 | + [`application/vnd.apiblueprint.sourcemap+json`](#json-serialization) 79 | + `application/vnd.apiblueprint.sourcemap+yaml` 80 | 81 | ### JSON Serialization 82 | 83 | `application/vnd.apiblueprint.parseresult+json; version=2.2` 84 | 85 | ```json 86 | { 87 | "_version": "2.2", 88 | "ast": { 89 | "_version": "4.0", 90 | 91 | ... 92 | }, 93 | "sourcemap": { 94 | ... 95 | }, 96 | "error": { 97 | "code": , 98 | "message": "", 99 | "location": [ 100 | { 101 | "index": , 102 | "length": 103 | } 104 | ] 105 | }, 106 | "warnings": [ 107 | { 108 | "code": , 109 | "message": "", 110 | "location": [ 111 | { 112 | "index": , 113 | "length": 114 | } 115 | ] 116 | } 117 | ] 118 | } 119 | ``` 120 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ![logo](https://raw.github.com/apiaryio/api-blueprint/master/assets/logo_apiblueprint.png) 2 | 3 | # API Blueprint AST 4 | 5 | ## Deprecation Notice 6 | 7 | As 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). 8 | 9 | ### JSON & YAML face of the API Blueprint 10 | API 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. 11 | 12 | This document defines serialization formats for [API Blueprint](http://apiblueprint.org) abstract syntax tree, or AST for short. 13 | 14 | For the definition of API Blueprint AST Source Map see the [API Blueprint AST Source Map definition][Source Map Definition]. 15 | 16 | Converting 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). 17 | 18 | ## Don't like to design APIs in JSON or YAML? 19 | If 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). 20 | 21 | ## Version 22 | + **Version**: 4.0 23 | + **Created**: 2013-08-30 24 | + **Updated**: 2015-09-07 25 | 26 | ## Future Development 27 | As of version 3.0 the API Blueprint AST is in the *interim* transition period 28 | towards unified document-structure based on the concept of DOM elements 29 | (see the [Element][] object). Please refrain from using AST elements marked as 30 | *"deprecated"*. 31 | 32 | ## Quick Links 33 | + [AST Description](#ast-definition) 34 | + [Media Types](#media-types) 35 | + [Keys description](#keys-description) 36 | + [Example: JSON serialization](#example-json-serialization) 37 | + [Serialization in Drafter](#serialization-in-drafter) 38 | + [Serialized Parsing Result Media Types][parsing media types] 39 | 40 | ## AST Definition 41 | Following is the definition of API Blueprint AST media types using the [MSON](https://github.com/apiaryio/mson) syntax. 42 | 43 | > **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. 44 | 45 | ### Blueprint (object) 46 | + `_version` (string) - Version of the AST Serialization as [defined](#version) in this document 47 | + `metadata` (array) - Ordered array of API Blueprint [metadata](https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#MetadataSection) 48 | - (object) 49 | - `name` (string) - Name of the metadata 50 | - `value` (string) - Value of the metadata 51 | 52 | + `name` (string) - Name of the API 53 | + `description` (string) - Top-level description of the API in Markdown (`.raw`) or HTML (`.html`) 54 | + `resourceGroups` (array[[Resource Group][]]) - **Deprecated** 55 | 56 | Note this property is **deprecated** and will be removed in a future. 57 | Replaced by `category` elements of the `content` property. 58 | 59 | + `element`: `category` (fixed, required) 60 | + `content` (array[[Element][]]) - Section elements of the blueprint 61 | 62 | ### Element (object) 63 | A component of an API description. 64 | 65 | #### Properties 66 | + `element` (enum[string]) - Element name 67 | + `category` - Element is a group of other elements 68 | + `copy` - Element is a human readable text 69 | + `resource` - Element is a Resource 70 | + `dataStructure` - Element is a Data Structure definition 71 | + `asset` - Element is an asset of API description 72 | + `attributes` (object) - Element-specific attributes 73 | + `name` (string, optional) - Human readable name of the element 74 | + `content` (enum) 75 | + (array[[Element][]]) - Ordered array of nested elements (for element `category`) 76 | + (string) - Markdown-formatted text (for element `copy` and `asset` type) 77 | + ([Resource][]) - Resource definiton (for element `resource`) 78 | + ([Data Structure][]) - Data structure (for element `dataStructure`) 79 | 80 | ### Resource Group (object) 81 | **Deprecated**, replaced by the `category` [Element][]. 82 | 83 | Logical group of resources. 84 | 85 | #### Properties 86 | + `name` (string) - Name of the Resource Group 87 | + `description` (string) - Description of the Resource Group (`.raw` or `.html`) 88 | + `resources` (array[[Resource][]]) - Ordered array of the respective resources belonging to the Resource Group 89 | 90 | ### Resource (object) 91 | Description of one resource, or a cluster of resources defined by its URI template. 92 | 93 | #### Properties 94 | + `name` (string) - Name of the Resource 95 | + `description` (string) - Description of the Resource (`.raw` or `.html`) 96 | + `element`: `resource` (fixed, required) 97 | + `uriTemplate` (string) - URI Template as defined in [RFC6570](http://tools.ietf.org/html/rfc6570) 98 | + `model` ([Payload][]) - [Resource Model](https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#ResourceModelSection), a reusable payload representing the resource 99 | + `parameters` (array[[Parameter][]]) - Ordered array of URI parameters 100 | + `actions` (array[[Action][]]) - Ordered array of actions available on the resource each defining at least one complete HTTP transaction 101 | + `content` (array[[Data Structure][]]) - Array of Resource's elements 102 | 103 | In the interim period this may contain at maximum one 104 | element of the `dataStructure` type - the definition of the of the Resource 105 | attributes. 106 | 107 | ### Action (object) 108 | An HTTP transaction (a request-response transaction). Actions are specified by an HTTP request method within a resource. 109 | 110 | #### Properties 111 | + `name` (string) - Name of the Action 112 | + `description` (string) - Description of the Action (`.raw` or `.html`) 113 | + `method` (string) - HTTP request method defining the action 114 | + `parameters` (array[[Parameter][]]) - Ordered array of resource's URI parameters descriptions specific to this action 115 | + `examples` (array[[Transaction Example][]]) - Ordered array of HTTP transaction [examples](#example-section) for the relevant HTTP request method 116 | + `attributes` (object) - Action-specific attributes 117 | + `uriTemplate` (string) - URI Template as defined in [RFC6570](http://tools.ietf.org/html/rfc6570) 118 | + `relation` (string) - Link relation identifier of the action as defined in [Relation section][] 119 | + `content` (array[[Data Structure][]]) - Array of Action's elements 120 | 121 | In the interim period this may contain at maximum one 122 | element of the `dataStructure` type - the definition of the of the action input 123 | attributes. 124 | 125 | ### Payload (object) 126 | An [API Blueprint payload](https://github.com/apiaryio/api-blueprint/blob/master/Glossary%20of%20Terms.md#payload). 127 | 128 | #### Properties 129 | + `name` (string) - Name of the payload 130 | 131 | The content of this key depends on the type of payload: 132 | 133 | + **model** payload: name of the resource, if any 134 | + **request** payload: name of the request, if any 135 | + **response** payload: HTTP status code 136 | 137 | + `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 138 | + `description` (string) - Description of the payload (`.raw` or `.html`) 139 | + `headers` (array[[Header][]]) - Ordered array of HTTP headers that are expected to be transferred with HTTP message represented by this payload 140 | + `body` (string) - **Deprecated** 141 | 142 | An entity body to be transferred with HTTP message represented by this payload 143 | 144 | Note this property is **deprecated** and will be removed in a future. 145 | Replaced by `bodyExample` [Asset][] element. 146 | 147 | + `schema` (string) - **Deprecated** 148 | 149 | A validation schema for the entity body as defined in `body`. 150 | 151 | Note this property is **deprecated** and will be removed in a future. 152 | Replaced by `bodySchema` `asset` element. 153 | 154 | + `content` (array) - Array of Payloads's elements 155 | 156 | In the interim period this may contain only: 157 | + At maximum one element of the `dataStructure` type - the definition of the message-body 158 | attributes 159 | + Up to two asset elements one for body example other for body schema 160 | 161 | + Items 162 | + ([Data Structure][]) 163 | + ([Asset][]) 164 | 165 | ### Header 166 | A HTTP header that are expected to be transferred with an HTTP message. 167 | 168 | #### Properties 169 | + `name` (string, required) - The name of the header 170 | + `value` (string, required) - The value of the header 171 | 172 | ### Asset (Element) 173 | An [API Blueprint asset][]. The content is an Asset in its textual 174 | representation as written in the source API Blueprint. 175 | 176 | #### Properties 177 | + `element`: `asset` (fixed, required) 178 | + `attributes` 179 | + `role` - Role of the asset 180 | + `bodyExample` - Asset is an example of message-body 181 | + `bodySchema` - Asset is an schema for message-body 182 | 183 | ### Parameter (object) 184 | Description of one URI template parameter. 185 | 186 | #### Properties 187 | - `name` (string) - Name of the parameter 188 | - `description` (string) - Description of the parameter (`.raw` or `.html`) 189 | - `type` (string) - An arbitrary type of the parameter (a string) 190 | - `required` (boolean) - Boolean flag denoting whether the parameter is required (true) or not (false) 191 | - `default` (string) - A default value of the parameter (a value assumed when the parameter is not specified) 192 | - `example` (string) - An example value of the parameter 193 | - `values` (array) - An array enumerating possible parameter values 194 | - (object) 195 | - `value` (string) - Value choice of for the parameter 196 | 197 | ### Transaction Example (object) 198 | An HTTP transaction example with expected HTTP message request and response payload(s). 199 | 200 | #### Properties 201 | + `name` (string) - Name of the Transaction Example 202 | + `description` (string) - Description of the Transaction Example (`.raw` or `.html`) 203 | + `requests` (array[[Payload][]]) - Ordered array of example transaction request payloads 204 | + `responses` (array[[Payload][]]) - Ordered array of example transaction response payloads 205 | 206 | ### Reference (object) 207 | A 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). 208 | 209 | #### Properties 210 | + `id` (string) - The identifier (name) of the reference 211 | 212 | ## Media Types 213 | The `application/vnd.apiblueprint.ast` is the media type for API Blueprint AST. The media type serialization format is specified in the `+` appendix. 214 | 215 | ### Serialization formats 216 | Two supported, feature-equal serialization formats are JSON and YAML: 217 | 218 | + `application/vnd.apiblueprint.ast.json` 219 | + `application/vnd.apiblueprint.ast.yaml` 220 | 221 | ### Example: JSON Serialization 222 | `application/vnd.apiblueprint.ast.json; version=4.0` 223 | 224 | ```json 225 | { 226 | "_version": "", 227 | "metadata": [ 228 | { 229 | "name": "", 230 | "value": "" 231 | } 232 | ], 233 | "name": "", 234 | "description": "", 235 | "element": "category", 236 | "content": [ 237 | { 238 | "element": "category", 239 | "attributes": { 240 | "name": "" 241 | }, 242 | "content": [ 243 | { 244 | "element": "copy", 245 | "content": "" 246 | }, 247 | { 248 | "name": "", 249 | "description": "", 250 | "element": "resource", 251 | "uriTemplate": "", 252 | "model": { 253 | "name": "", 254 | "description": "", 255 | "headers": [ 256 | { 257 | "name": "", 258 | "value": "" 259 | } 260 | ], 261 | "content": [ 262 | { 263 | "element": "dataStructure", 264 | "content":{ 265 | "element": "object", 266 | "meta": { 267 | "ref": "" 268 | }, 269 | "content": [] 270 | } 271 | }, 272 | { 273 | "element": "asset", 274 | "attributes": { 275 | "role": "bodyExample" 276 | }, 277 | "content": "" 278 | }, 279 | { 280 | "element": "asset", 281 | "attributes": { 282 | "role": "bodySchema" 283 | }, 284 | "content": "" 285 | } 286 | ] 287 | }, 288 | "parameters": [ 289 | { 290 | "name": "", 291 | "description": "", 292 | "type": "", 293 | "required": "", 294 | "default": "", 295 | "example": "", 296 | "values": [ 297 | { 298 | "value": "" 299 | } 300 | ] 301 | } 302 | ], 303 | "actions": [ 304 | { 305 | "name": "", 306 | "description": "", 307 | "method": "", 308 | "parameters": [ 309 | { 310 | "name": "", 311 | "description": "", 312 | "type": "", 313 | "required": "", 314 | "default": "", 315 | "example": "", 316 | "values": [ 317 | { 318 | "value": "" 319 | } 320 | ] 321 | } 322 | ], 323 | "examples": [ 324 | { 325 | "name": "", 326 | "description": "", 327 | "requests": [ 328 | { 329 | "name": "", 330 | "description": "", 331 | "headers": [ 332 | { 333 | "name": "", 334 | "value": "" 335 | } 336 | ], 337 | "content": [ 338 | { 339 | "element": "dataStructure", 340 | "content": { 341 | "element": "object", 342 | "meta": { 343 | "ref": "" 344 | }, 345 | "content": [] 346 | } 347 | }, 348 | { 349 | "element": "asset", 350 | "attributes": { 351 | "role": "bodyExample" 352 | }, 353 | "content": "" 354 | }, 355 | { 356 | "element": "asset", 357 | "attributes": { 358 | "role": "bodySchema" 359 | }, 360 | "content": "" 361 | } 362 | ] 363 | } 364 | ], 365 | "responses": [ 366 | { 367 | "name": "", 368 | "description": "", 369 | "headers": [ 370 | { 371 | "name": "", 372 | "value": "" 373 | } 374 | ], 375 | "content": [ 376 | { 377 | "element": "dataStructure", 378 | "content": { 379 | "element": "object", 380 | "meta": { 381 | "ref": "" 382 | }, 383 | "content": [] 384 | } 385 | }, 386 | { 387 | "element": "asset", 388 | "attributes": { 389 | "role": "bodyExample" 390 | }, 391 | "content": "" 392 | }, 393 | { 394 | "element": "asset", 395 | "attributes": { 396 | "role": "bodySchema" 397 | }, 398 | "content": "" 399 | } 400 | ] 401 | } 402 | ] 403 | } 404 | ], 405 | "content": [ 406 | { 407 | "element": "dataStructure", 408 | "content": { 409 | "element": "object", 410 | "meta": { 411 | "ref": "" 412 | }, 413 | "content": [] 414 | } 415 | } 416 | ] 417 | }, 418 | { 419 | "name": "", 420 | "description": "", 421 | "method": "", 422 | "parameters": [], 423 | "examples": [ 424 | { 425 | "name": "", 426 | "description": "", 427 | "responses": [ 428 | { 429 | "name": "", 430 | "reference": { 431 | "id": "" 432 | }, 433 | "description": "", 434 | "headers": [ 435 | { 436 | "name": "", 437 | "value": "" 438 | } 439 | ], 440 | "content": [ 441 | { 442 | "element": "asset", 443 | "attributes": { 444 | "role": "bodyExample" 445 | }, 446 | "content": "" 447 | }, 448 | { 449 | "element": "asset", 450 | "attributes": { 451 | "role": "bodySchema" 452 | }, 453 | "content": "" 454 | } 455 | ] 456 | } 457 | ] 458 | } 459 | ] 460 | } 461 | ], 462 | "content": [ 463 | { 464 | "element": "dataStructure", 465 | "content": { 466 | "element": "object", 467 | "meta": { 468 | "id": "", 469 | "ref": "" 470 | }, 471 | "content": [] 472 | } 473 | } 474 | ] 475 | } 476 | ] 477 | }, 478 | { 479 | "element": "category", 480 | "content": [ 481 | { 482 | "element": "dataStructure", 483 | "content": { 484 | "element": "object", 485 | "meta": { 486 | "id": "", 487 | "ref": "" 488 | }, 489 | "content": [] 490 | } 491 | } 492 | ] 493 | } 494 | ] 495 | } 496 | ``` 497 | 498 | ## Related Media Types 499 | - [**Serialized Parsing Result Media Types**][Parsing media types] - Media types for the serialization of complete parsing results (including warnings and errors) 500 | 501 | ## Serialization in Drafter 502 | The `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. 503 | 504 | ## License 505 | MIT License. See the [LICENSE](LICENSE) file. 506 | 507 | [Parsing media types]: Parse%20Result.md 508 | 509 | [MSON]: https://github.com/apiaryio/mson 510 | 511 | [API Blueprint asset]: https://github.com/apiaryio/api-blueprint/blob/master/Glossary%20of%20Terms.md#asset 512 | 513 | [Attribute section]: https://github.com/apiaryio/api-blueprint/blob/zdne/attributes-description/API%20Blueprint%20Specification.md#def-attributes-section 514 | [Resource section]: https://github.com/apiaryio/api-blueprint/blob/zdne/attributes-description/API%20Blueprint%20Specification.md#def-resource-section 515 | [Relation section]: https://github.com/apiaryio/api-blueprint/blob/zdne/attributes-description/API%20Blueprint%20Specification.md#def-relation-section 516 | 517 | [Blueprint]: #blueprint-object 518 | [Element]: #element-object 519 | [Resource Group]: #resource-group-object 520 | [Resource]: #resource-object 521 | [Action]: #action-object 522 | [Payload]: #payload-object 523 | [Reference]: #reference-object 524 | [Asset]: #asset-element 525 | [Parameter]: #parameter-object 526 | [Transaction Example]: #transaction-example-object 527 | [Attributes]: #attributes-data-structure 528 | [Data Structure]: https://github.com/refractproject/refract-spec/blob/master/namespaces/api-description-namespace.md#data-structure-element 529 | [Data Structures]: #data-structures-object 530 | 531 | [Source Map Definition]: Source%20Map.md 532 | -------------------------------------------------------------------------------- /Source Map.md: -------------------------------------------------------------------------------- 1 | ![logo](https://raw.github.com/apiaryio/api-blueprint/master/assets/logo_apiblueprint.png) 2 | 3 | # API Blueprint AST Source Map 4 | This document defines API Blueprint AST Source Map. API Blueprint Source Map is 1-on-1 with API Blueprint AST and represents the source maps for each of the nodes in the AST tree. 5 | 6 | ## Version 7 | Refer to the [API Blueprint AST Definition][] – the version of the Source Map always conforms to the version of API Blueprint AST. 8 | 9 | ## Quick Links 10 | + [Source Map Definition](#source-map-definition) 11 | + [Media Types](#media-types) 12 | + [Example: JSON serialization](#example-json-serialization) 13 | 14 | ## Source Map Definition 15 | Following is the definition of Source map media types using the [MSON][] syntax. 16 | 17 | ### Source Map (array) 18 | Set of indices to source code blocks. The blocks may be non-continuous. 19 | 20 | Each block is defined by a zero-based index of its first character and the number of following characters. 21 | 22 | #### Items 23 | - (array, fixed) - A tuple defining position of a block in the source code 24 | - *1219* (number) - Zero-based index of the first character 25 | - *30* (number) - Number of the characters in the block 26 | 27 | ### Blueprint Source Map (object) 28 | Source map of the [Blueprint][]. 29 | 30 | #### Properties 31 | + `metadata` (array[[Source Map][]]) - An array of source maps where each item in metadata has its own source map 32 | + `name` ([Source Map][]) - Source map of API name 33 | + `description` ([Source Map][]) - Source map of API description 34 | + `resourceGroups` (array[[Resource Group Source Map][]]) - **Deprecated** 35 | + `content` (array[[Element Source Map][]]) - Source map of section elements 36 | 37 | ### Element Source Map (object) 38 | + `attributes` 39 | + `name` ([Source Map][]) - Source map of the element name 40 | + `content` (enum) 41 | + (array[[Element Source Map][]]) - Source maps of nested elements (for element `category`) 42 | + ([Source Map][]) - Source map (for element `copy` and `asset`) 43 | + ([Resource Source Map][]) - Source map of Resource (for element `resource`) 44 | + ([Data Structure Source Map][]) - Source map of Data Structure (for element `dataStructure`) 45 | 46 | ### Resource Group Source Map (object) 47 | **Deprecated** 48 | 49 | Source map of the [Resource Group][]. 50 | 51 | #### Properties 52 | + `name` ([Source Map][]) - Source map of name of the Resource Group 53 | + `description` ([Source Map][]) - Source map of description of the Resource Group 54 | + `resources` (array[[Resource Source Map][]]) - Ordered array of the respective resources belonging to the Resource Group 55 | 56 | ### Resource Source Map (object) 57 | Source map of the [Resource][]. 58 | 59 | #### Properties 60 | + `name` ([Source Map][]) - Source map of name of the Resource 61 | + `description` ([Source Map][]) - Source map of description of the Resource 62 | + `uriTemplate` ([Source Map][]) - Source map of URI Template 63 | + `model` ([Payload Source map][]) - [Resource Model](https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#ResourceModelSection), a reusable payload representing the resource 64 | + `parameters` (array[[Parameter Source Map][]]) - Ordered array of source maps of URI parameters 65 | + `actions` (array[[Action Source Map][]]) - Ordered array of source maps of actions available on the resource each defining at least one complete HTTP transaction 66 | + `content` (array[[Data Structure Source Map][]]) - Ordered array of Resource source map's elements 67 | 68 | ### Action Source Map (object) 69 | Source map of the [Action][]. 70 | 71 | #### Properties 72 | + `name` ([Source Map][]) - Source map of name of the Action 73 | + `description` ([Source Map][]) - Source map of description of the Action 74 | + `method` ([Source Map][]) - Source map of HTTP request method defining the action 75 | + `parameters` (array[[Parameter Source Map][]]) - Ordered array of source maps of resource's URI parameters descriptions specific to this action 76 | + `examples` (array[[Transaction Example Source Map][]]) - Ordered array of source maps of HTTP transaction [examples](#example-section) for the relevant HTTP request method 77 | + `attributes` (object) 78 | + `uriTemplate` (string) - Source map of URI Template 79 | + `relation` (string) - Source map of link relation identifier of the action 80 | + `content` (array[[Data Structure Source Map][]]) - Ordered array of Action source map's elements 81 | 82 | ### Payload Source Map (object) 83 | Source map of [Payload][]. 84 | 85 | When a reference is used, the source map of the payload is in fact the source map of the [Resource Model](https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#ResourceModelSection). 86 | 87 | #### Properties 88 | + `name` ([Source Map][]) - Source map of name of the payload 89 | + `reference` ([Source Map][]) - Source map of the 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 90 | + `description` ([Source Map][]) - Source map of description of the payload 91 | + `attributes` ([Attributes Source Map][]) - Source map of attributes of the Payload 92 | + `headers` (array[[Source Map][]]) - Ordered array of source maps of HTTP headers that are expected to be transferred with HTTP message represented by this payload. Each item in the header has it's own source map. 93 | + `body` ([Source Map][]) - **Deprecated** 94 | 95 | Source map of body to be transferred with HTTP message represented by this payload 96 | 97 | Note this property is **deprecated** and will be removed in a future. Use `assets/body/source` instead. 98 | 99 | + `schema` ([Source Map][]) - **Deprecated** 100 | 101 | Source map of a validation schema for the entity body as defined in `body`. 102 | 103 | Note this property is **deprecated** and will be removed in a future. Use `assets/schema/source` instead. 104 | 105 | + `content` (array) - Ordered array of Payload source map's elements 106 | 107 | + Items 108 | + ([Data Structure Source Map][]) 109 | + ([Asset Source Map][]) 110 | 111 | ### Asset Source Map ([Element Source Map][]) 112 | Source map of [Asset][] 113 | 114 | ### Parameter Source Map (object) 115 | Source map of [Parameter][]. 116 | 117 | #### Properties 118 | + `description` ([Source Map][]) - Source map of description of the parameter 119 | + `type` ([Source Map][]) - Source map of an arbitrary type of the parameter (a string) 120 | + `required` ([Source Map][]) - Source map of boolean flag denoting whether the parameter is required (true) or not (false) 121 | + `default` ([Source Map][]) - Source map of a default value of the parameter (a value assumed when the parameter is not specified) 122 | + `example` ([Source Map][]) - Source map of an example value of the parameter 123 | + `values` (array[[Source Map][]]) - Source map of an array enumerating possible parameter values. Each item has it's own source map. 124 | 125 | ### Transaction Example Source Map (object) 126 | Source map of [Transaction Example][]. 127 | 128 | #### Properties 129 | + `name` ([Source Map][]) - Source map of name of the Transaction Example 130 | + `description` ([Source Map][]) - Source map of description of the Transaction Example 131 | + `requests` (array[[Payload Source Map][]]) - Ordered array of source maps of example transaction request payloads 132 | + `responses` (array[[Payload Source Map][]]) - Ordered array of source maps of example transaction response payloads 133 | 134 | ### Data Structure Source Map ([Named Type Source Map][]) 135 | Source map of [Data Structure][] 136 | 137 | ## Media Types 138 | The `application/vnd.apiblueprint.sourcemap` is the base media type for API Blueprint AST Source Map. 139 | 140 | ### Serialization formats 141 | Two supported, feature-equal serialization formats are JSON and YAML: 142 | 143 | + `application/vnd.apiblueprint.sourcemap+json` 144 | + `application/vnd.apiblueprint.sourcemap+yaml` 145 | 146 | 147 | [MSON]: https://github.com/apiaryio/mson 148 | [API Blueprint AST Definition]: README.md 149 | 150 | [Blueprint]: README.md#blueprint-object 151 | [Resource Group]: README.md#resource-group-object 152 | [Resource]: README.md#resource-object 153 | [Action]: README.md#action-object 154 | [Payload]: README.md#payload-object 155 | [Asset]: README.md#asset-object 156 | [Parameter]: README.md#parameter-object 157 | [Transaction Example]: README.md#transaction-example-object 158 | [Attributes]: README.md#attributes-data-structure 159 | [Data Structure]: README.md#data-structure-object 160 | [Data Structures]: README.md#data-structures-object 161 | 162 | [Source Map]: #source-map-array 163 | [Blueprint Source Map]: #blueprint-source-map-object 164 | [Resource Group Source Map]: #resource-group-source-map-object 165 | [Resource Source Map]: #resource-source-map-object 166 | [Action Source Map]: #action-source-map-object 167 | [Payload Source Map]: #payload-source-map-object 168 | [Asset Source Map]: #asset-source-map-element-source-map 169 | [Parameter Source Map]: #parameter-source-map-object 170 | [Transaction Example Source Map]: #transaction-example-source-map-object 171 | [Data Structure Source Map]: #data-structure-source-map-named-type-source-map 172 | [Element Source Map]: #element-source-map-object 173 | 174 | [Named Type Source Map]: https://github.com/apiaryio/mson-ast/blob/master/Source%20Map.md#named-type-source-map-object 175 | --------------------------------------------------------------------------------