{"id":14155463,"url":"https://github.com/swagger-api/apidom","last_synced_at":"2026-01-17T12:44:16.864Z","repository":{"id":37035638,"uuid":"249737066","full_name":"swagger-api/apidom","owner":"swagger-api","description":"Semantic parser for API specifications","archived":false,"fork":false,"pushed_at":"2026-01-13T10:18:03.000Z","size":480053,"stargazers_count":93,"open_issues_count":15,"forks_count":20,"subscribers_count":6,"default_branch":"main","last_synced_at":"2026-01-13T11:39:34.391Z","etag":null,"topics":["ast","asyncapi","hacktoberfest","javascript","open-source","openapi","openapi3","openapi31","parser","swagger","swagger-oss"],"latest_commit_sha":null,"homepage":"https://swagger-api.github.io/apidom/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/swagger-api.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSES/AFL-3.0.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":".github/SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2020-03-24T14:55:51.000Z","updated_at":"2026-01-13T09:41:14.000Z","dependencies_parsed_at":"2023-10-24T00:32:40.124Z","dependency_job_id":"90bc5977-abc0-4acc-ad4b-0324e09b8670","html_url":"https://github.com/swagger-api/apidom","commit_stats":{"total_commits":4664,"total_committers":18,"mean_commits":259.1111111111111,"dds":0.5263722126929674,"last_synced_commit":"ecb560bd4aa61acfc2ed782ceb9e3707ce1c0d8d"},"previous_names":[],"tags_count":217,"template":false,"template_full_name":null,"purl":"pkg:github/swagger-api/apidom","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swagger-api%2Fapidom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swagger-api%2Fapidom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swagger-api%2Fapidom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swagger-api%2Fapidom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/swagger-api","download_url":"https://codeload.github.com/swagger-api/apidom/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swagger-api%2Fapidom/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28508548,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T11:50:55.898Z","status":"ssl_error","status_checked_at":"2026-01-17T11:50:55.569Z","response_time":85,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["ast","asyncapi","hacktoberfest","javascript","open-source","openapi","openapi3","openapi31","parser","swagger","swagger-oss"],"created_at":"2024-08-17T08:03:24.977Z","updated_at":"2026-01-17T12:44:16.831Z","avatar_url":"https://github.com/swagger-api.png","language":"TypeScript","readme":"[comment]: \u003c\u003e (SPDX-FileCopyrightText: Copyright \u0026#40;c\u0026#41; 2015 refractproject)\n[comment]: \u003c\u003e (SPDX-License-Identifier: MIT)\n\n[comment]: \u003c\u003e (SPDX-FileCopyrightText: Copyright \u0026#40;c\u0026#41; 2015 Apiary Inc.)\n[comment]: \u003c\u003e (SPDX-License-Identifier: MIT)\n\n# ApiDOM\n\n[![Build Status](https://github.com/swagger-api/apidom/actions/workflows/build.yml/badge.svg)](https://github.com/swagger-api/apidom/actions)\n[![Dependabot enabled](https://badgen.net/badge/icon/dependabot?icon=dependabot\u0026label)](https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically)\n\n\nThe purpose of ApiDOM is to provide a single, unifying structure for describing APIs across\nAPI description language and serialization formats. There currently exists several API description languages one can choose\nwhen defining an API, from OpenAPI, RAML, API Blueprint or others.\nThere are also many serialization formats such as XML, YAML or JSON. Without a way to parse these formats\nto the same structure, developers are required to handle each format one-by-one, each in a different\nway and each translating to their internal domain model. This is tedious, time-consuming,\nand requires each maintainer to stay in step with every format they support.\n\nApiDOM solves this complex problem in a simple way. It allows parsers to parse to a single structure\nand allows tool builders to consume one structure for all formats.\n\n## Table of Contents\n\n- [Getting started](#getting-started)\n  - [Prerequisites](#prerequisites)\n  - [Installation](#installation)\n  - [Usage](#usage)\n  - [ApiDOM Playground](#apidom-playground)\n- [Development](#development)\n  - [Prerequisites](#prerequisites)\n  - [Setting up](#setting-up)\n  - [Setting up via docker](#setting-up-via-docker)\n  - [Setting up via GitHub Codespaces](#setting-up-via-github-codespaces)\n  - [npm scripts](#npm-scripts)\n  - [Build artifacts](#build-artifacts)\n  - [Using this monorepo as a local dev dependency](#using-this-monorepo-as-a-local-dev-dependency)\n- [Contributing](#contributing)\n- [Documentation](#documentation)\n  - [What is an Element ?](#what-is-an-element-)\n  - [As a way to annotate JSON](#as-a-way-to-annotate-json)\n  - [As a unifying structure](#as-a-unifying-structure)\n  - [As a queryable structure](#as-a-queryable-structure)\n  - [ApiDOM stages](#apidom-stages)\n- [ApiDOM packages](#apidom-packages)\n  - [ApiDOM AST](#apidom-ast)\n  - [ApiDOM Core](#apidom-core)\n  - [Retrieving ApiDOM Elements](#retrieving-apidom-elements)\n  - [ApiDOM Namespaces](#apidom-namespaces)\n  - [ApiDOM Parsers](#apidom-parsers)\n  - [Advanced ApiDOM Manipulations](#advanced-apidom-manipulations)\n  - [ApiDOM Language Service](#apidom-language-service)\n- [License](#license)\n- [Software Bill Of Materials (SBOM)](#software-bill-of-materials-sbom)\n\n## Getting started\n\n### Prerequisites\n\nThese prerequisites are required both for installing ApiDOM as a npm package and local development setup.\n\n- [node-gyp](https://www.npmjs.com/package/node-gyp) `\u003e=10` with [Python 3.x](https://www.python.org/downloads/)\n- [GLIBC](https://www.gnu.org/software/libc/) `\u003e=2.29`\n- [GCC compiler](https://gcc.gnu.org/)\n- [emscripten](https://emscripten.org/docs/getting_started/downloads.html) or [docker](https://www.docker.com/) needs to be installed, we recommend going with a docker option\n\n### Installation\n\nAssuming [prerequisites](#prerequisites) are already installed, ApiDOM npm packages are installable and works with `Node.js \u003e=12.20.0 \u003c=22`.\n\nYou can install ApiDOM packages using [npm CLI](https://docs.npmjs.com/cli):\n\n```sh\n $ npm install @swagger-api/apidom-ast\n $ npm install @swagger-api/apidom-converter\n $ npm install @swagger-api/apidom-core\n $ npm install @swagger-api/apidom-error\n $ npm install @swagger-api/apidom-json-path\n $ npm install @swagger-api/apidom-json-pointer\n $ npm install @swagger-api/apidom-json-pointer-relative\n $ npm install @swagger-api/apidom-logging\n $ npm install @swagger-api/apidom-ls\n $ npm install @swagger-api/apidom-ns-api-design-systems\n $ npm install @swagger-api/apidom-ns-arazzo-1\n $ npm install @swagger-api/apidom-ns-asyncapi-2\n $ npm install @swagger-api/apidom-ns-json-schema-2019-09\n $ npm install @swagger-api/apidom-ns-json-schema-2020-12\n $ npm install @swagger-api/apidom-ns-json-schema-draft-4\n $ npm install @swagger-api/apidom-ns-json-schema-draft-6\n $ npm install @swagger-api/apidom-ns-json-schema-draft-7\n $ npm install @swagger-api/apidom-ns-openapi-2\n $ npm install @swagger-api/apidom-ns-openapi-3-0\n $ npm install @swagger-api/apidom-ns-openapi-3-1\n $ npm install @swagger-api/apidom-parser\n $ npm install @swagger-api/apidom-parser-adapter-api-design-systems-json\n $ npm install @swagger-api/apidom-parser-adapter-api-design-systems-yaml\n $ npm install @swagger-api/apidom-parser-adapter-arazzo-json-1\n $ npm install @swagger-api/apidom-parser-adapter-arazzo-yaml-1\n $ npm install @swagger-api/apidom-parser-adapter-asyncapi-json-2\n $ npm install @swagger-api/apidom-parser-adapter-asyncapi-yaml-2\n $ npm install @swagger-api/apidom-parser-adapter-asyncapi-json-3\n $ npm install @swagger-api/apidom-parser-adapter-asyncapi-yaml-3\n $ npm install @swagger-api/apidom-parser-adapter-json\n $ npm install @swagger-api/apidom-parser-adapter-json-schema-json-2020-12\n $ npm install @swagger-api/apidom-parser-adapter-json-schema-yaml-2020-12\n $ npm install @swagger-api/apidom-parser-adapter-openapi-json-2\n $ npm install @swagger-api/apidom-parser-adapter-openapi-json-3-0\n $ npm install @swagger-api/apidom-parser-adapter-openapi-json-3-1\n $ npm install @swagger-api/apidom-parser-adapter-openapi-yaml-2\n $ npm install @swagger-api/apidom-parser-adapter-openapi-yaml-3-0\n $ npm install @swagger-api/apidom-parser-adapter-openapi-yaml-3-1\n $ npm install @swagger-api/apidom-parser-adapter-yaml-1-2\n $ npm install @swagger-api/apidom-reference\n```\n\n### Usage\n\nEvery package of the monorepo has an associated README file demonstrating its purpose and containing\nusage examples. An overview of available packages is provided in the [ApiDOM packages](#apidom-packages) section.\n\n### ApiDOM Playground\n\nApiDOM Playground is a React application that runs in a browser and can visually demonstrate capabilities\nof the ApiDOM. ApiDOM Playground is build and deployed whenever the new commit lands on `main` branch.\n\n![image](https://user-images.githubusercontent.com/193286/145010522-5d85e34b-8d28-4a07-9ee2-b28807a013cd.png)\n\nApiDOM Playground is available at [https://swagger-api.github.io/apidom/](https://swagger-api.github.io/apidom/)\n\n## Development\n\nThis is a monorepo for all ApiDOM packages. All the code is written in [TypeScript](https://www.typescriptlang.org/).\nAll the information necessary for working with monorepo can be found in this [article](https://vladimirgorej.com/blog/things-i-have-learned-maintaining-javascript-monorepo-with-lerna/).\n\nAssuming [prerequisites](#prerequisites) are already installed, [Node.js](https://nodejs.org/) `\u003e=22.14.0` and `npm \u003e=10.9.2`\nare the minimum required versions that this repo runs on, but we recommend using the latest version of Node.js@22.\n\n### Setting up\n\nRun the following commands to setup the repository for local development:\n\n```shell\n $ git clone https://github.com/swagger-api/apidom.git\n $ cd apidom\n $ npm i\n $ npm run build\n```\n\n### Setting up via docker\n\nThere are situations, when satisfying all the **prerequisites** of this repository on you local\ndevelopment machine is just not possible. In that case, you can use **docker** to get around it.\nRepository directory is mounted as volume inside a running container called `apidom-dev`.\nThat way you can edit code locally on your development machine and run **npm scripts**\ninside the `apidom-dev` docker container.\n\n**Build the ApiDOM docker image:**\n\n```sh\n $ git clone https://github.com/swagger-api/apidom.git\n $ cd apidom\n $ docker-compose up\n```\n\n**Install dependencies and build ApiDOM inside the docker container:**\n\n```sh\n$ docker exec -it apidom-dev npm i --verbose\n$ docker exec -it apidom-dev npm run build\n```\n\n**Run npm scripts inside the docker container:**\n\n```sh\n$ docker exec -it apidom-dev npm run test\n```\n\n\u003e Note: monorepo needs to be build in order for monorepo package topology to work correctly.\n\n### Setting up via GitHub Codespaces\n\nThis repository is [configured](https://github.com/swagger-api/apidom/tree/main/.devcontainer) to work with [GitHub Codespaces](https://github.com/codespaces).\nCreate a new codespace by picking this repository from the list of available repositories.\nOnce the codespace is created, run following commands inside the codespace terminal:\n\n```sh\n $ npm i\n $ npm run build\n```\n\n### npm scripts\n\nSome npm scripts run in parallel. Default maximum parallelization is set `2`. This is due to the fact\nthat our `CI` runs on GitHub Actions which uses GitHub hosted runners with [2-core CPUs](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources).\nIf you have computer with more than 2 CPU cores, you can speed running npm scripts by\ncreating an environment variable called `CPU_CORES` and assign it a number of your CPU cores.\n\nAssuming 4 CPU cores are available:\n\n```sh\n  $ export CPU_CORES=4\n  $ npm run build\n```\n\n`build` scripts now runs much faster than before.\n\n**Build artifacts**\n\n```sh\n $ npm run build\n```\n\n**Test**\n\nYou must first **build the artifacts** before running tests.\n\n```sh\n $ npm run test\n```\n\n**Lint**\n\n```sh\n $ npm run lint\n```\n\n**Check TypeScript types**\n\n```sh\n $ npm run typescript:check-types\n```\n\n**Generate TypeScript types**\n\n```sh\n $ npm run typescript:declaration\n```\n\n**Clean**\n\n```sh\n $ npm run clean\n```\n\n### Build artifacts\n\nAll the packages have identical build system and expose build artifacts in identical way.\nAfter building artifacts, every package will contain five (5) additional directories.\nAll the build artifacts are polymorphic - they can run in different environments like [Web Browser](https://en.wikipedia.org/wiki/Web_browser), [Node.js](https://nodejs.org/) or [Web Worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API).\n\n***.cjs**\n\nThese files are generated inside `src/` directory.\nContain ES5 compatible code with [CommonJS](https://en.wikipedia.org/wiki/CommonJS) style imports.\nThese build fragments are ideal for legacy [Node.js](https://nodejs.org/) and similar environments.\n\n***.mjs**\n\nThese files are generated inside `src/` directory.\nContain ES5 compatible code with [ES6 imports](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import).\nThese build fragments are ideal for modern [Node.js](https://nodejs.org/),\nbundling with [Webpack](https://webpack.js.org/) or similar bundlers.\n\n**dist/**\n\nThis directory contains bundled build fragments that use [UMD](https://github.com/umdjs/umd) modules.\nThey're ideal for browser usage. The fragments are both in minified and un-minified form.\n\n**types/**\n\nTypeScript types generated from the source code.\n\n### Using this monorepo as a local dev dependency\n\nFor using this monorepo as a local dev dependency for `dependent project`,\nfollowing commands needs to be issued inside the monorepo directory after\nit has been cloned to a local filesystem:\n\n```sh\n $ npm i\n $ npm run build\n $ npm run link\n```\nThis will install the dependencies, built the monorepo and link all it's packages to\nglobal `node_modules`.\n\n#### Usage in `dependent project`\n\nNow that we have monorepo packages globally linked we can use them in `dependent project`.\nLet's say `dependent project` needs to directly use following packages:\n\n- @swagger-api/apidom-ast\n- @swagger-api/apidom-core\n\nIssuing following command from inside the `dependent project` will link these packages:\n\n```sh\n $ npm link @swagger-api/apidom-ast @swagger-api/apidom-core\n```\n\nIf more packages (or all of them) need to be used in `dependent project`, they need to be explicitly\nenumerated using above command and separated by single empty space.\n\nNotice that we link packages using single `npm link` command. This is necessary\nbecause of how `npm link` works internally. Always use single `npm link` command with\nmultiple package names as argument.\n\n**Don't ever do this!**\n\n```sh\n $ npm link @swagger-api/apidom-ast\n $ npm link @swagger-api/apidom-core\n```\n\n\u003e Setting up npm script in `dependent project` can help keep things DRY.\n\n#### Cleaning up\n\n##### Dependent project\n\nThe best way to unlink monorepo packages from `dependent project` is to run following command\ninside the `dependent project`:\n\n```shell\n $ npm i\n```\n\nRunning `npm i` will remove the links to monorepo packages and install the packages from npm registry.\n\n\u003e Note: running `npm unlink \u003cpackage-name\u003e` in `dependent project` will remove the link to monorepo package,\nbut will leave the `dependent project` node_modules in corrupted state as there is no version of the package\ninstalled anymore. Running `npm i` is always a prefered way to restore your node_modules to original state.\n\n\n##### ApiDOM monorepo\n\nIt is not necessary to unlink monorepo packages from global `node_modules`. But if you\nwant to keep your global `node_modules` tidy you can run the following command in monorepo directory:\n\n```shell\n $ npm run unlink\n```\n\nRunning above npm script will unlink all monorepo packages from global `node_modules`.\n\nIf you want to just unlink particular monorepo packages, you have to enumerate them explicitly:\n\n```shell\n $ npm unlink --global @swagger-api/apidom-ast @swagger-api/apidom-core\n```\n\n## Contributing\n\nThis project uses [swagger-api](https://github.com/swagger-api) GitHub organizations contributing guide.\nYou can obtain copy of this contributing guide at [https://github.com/swagger-api/.github/blob/master/CONTRIBUTING.md](https://github.com/swagger-api/.github/blob/master/CONTRIBUTING.md).\nRead our contributing guide to learn about our development process, how to propose bugfixes and improvements,\nand how to build and test your changes to ApiDOM.\n\n## Documentation\n\nIf there is one thing API description languages have taught us, it is that a single contract provides\nthe best and fastest way to design and iterate on an API. Developers building the API can move independently\nas they progress towards the defined contract found in the OpenAPI or RAML document.\nConversely, API consumers can build tools for consuming the API based on the API definition document.\n\nThis same pattern has proven to be just as valuable for building API description languages and tooling.\nApiDOM is the contract for producing and consuming the many API description languages and serialization formats\nand allows everyone to move quickly and independently.\n\n### What is an Element ?\n\nApiDOM is made up of many small elements that have a rich semantic meaning given their value and context.\nAn element is an individual piece that makes up an API, and can range from defining a resource to providing\nan example of an HTTP request.\n\nThe ApiDOM defines elements to be used for:\n\nDescribing an API\nDescribing data structures used within that API\nDescribing parse results when parsing API-related documents\nThese elements also seek to provide a way to decouple APIs and their semantics from the implementation details.\n\nThe structure of an ApiDOM is recursive by nature. When looking for specific elements,\nit is best to traverse the ApiDOM tree to look for a match. Querying the ApiDOM tree will\ndecouple our code from specific API description language. Also, it decouples our code from the\nspecific structure of these documents as long as they are semantically equivalent.\n\n### As a way to annotate JSON\n\nApiDOM provides the ability to take a normal JSON structure and add a layer on top of it for the purpose\nof annotating and adding semantic data. Instead of creating an entirely different structure to describe the data,\nApiDOM's approach is to expand the existing structure (we call it \"refracting\" a structure).\nHere is an example to show our point.\n\nTake the following simple JSON object.\n\n```json\n{\n  \"name\": \"John Doe\",\n  \"email\": \"john@example.com\"\n}\n```\n\nUsing ApiDOM, we can expand this out and add some human-readable titles and descriptions.\n\n```json\n{\n  \"element\": \"object\",\n  \"content\": [\n    {\n      \"element\": \"member\",\n      \"meta\": {\n        \"title\": \"Name\",\n        \"description\": \"Name of a person\"\n      },\n      \"content\": {\n        \"key\": {\n          \"element\": \"string\",\n          \"content\": \"name\"\n        },\n        \"value\": {\n          \"element\": \"string\",\n          \"content\": \"John Doe\"\n        }\n      }\n    },\n    {\n      \"element\": \"member\",\n      \"meta\": {\n        \"title\": \"Email\",\n        \"description\": \"Email address for the person\"\n      },\n      \"content\": {\n        \"key\": {\n          \"element\": \"string\",\n          \"content\": \"email\"\n        },\n        \"value\": {\n          \"element\": \"string\",\n          \"content\": \"john@example.com\"\n        }\n      }\n    }\n  ]\n}\n```\n\nWe added some semantic data to the existing data, but we did so while retaining the semantic structure of the data\nwith the object and string elements. **This means there is no semantic difference in the ApiDOM structure and\nthe original JSON structure**. It also means we can add extra semantics on top of these structural ones.\n\n### As a unifying structure\n\nYou may have noticed the similarities between the JSON example above and XML.\nXML has elements, attributes, and content. It would be a good question to ask if we simply turned JSON into XML.\n\nApiDOM is actually meant to provide these cross-format similarities. It means that a JSON structure\nmay be refracted and converted to XML. It also means an XML document may be converted into ApiDOM.\nThis also goes for YAML, HTML, CSV, and many other formats. ApiDOM is a way to use refracting to unify these structures.\n\nLet's look at another example, this time refacting XML with ApiDOM.\n\n```xml\n\u003cperson name=\"John Doe\" email=\"john@example.com\"\u003e\u003c/person\u003e\n```\n\nThis example in refracted form would look like the following snippet. Notice that we're using attributes in resulting ApiDOM structure.\n\n```json\n{\n  \"element\": \"person\",\n  \"attributes\": {\n    \"name\": {\n      \"element\": \"string\",\n      \"content\": \"John Doe\"\n    },\n    \"email\": {\n      \"element\": \"string\",\n      \"content\": \"john@example.com\"\n    }\n  }\n}\n```\n\nSince we can go back and forth between JSON, YAML, XML, and other formats, we are now able to use same toolset across the different formats.\nThat means we could use XSLT to transform JSON documents.\n\n### As a queryable structure\n\nApiDOM is meant to free us from the structure of our documents, similar to how XML does with things\nlike XPATH or the DOM. It means we can now query JSON documents as if there was an underlying DOM,\nwhich decouples our SDK from our structure and our structure from our data.\n\n### ApiDOM stages\n\nThere are three stages to ApiDOM\n\n- Parse stage\n- Refract stage\n- Generate stage\n\n\n#### Parse stage\n\nThe parse stage takes JSON string and produces ApiDOM structure using the base ApiDOM namespace. There are two phases of parsing:\n\n- Lexical Analysis phase\n- Syntactic Analysis phase\n\n\n##### Lexical Analysis phase\n\nLexical Analysis will take a JSON string and turn it into a stream of tokens. tree-sitter / web-tree-sitter is used\nas an underlying lexical analyzer.\n\n##### Syntactic Analysis\n\nSyntactic Analysis will take a stream of tokens and turn it into an ApiDOM representation.\nCST produced by lexical analysis is syntactically analyzed, and ApiDOM structure using base (generic) ApiDOM namespace is produced.\nSyntactic analysis can further be direct or indirect. JSON parser has both direct and indirect syntactical analyzers,\nbut YAML parser only has an indirect one.\n\n###### Direct Syntactical analysis\n\nThis analysis directly turns tree-sitter CST into ApiDOM. Single traversal is required, which makes it super performant,\nand it's the default analysis used.\n\n###### Indirect Syntactic analysis\n\nThis analysis turns trees-sitter CST into JSON AST representation. Then JSON AST is turned into ApiDOM.\nTwo traversals are required, which makes the indirect analysis less performant than the direct one.\nThough less performant, having JSON AST representation allows us to do further complex analysis.\n\n#### Refract stage\n\nThe refract stage takes a generic ApiDOM structure (base namespace) and traverses through it, adding, updating,\nand removing nodes as it goes along and turning it into semantic ApiDOM structure (like OpenAPI or AsyncAPI).\nThis is by far the most complex part of ApiDOM. This is where plugins operate.\nIf plugins are used, additional traversal is currently needed.\n\n#### Generate stage\n\nWe can generate JSON/YAML documents from the ApiDOM structure.\nIt doesn't matter if the original document was originally defined in JSON or YAML.\nGenerated JSON/YAML documented will have exactly the same semantic information as the original one,\nbut the style information from the original document is not preserved (white spaces/comments, etc..).\n\n```mermaid\nflowchart TD\n  %% Input node\n  In[\"JSON/YAML string\"]\n\n  %%--- Parse Stage and internals\n  subgraph Parse_Stage[\"Parse Stage\"]\n    P1[\"Lexical Analysis\u003cbr/\u003eJSON/YAML → CST\"]\n    SA[\"Syntactic Analysis\"]\n    SA1[\"Direct\u003cbr/\u003e*CST → Generic ApiDOM*\"]\n    SA2[\"Indirect\u003cbr/\u003e*CST → JSON AST → Generic ApiDOM*\"]\n\n    P1 --\u003e SA\n    SA --\u003e SA1\n    SA --\u003e SA2\n  end\n\n  %%--- Refract Stage\n  subgraph Refract_Stage[\"Refract Stage\"]\n    R[\"Generic ApiDOM + plugins → Semantic ApiDOM\"]\n  end\n\n  %%--- Generate Stage\n  subgraph Generate_Stage[\"Generate Stage\"]\n    G[\"Generate JSON/YAML output\u003cbr/\u003e(style info lost)\"]\n  end\n\n  %% Output node\n  Out[\"JSON/YAML string\"]\n\n  %%--- Connections\n  In --\u003e Parse_Stage\n  Parse_Stage --\u003e Refract_Stage\n  Refract_Stage --\u003e Generate_Stage\n  Generate_Stage --\u003e Out\n```\n\n---\n\nHaving said that, this is how JSON OpenAPI 3.1 document gets transformed into ApiDOM:\n\n\n**with direct syntactic analysis (requires 2 traversals)**\n```\nJSON string -\u003e tree-sitter CST -\u003e  generic ApiDOM -\u003e OpenAPI 3.1 ApiDOM\n```\n\n**with indirect syntactic analysis (requires 3 traversals)**\n```\nJSON string -\u003e tree-sitter CST -\u003e JSON AST -\u003e generic ApiDOM -\u003e OpenAPI 3.1 ApiDOM\n```\n\n**with direct syntactic analysis and additional plugins (requires 3 traversal)**\n```\nJSON string -\u003e tree-sitter CST -\u003e generic ApiDOM -\u003e OpenAPI 3.1 ApiDOM -\u003e plugins -\u003e OpenAPI 3.1 ApiDOM\n```\n---\n\nThis very closely reflects how [Babel](https://github.com/babel/babel) works ([Babel Plugin Handbook](https://github.com/jamiebuilds/babel-handbook/blob/master/translations/en/plugin-handbook.md)).\nTheir transform phase is our refract phase. The only difference is that when plugins are involved, our transform phase\nrequires 2 traversals instead of a single one. We can find a way in the future how to fold these 2 traversals into a single one.\n\n## ApiDOM packages\n\n### ApiDOM AST\n\n[@swagger-api/apidom-ast](https://github.com/swagger-api/apidom/tree/main/packages/apidom-ast) contains tools necessary for [syntactic analysis](#syntactic-analysis), which will take a stream of tokens and turn it into an AST representation. The AST represents the structure of input string in a way that makes it easier to work with. The package contains AST nodes for JSON and YAML 1.2 formats and comes with its own traversal algorithm convenient for traversing CST or AST.\n\n### ApiDOM Core\n\n[@swagger-api/apidom-core](https://github.com/swagger-api/apidom/tree/main/packages/apidom-core) is a package that contains tools for manipulating ApiDOM structures. It provides a base ApiDOM namespace, predicates for all primitive and base namespace elements, and algorithms for transforming and handling ApiDOM structures. The available algorithms allow for transcluding, merging, copying, traversing and transforming ApiDOM structures into its different forms.\n\n### Retrieving ApiDOM Elements\n\nIt is possible to evaluate [JSON Pointer](https://github.com/swagger-api/apidom/tree/main/packages/apidom-json-pointer), [Relative JSON Pointer](https://github.com/swagger-api/apidom/tree/main/packages/apidom-json-pointer-relative) and [JSONPath expressions](https://github.com/swagger-api/apidom/tree/main/packages/apidom-json-path) against ApiDOM structures. A successful evaluation returns the corresponding ApiDOM Element at the specified location.\n\n### ApiDOM Namespaces\n\nThe namespace packages provide ApiDOM namespaces for specifications, consisiting of a number of elements implemented on top of primitive ones. The refractor layer in each namespace allows to transform JavaScript structures or generic ApiDOM into elements from that specific namespace. The elements can be traversed using the `visit` function provided by [apidom-core](https://github.com/swagger-api/apidom/tree/main/packages/apidom-core) package.\n\nAvailable namespaces:\n\n- [API Design Systems](https://github.com/swagger-api/apidom/tree/main/packages/apidom-ns-api-design-systems)\n- [Arazzo 1.0.1](https://github.com/swagger-api/apidom/tree/main/packages/apidom-ns-arazzo-1)\n- [AsyncAPI 2.x.y](https://github.com/swagger-api/apidom/tree/main/packages/apidom-ns-asyncapi-2)\n- [JSON Schema Draft 4/5](https://github.com/swagger-api/apidom/tree/main/packages/apidom-ns-json-schema-draft-4)\n- [JSON Schema Draft 6](https://github.com/swagger-api/apidom/tree/main/packages/apidom-ns-json-schema-draft-6)\n- [JSON Schema Draft 7](https://github.com/swagger-api/apidom/tree/main/packages/apidom-ns-json-schema-draft-7)\n- [JSON Schema 2019-09](https://github.com/swagger-api/apidom/tree/main/packages/apidom-ns-json-schema-2019-09)\n- [JSON Schema 2020-12](https://github.com/swagger-api/apidom/tree/main/packages/apidom-ns-json-schema-2020-12)\n- [OpenAPI 2.0](https://github.com/swagger-api/apidom/tree/main/packages/apidom-ns-openapi-2)\n- [OpenAPI 3.0.x](https://github.com/swagger-api/apidom/tree/main/packages/apidom-ns-openapi-3-0)\n- [OpenAPI 3.1.0](https://github.com/swagger-api/apidom/tree/main/packages/apidom-ns-openapi-3-1)\n\n### ApiDOM Parsers\n\nThe parser packages provide parser adapters for specifications in JSON and YAML formats, allowing to transform them into generic ApiDOM or specific ApiDOM namespace.\n\nThe base parser adapters support [JSON](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser-adapter-json) and [YAML 1.2](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser-adapter-yaml-1-2) formats. They are responsible for [lexical and syntactic analysis](#parse-stage), transforming the provided string into a generic ApiDOM structure. These base adapters are extended in parser adapters for specifications, enabling parsing of definitions directly into the ApiDOM namespaces for those specifications.\n\nAvailable parser adapters for ApiDOM namespaces:\n\n- API Design Systems - [JSON](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser-adapter-api-design-systems-json) / [YAML](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser-adapter-api-design-systems-yaml)\n- Arazzo 1.0.1 - [JSON](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser-adapter-arazzo-json-1) / [YAML](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser-adapter-arazzo-yaml-1)\n- AsyncAPI 2.x.y - [JSON](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser-adapter-asyncapi-json-2) / [YAML](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser-adapter-asyncapi-yaml-2)\n- AsyncAPI 3.x.y - [JSON](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser-adapter-asyncapi-json-3) / [YAML](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser-adapter-asyncapi-yaml-3)\n- JSON Schema 2020-12 - [JSON](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser-adapter-json-schema-json-2020-12) / [YAML](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser-adapter-json-schema-yaml-2020-12)\n- OpenAPI 2.0 - [JSON](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser-adapter-openapi-json-2) / [YAML](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser-adapter-openapi-yaml-2)\n- OpenAPI 3.0.x - [JSON](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser-adapter-openapi-json-3-0) / [YAML](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser-adapter-openapi-yaml-3-0)\n- OpenAPI 3.1.0 - [JSON](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser-adapter-openapi-json-3-1) / [YAML](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser-adapter-openapi-yaml-3-1)\n\n[@swagger-api/apidom-parser](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser) consumes any parser adapter with compatible shape and provides a unified API for parsing. It contains logic of mapping a source string to appropriate media type and a source string with media type to appropriate ApiDOM namespace.\n\n### Advanced ApiDOM manipulations\n\n[@swagger-api/apidom-reference](https://github.com/swagger-api/apidom/tree/main/packages/apidom-reference) provides algorithms for semantic ApiDOM manipulations. It contains components enabling parsing, resolving, dereferencing and bundling.\n\nThe [parse component](https://github.com/swagger-api/apidom/tree/main/packages/apidom-reference#parse-component) implements the default parser plugins, enabling parsing for files located on local filesystems and on the internet. It can parse provided definitions into generic ApiDOM structure or into one of the ApiDOM namespaces.\n\nAvailable parse strategies:\n\n- JSON format\n- YAML 1.2 format\n- Binary format\n- ApiDOM - JSON\n- API Design Systems - JSON / YAML\n- Arazzo 1.0.1 - JSON / YAML\n- AsyncAPI 2.x.y - JSON / YAML\n- OpenAPI 2.0 - JSON / YAML\n- OpenAPI 3.0.x - JSON / YAML\n- OpenAPI 3.1.0 - JSON / YAML\n\nThe [resolve component](https://github.com/swagger-api/apidom/tree/main/packages/apidom-reference#resolve-component) provides file resolution and external resolution sub-components. File resolution contains plugins allowing to read files located on local filesystem and on the internet, and provide their content. External resolution resolves external dependencies of a document using a specific external resolution strategy, providing a set of resolved references as a result.\n\nAvailable external resolution strategies:\n\n- ApiDOM\n- AsyncAPI 2.x.y\n- OpenAPI 2.0\n- OpenAPI 3.0.x\n- OpenAPI 3.1.0\n\nThe [dereference component](https://github.com/swagger-api/apidom/tree/main/packages/apidom-reference#dereference-component) transcludes referencing elements (internal or external) with referenced elements, using a specific dereference strategy.\n\nAvailable dereference strategies:\n\n- ApiDOM\n- AsyncAPI 2.x.y\n- OpenAPI 2.0\n- OpenAPI 3.0.x\n- OpenAPI 3.1.0\n\nThe [bundle component](https://github.com/swagger-api/apidom/tree/main/packages/apidom-reference#bundle-component) allows to package up resources spread across multiple files in a single file (Compound Document) using a specific bundle strategy.\n\nAvailable bundle strategies:\n\n- OpenAPI 3.1.0\n\n### ApiDOM Language Service\n\n[ApiDOM Language Service](https://github.com/swagger-api/apidom/tree/main/packages/apidom-ls) provides language processing for ApiDOM supported languages for editing experience. It adheres to the LSP Protocol and can therefore be used via LSP Server wrapper, providing editing capabilities to various editors and IDEs. It provides validation, documentation, definitions, completion, semantic highlighting and dereferencing for supported specifications.\n\nApiDOM Language Service supports:\n\n- AsyncAPI 2.x.y\n- OpenAPI 2.0\n- OpenAPI 3.0.x\n- OpenAPI 3.1.0\n\n## License\n\nApiDOM is licensed under [Apache 2.0 license](https://github.com/swagger-api/apidom/blob/main/LICENSES/Apache-2.0.txt).\nApiDOM comes with an explicit [NOTICE](https://github.com/swagger-api/apidom/blob/main/NOTICE) file\ncontaining additional legal notices and information.\n\nThis project uses [REUSE specification](https://reuse.software/spec/) that defines a standardized method\nfor declaring copyright and licensing for software projects.\n\n## Software Bill Of Materials (SBOM)\n\nSoftware Bill Of materials is available in this repository [dependency graph](https://github.com/swagger-api/apidom/network/dependencies).\nClick on `Export SBOM` button to download the SBOM in [SPDX format](https://spdx.dev/).\n\n","funding_links":[],"categories":["open-source"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswagger-api%2Fapidom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fswagger-api%2Fapidom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswagger-api%2Fapidom/lists"}