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

Parsing with AMF

AMF can parse AML dialects 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:


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.