Quickstart#

This tutorial covers installing all the tools you'll need to design metadata documents with AML and shows you how to get up and running quickly.

Before you begin#

Prerequisites:

  • JVM: version 7 or higher
  • SBT to build the AMF command-line

Download the example#

You can download the example from the AML project examples repository in Github.

git clone https://github.com/aml-org/examples.git
cd examples

Build and install the AMF command-line tool#

Download AMF from its github repository and build AMF command-line (you will need Scala SBT):

git clone https://github.com/aml-org/amf.git
cd amf
sbt buildCommandLine

This will leave a versioned fat jar (amf-X.Y.Z-SNAPSHOT.jar) in the top-level repository of the project. Copy this jar file to the top-level of the examples repository:

cp ./amf-X.Y.Z-SNAPSHOT.jar ../examples/amf.jar

Defining an AML Dialect for a new type of metadata documents#

In this example we will define a new type of metadata document to exchange information about geographical locations.

First, we will define a new type of AML Dialect describing the structure of the document, located in the examples repository in the file aml/quickstart/dialects/places.yaml:

places.yaml

#%Dialect 1.0
dialect: Places
version: 1.0
external:
schema: http://schema.org/
nodeMappings:
LocationNode:
classTerm: schema.Place
mapping:
name:
propertyTerm: schema.name
mandatory: true
range: string
image:
propertyTerm: schema.image
range: uri
documents:
root:
encodes: LocationNode

The dialect is very simple. It just defines a document with a couple of nodes: one for the place, and the other for an image of the place. We are using the Schema.org vocabulary to provide the semantics of the metadata.

You can check the validity of this AML Dialect using AMF. From the top-level directory of the examples repository:

examples [master] $ java -jar amf.jar validate -in "AML 1.0" -mime-in application/yaml file://aml/quickstart/dialects/places.yaml
{
"@type": "http://www.w3.org/ns/shacl#ValidationReport",
"http://www.w3.org/ns/shacl#conforms": true
}

Parsing metadata documents#

Having a valid AML Dialect, we can start using it to parse metadata documents with information about different places.

For example, we can try the golden_gate.yaml document:

golden_gate.yaml

#%Places 1.0
name: Golden Gate
image: https://en.wikipedia.org/wiki/Golden_Gate#/media/File:Golden_Gate_1.jpg

We can use AMF to parse and validate the example, passing as an argument the location of the dialect and dialect instance to be parsed:

examples [master] $ java -jar amf.jar parse -ds file://aml/quickstart/dialects/places.yaml -in "AML 1.0" -mime-in application/yaml -ctx true file://aml/quickstart/golden_gate.yaml

The following JSON-LD document will be returned in the console:

[
{
"@id": "#",
"@type": [
"meta:DialectInstance",
"doc:Document",
"doc:Fragment",
"doc:Module",
"doc:Unit"
],
"meta:definedBy": [
{
"@id": "file://aml/quickstart/dialects/places.yaml#"
}
],
"doc:encodes": [
{
"@id": "#/",
"@type": [
"schema-org:Place",
"file://aml/quickstart/dialects/places.yaml#/declarations/LocationNode",
"meta:DialectDomainElement",
"doc:DomainElement"
],
"schema-org:image": [
{
"@id": "https://en.wikipedia.org/wiki/Golden_Gate#/media/File:Golden_Gate_1.jpg"
}
],
"schema-org:name": [
{
"@value": "Golden Gate"
}
]
}
],
"@context": {
"@base": "file://aml/quickstart/golden_gate.yaml",
"doc": "http://a.ml/vocabularies/document#",
"meta": "http://a.ml/vocabularies/meta#",
"schema-org": "http://schema.org/"
}
}
]

JSON-LD is a W3C standard to store graphs of information with support for hyperlinks. JSON-LD is the native format for AMF-parsed graph models.

Using vocabularies for custom semantics#

AML allows users to define the semantics for metadata documents in AML Vocabulary files.

The file aml/quickstart/geolocation.yaml contains a vocabulary defining a few terms for a custom geolocation vocabulary:

geolocation.yaml

#%Vocabulary 1.0
vocabulary: Geolocation
base: http://myorg.com/vocabs/geo#
classTerms:
Point:
description: Single coordinate pair
Line:
description: Pair of points
Polygon:
description: contains at least 4 coordinate points
propertyTerms:
position:
description: Geolocation of an element
range: Point
latitude:
description: Geographical latitude
longitude:
description: Geographical longitude

We could modify our dialect to generate a new version that uses the AML Vocabulary for geolocation we have just reviewed:

places_2.yaml

