4 | 8 |
9 | 10 |API Elements is a structure for describing APIs and the complex data structures used within them.
11 | 12 | 20 | 21 | -------------------------------------------------------------------------------- /docs/additional-information.md: -------------------------------------------------------------------------------- 1 | # Additional Information 2 | 3 | This page lists links and references for additional reading. 4 | 5 | - [API Blueprint](https://apiblueprint.org/) - API description format that utilizes API Elements as its parsing results 6 | - [MSON](https://github.com/apiaryio/mson) - Data structure format that utilizes API Elements as its parsing results (see the Data Structure Elements) 7 | -------------------------------------------------------------------------------- /docs/conf.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python3 2 | # -*- coding: utf-8 -*- 3 | # 4 | # a documentation build configuration file, created by 5 | # sphinx-quickstart on Mon Jan 15 14:21:21 2018. 6 | # 7 | # This file is execfile()d with the current directory set to its 8 | # containing dir. 9 | # 10 | # Note that not all possible configuration values are present in this 11 | # autogenerated file. 12 | # 13 | # All configuration values have a default; values that are commented out 14 | # serve to show the default. 15 | 16 | # If extensions (or modules to document with autodoc) are in another directory, 17 | # add these directories to sys.path here. If the directory is relative to the 18 | # documentation root, use os.path.abspath to make it absolute, like shown here. 19 | # 20 | # import os 21 | # import sys 22 | # sys.path.insert(0, os.path.abspath('.')) 23 | 24 | import recommonmark 25 | from recommonmark.transform import AutoStructify 26 | from recommonmark.parser import CommonMarkParser 27 | 28 | 29 | # -- General configuration ------------------------------------------------ 30 | 31 | # If your documentation needs a minimal Sphinx version, state it here. 32 | # 33 | # needs_sphinx = '1.0' 34 | 35 | # Add any Sphinx extension module names here, as strings. They can be 36 | # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 37 | # ones. 38 | extensions = [] 39 | 40 | # Add any paths that contain templates here, relative to this directory. 41 | templates_path = ['_templates'] 42 | 43 | # The suffix(es) of source filenames. 44 | # You can specify multiple suffix as a list of string: 45 | # 46 | source_suffix = ['.rst', '.md'] 47 | 48 | source_parsers = { 49 | '.md': CommonMarkParser, 50 | } 51 | 52 | # The master toctree document. 53 | master_doc = 'index' 54 | 55 | # General information about the project. 56 | project = 'API Elements' 57 | copyright = '2018, Apiary' 58 | author = 'Apiary' 59 | 60 | # The version info for the project you're documenting, acts as replacement for 61 | # |version| and |release|, also used in various other places throughout the 62 | # built documents. 63 | # 64 | # The short X.Y version. 65 | version = '1.0' 66 | # The full version, including alpha/beta/rc tags. 67 | release = '1.0' 68 | 69 | # The language for content autogenerated by Sphinx. Refer to documentation 70 | # for a list of supported languages. 71 | # 72 | # This is also used if you do content translation via gettext catalogs. 73 | # Usually you set "language" from the command line for these cases. 74 | language = None 75 | 76 | # List of patterns, relative to source directory, that match files and 77 | # directories to ignore when looking for source files. 78 | # This patterns also effect to html_static_path and html_extra_path 79 | exclude_patterns = [] 80 | 81 | # The name of the Pygments (syntax highlighting) style to use. 82 | pygments_style = 'sphinx' 83 | 84 | # If true, `todo` and `todoList` produce output, else they produce nothing. 85 | todo_include_todos = False 86 | 87 | 88 | # -- Options for HTML output ---------------------------------------------- 89 | 90 | # The theme to use for HTML and HTML Help pages. See the documentation for 91 | # a list of builtin themes. 92 | # 93 | html_theme = 'sphinx_rtd_theme' 94 | 95 | # Theme options are theme-specific and customize the look and feel of a theme 96 | # further. For a list of options available for each theme, see the 97 | # documentation. 98 | # 99 | # html_theme_options = {} 100 | 101 | # Add any paths that contain custom static files (such as style sheets) here, 102 | # relative to this directory. They are copied after the builtin static files, 103 | # so a file named "default.css" will overwrite the builtin "default.css". 104 | html_static_path = ['_static'] 105 | 106 | # Custom sidebar templates, must be a dictionary that maps document names 107 | # to template names. 108 | # 109 | # This is required for the alabaster theme 110 | # refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars 111 | 112 | # Custom sidebar templates, maps document names to template names. 113 | html_sidebars = { 114 | 'index': ['sidebar_intro.html', 'globaltoc.html', 'searchbox.html'], 115 | '**': ['sidebar_intro.html', 'localtoc.html', 'relations.html', 'searchbox.html'], 116 | } 117 | 118 | html_show_sourcelink = False 119 | html_show_sphinx = False 120 | 121 | 122 | # -- Options for HTMLHelp output ------------------------------------------ 123 | 124 | # Output file base name for HTML help builder. 125 | htmlhelp_basename = 'adoc' 126 | 127 | 128 | # -- Options for LaTeX output --------------------------------------------- 129 | 130 | latex_elements = { 131 | # The paper size ('letterpaper' or 'a4paper'). 132 | # 133 | # 'papersize': 'letterpaper', 134 | 135 | # The font size ('10pt', '11pt' or '12pt'). 136 | # 137 | # 'pointsize': '10pt', 138 | 139 | # Additional stuff for the LaTeX preamble. 140 | # 141 | # 'preamble': '', 142 | 143 | # Latex figure (float) alignment 144 | # 145 | # 'figure_align': 'htbp', 146 | } 147 | 148 | # Grouping the document tree into LaTeX files. List of tuples 149 | # (source start file, target name, title, 150 | # author, documentclass [howto, manual, or own class]). 151 | latex_documents = [ 152 | (master_doc, 'a.tex', 'a Documentation', 153 | 'a', 'manual'), 154 | ] 155 | 156 | 157 | # -- Options for manual page output --------------------------------------- 158 | 159 | # One entry per manual page. List of tuples 160 | # (source start file, name, description, authors, manual section). 161 | man_pages = [ 162 | (master_doc, 'a', 'a Documentation', 163 | [author], 1) 164 | ] 165 | 166 | 167 | # -- Options for Texinfo output ------------------------------------------- 168 | 169 | # Grouping the document tree into Texinfo files. List of tuples 170 | # (source start file, target name, title, author, 171 | # dir menu entry, description, category) 172 | texinfo_documents = [ 173 | (master_doc, 'a', 'a Documentation', 174 | author, 'a', 'One line description of project.', 175 | 'Miscellaneous'), 176 | ] 177 | 178 | 179 | github_doc_root = 'https://github.com/apiaryio/api-elements/tree/master/doc/' 180 | 181 | 182 | def setup_recommonmark(app): 183 | app.add_config_value('recommonmark_config', { 184 | 'url_resolver': lambda url: github_doc_root + url, 185 | 'enable_eval_rst': True, 186 | 'auto_toc_tree_section': 'Contents', 187 | 'enable_auto_doc_ref': False, 188 | }, True) 189 | app.add_transform(AutoStructify) 190 | 191 | 192 | def setup(app): 193 | app.add_stylesheet('css/table.css') 194 | setup_recommonmark(app) 195 | -------------------------------------------------------------------------------- /docs/element-definitions.md: -------------------------------------------------------------------------------- 1 | # Element Reference 2 | 3 | ## Element 4 | 5 | An _Element_ SHALL be a tuple (`element`, `meta`, `attributes`, `content`) where 6 | - `element` SHALL be a non-empty, finite character string identifying the _type_ of this Element 7 | - `meta` SHALL be a set of _properties_, some of which have [reserved semantics](#reserved-meta-properties) 8 | - `attributes` SHALL be a set of _properties_ defined by the _type_ of this Element 9 | - `content` SHALL be defined by the _type_ of this Element 10 | 11 | Entries in `meta` SHOULD be independent of Element. 12 | Entries in `attributes` MAY be Element specific. 13 | 14 | ### Property 15 | 16 | A _property_ SHALL be a tuple (`key`, `value`) where 17 | - `key` SHALL be a non-empty, finite character string 18 | - `value` SHALL be an _Element_ 19 | - Two properties SHALL be equal if their keys are. 20 | 21 | > The last statement defining equality on properties through their keys allows definition of _objects_ as _sets_ of properties. 22 | 23 | ### Values 24 | Following values can be described in API Elements: 25 | - _null_ value 26 | - boolean values _true_ and _false_ 27 | - rational numbers, i.e. floating point numbers with finite precision 28 | - finite character strings 29 | - finite sets of properties 30 | - finite lists of values 31 | 32 | ### Types 33 | Types specify value categories. Every Element SHALL describe a type. 34 | 35 | Note that because types may be restricted to exactly one value, an Element MAY match only a single value; such an Element still represents a type, not the value itself. 36 | 37 | An Element can therefore be thought of as a predicate that holds if, and only if, given value is in its value category. Given `Number` is the predicate classifying rational numbers, `Number(42.0)` SHALL hold, whereas `Number("foobar")` SHALL NOT. 38 | 39 | #### Subtypes 40 | We say the type _S_ is a _subtype_ of type _T_ if, and only if, all values of _S_ are also values of _T_. 41 | 42 | --- 43 | 44 | API Elements predefines three broad categories of Element types: 45 | 1. [Data Structure Element types](#data-structure-element-types) - Tools to define types, e.g. [string][], [array][], [object][] 46 | 2. [API Element types](#api-element-types) - Types specific to API description 47 | 3. [Parse Result Element types](#parse-result-element-types) - Types specific to document parsing, e.g. source map, parse result 48 | 49 | 50 | ### Reserved meta properties 51 | 52 | Any of the following properties MAY be an entry of any Element's `meta`: 53 | 54 | - `id` ([String][]) - Unique name of this Element; defines a named type; MUST be unique with respect to other `id`s in a document 55 | - `ref` ([Ref](#ref-element)) - Pointer to referenced element or type 56 | - `classes` ([Array][][[String][]]) - Classifications for given element 57 | - `title` ([String][]) - Human-readable title of element 58 | - `description` ([String][]) - Human-readable description of element 59 | - `links` ([Array][][[Link Element](#link-element)]) - Meta links for a given element 60 | 61 | ### Examples 62 | 63 | A primitive Element representing finite character strings is [String][], of type id `string`. Serialized into JSON, an Element representing `Hello world!` interpreted as a [String][] value: 64 | 65 | ```json 66 | { 67 | "element": "string", 68 | "content": "Hello world!" 69 | } 70 | ``` 71 | 72 | 73 | A less trivial example is the following `asset` Element. The specific semantic interpretation of an `asset` Element is well defined in the API Elements Reference section. What we essentially describe here is a JSON snippet `{"foo": "bar"}` defined in the message body of documentation. 74 | ```json 75 | { 76 | "element": "asset", 77 | "meta": { 78 | "classes": { 79 | "element": "array", 80 | "content": [ 81 | { 82 | "element": "string", 83 | "content": "messageBody" 84 | } 85 | ] 86 | } 87 | }, 88 | "attributes": { 89 | "contentType": { 90 | "element": "string", 91 | "content": "application/json" 92 | } 93 | }, 94 | "content": "{\"foo\": \"bar\"}" 95 | } 96 | ``` 97 | 98 | --- 99 | 100 | ## Data Structure Element types 101 | 102 | ### Overview 103 | 104 | [API Elements](#api-element-types) and [Parse Result Elements](#parse-result-element-types) are all defined via Data Structure Elements. 105 | The following table summarizes them very broadly. 106 | 107 || Name | 111 |Type (JSON serialized) | 112 |Value (JSON serialized) | 113 |
|---|---|---|
| null | 118 |
119 | {
120 | "element": "null"
121 | }
122 | |
123 | null |
124 |
| boolean | 127 |
128 | {
129 | "element": "boolean"
130 | }
131 | |
132 |
133 | true134 | false135 | |
136 |
| number | 139 |
140 | {
141 | "element": "number"
142 | }
143 | |
144 |
145 | 0146 | -1.5147 | 6.53e-3148 | |
149 |
| string | 152 |
153 | {
154 | "element": "string"
155 | }
156 | |
157 |
158 | "Hello world"159 | ""160 | |
161 |
| array | 166 |
167 | {
168 | "element": "array"
169 | }
170 | |
171 |
172 | []173 | [42, "Hello world!"]174 | |
175 |
| member | 178 |
179 | {
180 | "element": "member",
181 | "content": {
182 | "key": {
183 | "element": "string",
184 | "content": "foo"
185 | },
186 | "value": {
187 | "element": "string"
188 | }
189 | }
190 | }
191 | |
192 |
193 | Properties in JSON cannot be represented as standalone values. However, they exist as fragments of a JSON objects:
194 | "foo": ""195 | "foo": "Hey!"196 | |
197 |
| object | 200 |
201 | {
202 | "element": "object"
203 | }
204 | |
205 |
206 | {}
207 | {
208 | "foo": "Hey!"
209 | }
210 | {
211 | "bar": true
212 | }
213 | |
214 |
| enum | 217 |
218 | {
219 | "element": "enum",
220 | "attributes": {
221 | "enumerations": {
222 | "element": "array",
223 | "content": [
224 | {
225 | "element": "string"
226 | },
227 | {
228 | "element": "number"
229 | }
230 | ]
231 | }
232 | }
233 | }
234 | |
235 |
236 | -45.9237 | "Hello world!"238 | ""239 | 0240 | |
241 |
| select & option | 244 |
245 | {
246 | "element": "select",
247 | "content": [
248 | {
249 | "element": "option",
250 | "content": {
251 | "element": "string"
252 | }
253 | },
254 | {
255 | "element": "option",
256 | "content": {
257 | "element": "number"
258 | }
259 | }
260 | ]
261 | }
262 | |
263 |
264 | -45.9265 | "Hello world!"266 | ""267 | 0268 | |
269 |
| extend | 272 |
273 | {
274 | "element": "extend",
275 | "content": [
276 | {
277 | "element": "object",
278 | "content": [
279 | {
280 | "element": "member",
281 | "content": {
282 | "key": {
283 | "element": "string",
284 | "content": "foo"
285 | },
286 | "value": {
287 | "element": "string"
288 | }
289 | }
290 | },
291 | {
292 | "element": "member"
293 | "content": {
294 | "key": {
295 | "element": "string",
296 | "content": "bar"
297 | },
298 | "value": {
299 | "element": "number"
300 | }
301 | }
302 | }
303 | ]
304 | },
305 | {
306 | "element": "object",
307 | "content": [
308 | {
309 | "element": "member"
310 | "content": {
311 | "key": {
312 | "element": "string",
313 | "content": "baz"
314 | },
315 | "value": {
316 | "element": "boolean"
317 | }
318 | }
319 | }
320 | ]
321 | }
322 | ]
323 | }
324 | |
325 |
326 | {}
327 | {
328 | "foo": "Hey!"
329 | }
330 | {
331 | "bar": 42.3
332 | }
333 | {
334 | "foo": "Hello",
335 | "bar": 3.14,
336 | "baz": true
337 | }
338 | |
339 |
| ref | 344 |
345 | Given an named type such as
346 | {
347 | "element": "string",
348 | "meta": {
349 | "id": {
350 | "element": "string",
351 | "content": "SpecialString"
352 | }
353 | }
354 | }
355 | }
356 | A reference:
357 | {
358 | "element": "ref"
359 | "content": "MyString"
360 | }
361 | |
362 |
363 | ""364 | "abc"365 | "Hello world!"366 | |
367 |