Skip to main content
Version: AMF v5.x.x

Parsing with AMF

AMF can parse AML dialects, JSON Schema (check supported drafts), and the following API specifications:

The following section explains the basics of parsing, and the example shows how to parse each specification in Scala, Java or Typescript.

Parsing Basics​

Parsing is the process of analyzing a sequence of tokens and then building a data structure from them.

AMF uses syntactic parsers such as SYAML to read a JSON or YAML file and generates an abstract syntax tree (AST) from the file, which is later used to generate a semantic graph that represents the model. This model can be either an API Contract Model (representing an API, independent of its specification), or an AML Document model (a Dialect, Vocabulary, or Dialect Instance).

Parsing returns a BaseUnit object, which is a graph of the model. Depending on the content in the parsed file, the BaseUnit object can be a Fragment, a Module, a Document or another type.

The following figure shows the parsing process:

parsing graph

A syntactic parser such as SYAML is used to generate an AST from a YAML/JSON file or a string.

AMF uses the AST to generate a semantic graph of the model, called BaseUnit. This BaseUnit will be used in the following stages of AMF (transformation, validation, rendering).

For more information about the AMF model, see the AMF model documentation resource.

info

We are working on incorporating ANTLR to AMF to support multiple syntactic parsers.

How to parse APIs​

To parse an API from the supported API specifications you need a specific or general AMFConfiguration, and the BaseUnitClient from that configuration.

You can use the following parsing methods:

  • If the API is a file use client.parse(path), providing the path to it
  • If the API is a string use client.parseContent(string, mediatype) providing the API as a string
  • the mediatype is an optional parameter, if it's not present AMF will try to guess it

Refer to the AMF Configuration and Client objects for more information on how to choose the configuration and client to use.

Parsing code examples​

The file paths you give the parser must have the following structure:

Windows:

  • Absolute path: file:///C:/testing/api.raml
  • Relative path: file://api.raml

MacOS and Unix:

  • Absolute path: file:///Users/aml/testing/api.raml
  • Relative path: file://api.raml

API Contract Model parsing​

The following code are examples on how to parse APIs (non GraphQL):


Code extracted from the examples GitHub repository.

AML parsing​

The following code are examples on how to parse AML Vocabularies, Dialects and Dialect Instances:

Before parsing an AML Dialect Instance, you must register its Dialect in the AMLConfiguration using its withDialect(path) function.


Code extracted from the examples GitHub repository.

JSON Schema​

The following code are examples on how to parse a JSON Schema:

For more information about JSON Schema support go to the JSON Schema section of the documentation.


Code extracted from the examples GitHub repository.

GraphQL​

The following code are examples on how to parse a GraphQL API:


Code extracted from the examples GitHub repository.