#%Dialect 1.0
dialect: Places
version: 1.1
uses:
geo: ../vocabularies/geolocation.yaml
external:
schema: http://schema.org/
nodeMappings:
LocationNode:
classTerm: schema.Place
mapping:
name:
propertyTerm: schema.name
mandatory: true
range: string
image:
propertyTerm: schema.image
range: uri
location:
mandatory: true
propertyTerm: geo.position
range: CoordinatesNode
CoordinatesNode:
classTerm: geo.Point
mapping:
lat:
propertyTerm: geo.latitude
mandatory: true
range: double
long:
propertyTerm: geo.longitude
mandatory: true
range: double
documents:
root:
encodes: LocationNode

Now, we can parse documents that include geographical coordinates like:

golden_gate_2.yaml

#%Places 1.1
name: Golden Gate
image: https://en.wikipedia.org/wiki/Golden_Gate#/media/File:Golden_Gate_1.jpg
location:
lat: 37.81
long: 122.5

The geographical information will appear in the graph using the semantic terms defined in our geolocation vocabulary:

examples [master] $ java -jar amf.jar parse -ds file://aml/quickstart/dialects/places_2.yaml -in "AML 1.0" -mime-in application/yaml -ctx true file://aml/quickstart/golden_gate_2.yaml
[
{
"@id": "#",
"@type": [
"meta:DialectInstance",
"doc:Document",
"doc:Fragment",
"doc:Module",
"doc:Unit"
],
"meta:definedBy": [
{
"@id": "file://aml/quickstart/dialects/places_2.yaml#"
}
],
"doc:encodes": [
{
"@id": "#/",
"@type": [
"schema-org:Place",
"file://aml/quickstart/dialects/places_2.yaml#/declarations/LocationNode",
"meta:DialectDomainElement",
"doc:DomainElement"
],
"schema-org:image": [
{
"@id": "https://en.wikipedia.org/wiki/Golden_Gate#/media/File:Golden_Gate_1.jpg"
}
],
"schema-org:name": [
{
"@value": "Golden Gate"
}
],
"http://myorg.com/vocabs/geo#position": [
{
"@id": "#/location",
"@type": [
"http://myorg.com/vocabs/geo#Point",
"file://aml/quickstart/dialects/places_2.yaml#/declarations/CoordinatesNode",
"meta:DialectDomainElement",
"doc:DomainElement"
],
"http://myorg.com/vocabs/geo#longitude": [
{
"@value": 122.5
}
],
"http://myorg.com/vocabs/geo#latitude": [
{
"@value": 37.81
}
]
}
]
}
],
"@context": {
"@base": "file://aml/quickstart/golden_gate_2.yaml",
"doc": "http://a.ml/vocabularies/document#",
"meta": "http://a.ml/vocabularies/meta#",
"schema-org": "http://schema.org/"
}
}
]

Validating metadata documents#

If we try to parse an invalid document, the parser will fail and return an error message with a list of errors and syntactic information about the location of the error. As an example, you can try to parse the aml/quickstart/piccadilly_circus_error.yaml document in the examples. In this document, geographical coordinates are provided as strings instead of double values:

piccadilly_circus_error.yaml

#%Places 1.1
name: Piccadilly Circus
image: https://commons.wikimedia.org/wiki/File:Open_Happiness_Piccadilly_Circus_Blue-Pink_Hour_120917-1126-jikatu.jpg#/media/File:Open_Happiness_Piccadilly_Circus_Blue-Pink_Hour_120917-1126-jikatu.jpg
location:
lat: "51.30 N"
long: "0.8 W"

Parsing the document throws a textual error in the console:

examples [master] $ java -jar amf.jar parse -ds file://aml/quickstart/dialects/places_2.yaml -in "AML 1.0" -mime-in application/yaml -ctx true file://aml/quickstart/piccadilly_circus_error.yaml
Model: file://aml/quickstart/piccadilly_circus_error.yaml#
Profile: AMF
Conforms? false
Number of results: 2
Level: Violation
- Source: http://a.ml/vocabularies/amf/parser#inconsistent-property-range-value
Message: Cannot find expected range for property http://myorg.com/vocabs/geo#latitude (lat). Found 'http://www.w3.org/2001/XMLSchema#string', expected 'http://www.w3.org/2001/XMLSchema#double'
Level: Violation
Target: file://aml/quickstart/piccadilly_circus_error.yaml#/location
Property: http://myorg.com/vocabs/geo#latitude
Position: Some(LexicalInformation([(6,7)-(6,16)]))
- Source: http://a.ml/vocabularies/amf/parser#inconsistent-property-range-value
Message: Cannot find expected range for property http://myorg.com/vocabs/geo#longitude (long). Found 'http://www.w3.org/2001/XMLSchema#string', expected 'http://www.w3.org/2001/XMLSchema#double'
Level: Violation
Target: file://aml/quickstart/piccadilly_circus_error.yaml#/location
Property: http://myorg.com/vocabs/geo#longitude
Position: Some(LexicalInformation([(7,8)-(7,15)]))

To get the error report as a machine-friendly graph encoded using JSON-LD, the validate AMF command must be used.

Last updated on by arielmirra