This tutorial shows you how to define and edit reusable, modular metadata documents that can be linked together as a graph of metadata using AML.
- JVM: version 7 or higher
- SBT to build the AMF command-line
You can download the example from the AML project examples repository in Github.
This tutorial assumes you have a working version of the AMF command-line as described in the quickstart tutorial.
In this tutorial, you will split a stand-alone, monolithic AML metadata document into a set of modular documents that can be edited, published and linked independently.
We will start with the initial version of the dialect, found in
aml/modular/dialect/database_configuration.yaml, a very simple AML Dialect describing configuration metadata file with information to connect to different databases.
This AML dialect uses two vocabularies, one to describe infrastructure, and the other to describe configurations. Both are located in
Since this AML dialect defines a single, monolithic type of document, the
documents section of the dialect includes only a
root entry encoding the root node of the document.
Using this dialect definition, we can edit standalone configuration documents, like the configuration document located at
In many situations, entities defined in a document can be reused in multiple documents. AML allows you to define reusable entities in their own independent metadata documents, known as fragments, that can be linked from all these documents. The graph of information parsed from all these documents will point to the same node URI in the generated metadata graph.
To declare a fragment, the
documents section of the AML dialect must include a
fragments entry with a mapping from the name of the fragment to the node encoded in the fragment.
Version 1.1 of the DB Config dialect introduces a fragment to declare databases servers. It can be found in the
In this case, we define a fragment named
DatabaseServer encoding a
With this dialect definition, we can create fragments declaring metadata about database servers with the semantics of the
Infrastructure vocabulary, for example in the
These fragments can be linked from the configuration document, using the
!include linking directive:
Another common use case is to define related collections of metadata entities that can be reused across different documents.
AML supports these modular collections through the definition of metadata libraries.
Libraries are defined in the
documents section using the
libraries property. This node keeps a map of declarations for the library, including name of the declaration and type of declared nodes.
The version 1.2 of the
DB Config dialect, located at
aml/modular/dialect/database_configuration_3.yaml includes the declaration of libraries of servers:
After these dialect definitions, metadata documents containing libraries of servers can be defined, like the one located at
These libraries can be referenced from configuration document using library reference aliases, as in
Instead of library reference aliases,
$ref linking directives can also be used, as shown in this example JSON representation of the same metadata:
AMF can be used to parse modular metadata documents containing links.
By default, AMF will produce a JSON-LD document encoding a graph that explicitly links documents using the
doc:link-target property. Linked documents will be eagerly followed and added to the
Different types of documents in the graph will be marked with different semantics.
- Fragments will be marked with the
- Libraries will be marked with the
For example, to parse version 1.1 of the database document using a fragment, AMF can be used:
Sometimes, we want to work with the final graph of metadata in which all explicit links have been replaced by standard JSON-LD links. In the process, all the
doc:references relationships disappear and a single unit is generated. This process is known as
resolution in AMF.
You can trigger the resolution process in AMF programmatically or by passing the
--resolve true argument to the command line tool: