YAMAML Specification

Version: 0.2.0 Status: Working Draft Date: 2026-03-14 Latest: https://docs.yamaml.org/specs/yamaml/spec/

Abstract

YAMAML (Yet Another Metadata Application Profile and RDF Mapping Language) is a human-friendly markup language for creating, managing, and publishing metadata application profiles. YAMAML documents describe the structure and constraints of metadata records using YAML syntax, and can be transformed into standard formats including RDF, SHACL, ShEx, OWL-DSP, SimpleDSP, DCTAP, and Frictionless Data Packages.

Status of This Document

This document defines the textual syntax and semantics of YAMAML. It is a working draft and subject to change.

Historical Note

YAMAML is based on the YAMA specification (Yet Another Metadata Application Profile, circa 2019). YAMAML extends and refines the original YAMA concepts with a clearer document model, explicit data mapping capabilities, richer constraint vocabulary, and interoperability with modern metadata standards. Where the original YAMA specification used the term “Description Set” as a top-level container, YAMAML simplifies this to a flat document model. Elements such as description_set, standalone, name, long_description, and constraint from the original YAMA specification have been superseded by the elements defined in this document.

1. Introduction

1.1 Design Goals

YAMAML is designed to be:

• Human-readable — authored and reviewed in a plain text editor.
• YAML-native — parsable by any YAML 1.2 compliant parser.
• Multi-target — a single source document produces RDF, SHACL, ShEx, DCTAP, DSP, diagrams, and more.
• Extensible — custom keys are permitted alongside the reserved vocabulary defined here.
• Practical — includes optional data mapping for generating RDF from tabular or structured data sources.

1.2 Syntax Compatibility

YAMAML documents are valid YAML 1.2 documents. A YAMAML document SHOULD begin with the YAML directive and document start marker:

%YAML 1.2
---

1.3 Conventions

The key words “MUST”, “SHOULD”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

In property tables:

• R = Required
• Type = Expected YAML type
• Default = Value assumed when the key is absent

2. Document Structure

A YAMAML document is a YAML mapping with the following top-level structure:

%YAML 1.2
---
base: <IRI>
namespaces:
  <prefix>: <IRI>
defaults:
  mapping:
    <mapping-properties>
data:
  - <inline-records>
descriptions:
  <description-name>:
    <description-properties>

2.1 Top-Level Properties

2.2 Namespaces

The namespaces section declares prefix-to-IRI bindings used throughout the document for compact IRI notation (prefixed names).

namespaces:
  foaf: http://xmlns.com/foaf/0.1/
  schema: http://schema.org/
  xsd: http://www.w3.org/2001/XMLSchema#
  dcterms: http://purl.org/dc/terms/

Prefixed Names

A prefixed name has the form prefix:localName (e.g., foaf:name). Processors expand prefixed names by replacing prefix: with the corresponding namespace IRI. Full IRIs (http://..., urn:...) are also accepted wherever a prefixed name is expected.

Standard Prefixes

A YAMAML processor maintains a standard prefix table identical to the SimpleDSP table: dc, dcterms, foaf, skos, xl, rdf, rdfs, owl, xsd, and schema. These entries are consulted as a fallback to resolve any prefixed name whose prefix is not declared in the document’s namespaces section.

Resolution Rule

For any prefixed name prefix:localName in a YAMAML document, a YAMAML processor resolves the prefix as follows:

1. If prefix is declared in namespaces, use the IRI bound there.
2. Otherwise, if prefix appears in the standard prefix table, use the IRI from the table.
3. Otherwise, the prefix is undeclared and the document is not well-formed.

The user’s namespaces declarations take precedence unconditionally. A prefix declared in namespaces may bind to any IRI; the processor does not compare it against the standard table. Authors may redefine a standard prefix, use unconventional labels (for example, DCTERMS instead of dcterms), or bind a familiar label to a different IRI for local conventions. Prefix labels in RDF/SHACL/ShEx outputs mirror those used in the profile — exported @prefix declarations are derived from the resolved bindings, not renamed to canonical forms.

If every prefixed name in the document resolves through the standard prefix table, the namespaces section may be omitted.

2.3 Defaults

The defaults section provides inherited values for descriptions and their statements, reducing repetition when many statements share common properties.

defaults:
  mapping:
    source: data.csv
    type: csv

Currently, only mapping defaults are defined. When a statement’s mapping is specified, its properties are merged with the defaults — statement-level values override defaults.

2.4 Inline Data

The data section holds inline records that can be used as a data source via source: data in a mapping. This is an alternative to referencing external files.

data:
  - id: 1
    name: Alice
  - id: 2
    name: Bob

3. Descriptions

A description defines a class of resources — the equivalent of a shape, template, or record type. Each description is identified by its key within the descriptions mapping.

descriptions:
  book:
    a: schema:Book
    label: Book
    note: A published book
    statements:
      title:
        property: dcterms:title
        # ...

3.1 Description Properties

3.2 Identifier Mapping

Descriptions that participate in RDF generation from data sources require an id section that specifies how record identifiers are extracted from the data.

descriptions:
  character:
    a: foaf:Person
    id:
      prefix: tbbt
      mapping:
        source: characters.csv
        type: csv
        path: ID

id Properties

When prefix is omitted, the identifier value is appended to the document base to form the subject IRI (backward-compatible behavior). When prefix is present, the referenced namespace takes precedence over base for that description’s records.

In SimpleDSP, prefix corresponds to the ID row’s value constraint column — a namespace prefix ending with : (e.g. ndlbooks:). The document-level base corresponds to @base in the SimpleDSP [@NS] block, which is the schema namespace (where the description template definitions live), distinct from the record namespace.

# Schema namespace — where the DSP definitions live
base: http://ndl.go.jp/dcndl/dsp/biblio

namespaces:
  ndlbooks: http://iss.ndl.go.jp/books/
  ndlauthors: http://iss.ndl.go.jp/authors/

descriptions:
  MAIN:
    a: foaf:Document
    id:
      prefix: ndlbooks       # records live at http://iss.ndl.go.jp/books/{id}
      mapping:
        path: 書誌ID

  Author:
    a: foaf:Person
    id:
      prefix: ndlauthors     # records live at http://iss.ndl.go.jp/authors/{id}
      mapping:
        path: AuthorID

3.3 Description References

Descriptions can reference other descriptions to model relationships:

• IRI references — A statement with type: IRI and description: <name> creates a typed relationship to another description.
• Blank node references — A statement with type: BNODE and description: <name> creates an inline blank node with the properties of the referenced description.

descriptions:
  person:
    a: foaf:Person
    statements:
      address:
        property: schema:address
        type: BNODE
        description: postalAddress    # inline blank node
      knows:
        property: foaf:knows
        type: IRI
        description: person           # self-reference (IRI link)

  postalAddress:
    a: schema:PostalAddress
    statements:
      street:
        property: schema:streetAddress
        type: literal
        datatype: xsd:string

4. Statements

A statement defines a single property of a described resource — its predicate, expected value type, cardinality constraints, and optional data mapping.

statements:
  title:
    label: Title
    property: dcterms:title
    min: 1
    max: 1
    type: literal
    datatype: xsd:string
    note: The title of the resource

4.1 Statement Properties

4.2 Value Types

The type property declares the kind of value a statement expects.

4.3 Cardinality

Cardinality is expressed through min and max:

When max is absent, the property is unbounded (repeatable without limit).

The cardinalityNote property allows descriptive cardinality that cannot be expressed as numeric min/max, such as “recommended” or “mandatory if applicable”. When cardinalityNote is present:

• min and max MAY still be specified for machine-processable cardinality.
• Processors that support descriptive cardinality (e.g., OWL-DSP) SHOULD emit the note alongside any numeric constraints.

4.4 Facets

The facets mapping provides fine-grained constraints on values, following XSD facet semantics:

statements:
  age:
    property: foaf:age
    type: literal
    datatype: xsd:integer
    facets:
      MinInclusive: 0
      MaxInclusive: 150
  isbn:
    property: schema:isbn
    type: literal
    datatype: xsd:string
    facets:
      Length: 13

4.5 Value Constraints

Enumerated Values

The values property restricts a statement to a fixed set of allowed values:

# Literal picklist
format:
  property: dcterms:format
  type: literal
  values:
    - print
    - ebook
    - audiobook

# IRI value set
license:
  property: dcterms:license
  type: IRI
  values:
    - http://creativecommons.org/licenses/by/4.0/
    - http://creativecommons.org/publicdomain/zero/1.0/

Pattern

The pattern property constrains values using a regular expression:

issn:
  property: schema:issn
  type: literal
  datatype: xsd:string
  pattern: "^\\d{4}-\\d{3}[\\dX]$"

Vocabulary Scheme

The inScheme property constrains IRI values to specific vocabulary namespaces:

subject:
  property: dcterms:subject
  type: IRI
  inScheme: skos:       # values must be from the SKOS namespace

classification:
  property: dcterms:subject
  type: IRI
  inScheme:             # values from either namespace
    - ndlsh:
    - lcsh:

5. Data Mapping

YAMAML supports an optional data mapping layer for generating RDF from tabular or structured data sources. Mappings are defined at both the description level (for record identity) and the statement level (for property values).

5.1 Mapping Properties

5.2 Data Sources

YAMAML supports the following data source formats:

Source paths are resolved relative to the YAMAML document’s directory. Absolute paths and URLs are used as-is.

5.3 Value Transformation Pipeline

When a mapping is present, extracted values pass through a transformation pipeline in the following order:

1. Extract — The path expression is evaluated against the data source to obtain the raw value.
2. Split — If separator is defined and the value is a string, it is split into multiple values.
3. Strip — Characters listed in strip are removed from each value.
4. Replace — Each [from, to] pair in replace is applied as a global string replacement.
5. Decorate — prepend and append are added to each value.

5.4 Defaults and Inheritance

The defaults.mapping section provides base mapping properties inherited by all statements. Statement-level mapping properties override defaults:

defaults:
  mapping:
    source: characters.csv
    type: csv

descriptions:
  character:
    id:
      mapping:
        path: ID            # inherits source and type from defaults
    statements:
      name:
        property: foaf:name
        mapping:
          path: name         # inherits source and type from defaults
      wikidata:
        property: rdfs:seeAlso
        type: IRI
        mapping:
          source: external.csv   # overrides default source
          path: wikidata_id
          prepend: http://www.wikidata.org/entity/

6. Worked Examples

Complete YAMAML profiles are available in the Examples section:

The same examples authored in PKL appear in §10 of the PKL authoring guide.

7. Output Format Mappings

This section defines how YAMAML elements map to each supported output format.

7.1 RDF

RDF generation requires data mappings. Each record in the data source produces a set of quads.

7.2 SHACL

7.3 ShEx

7.4 OWL-DSP

7.5 SimpleDSP

SimpleDSP value type resolution:

7.6 DCTAP

7.7 Frictionless Data Package

8. Processing Model

8.1 IRI Expansion

Processors MUST expand prefixed names to full IRIs using the following rules:

1. If the term matches ^(https?|urn):, it is already a full IRI.
2. If the term contains :, split on the first : to get prefix and localName. If prefix matches a declared namespace, expand to namespace_IRI + localName.
3. Otherwise, if base is defined, expand to base + term.
4. Otherwise, use the term as-is.

8.2 Source Path Resolution

Data source paths in mappings are resolved as follows:

1. If the path starts with http:// or https://, it is treated as a URL and fetched over the network.
2. If the path starts with /, it is an absolute file path.
3. Otherwise, it is resolved relative to the directory containing the YAMAML document.

8.3 Type Inference

When type is omitted from a statement:

• If datatype is present, the value type is implicitly literal.
• If description is present and no type is specified, the relationship type depends on context (processors MAY default to IRI).
• If neither datatype nor description is present, processors SHOULD treat the type as literal.

9. Conformance

9.1 Document Conformance

A conforming YAMAML document:

1. MUST be valid YAML 1.2.
2. MUST contain a descriptions mapping with at least one description.
3. Each description MUST contain a statements mapping (descriptions without statements are permitted but not actionable).
4. Each statement that participates in output generation MUST have a property key.

9.2 Processor Conformance

A conforming YAMAML processor:

1. MUST parse YAML 1.2 documents.
2. MUST expand prefixed names using declared namespaces.
3. MUST support the top-level keys defined in Section 2.1.
4. MUST support the description properties defined in Section 3.1.
5. MUST support the statement properties defined in Section 4.1.
6. SHOULD ignore unknown keys without raising an error.
7. MAY support a subset of output formats.

10. Differences from YAMA 0.1.5

This section summarizes the key differences between YAMAML and the original YAMA specification (v0.1.5, circa 2019).

References

• YAML 1.2 Specification: https://yaml.org/spec/1.2/spec.html
• YAMA Specification (historical, circa 2019): http://purl.org/yama/spec/latest
• SHACL: https://www.w3.org/TR/shacl/
• ShEx: https://shex.io
• DCTAP: https://dcmi.github.io/dctap/
• OWL-DSP Ontology: https://www.kanzaki.com/ns/dsp#
• SimpleDSP: See the SimpleDSP Specification
• Frictionless Data Package: https://datapackage.org
• Semantic Versioning: https://semver.org

Related Publications

The following peer-reviewed publications describe the research and design behind YAMA and YAMAML, listed in chronological order:

1. Thalhath, N., Nagamori, M., Sakaguchi, T., & Sugimoto, S. (2019). Authoring Formats and Their Extensibility for Application Profiles. In A. Jatowt, A. Maeda, & S. Y. Syn (Eds.), Digital Libraries at the Crossroads of Digital Information for the Future (pp. 116–122). Lecture Notes in Computer Science. Springer International Publishing. https://doi.org/10.1007/978-3-030-34058-2_12

2. Thalhath, N., Nagamori, M., Sakaguchi, T., & Sugimoto, S. (2019). Yet Another Metadata Application Profile (YAMA): Authoring, Versioning and Publishing of Application Profiles. International Conference on Dublin Core and Metadata Applications, 114–125. https://doi.org/10.23106/dcmi.952141854

3. Thalhath, N., Nagamori, M., Sakaguchi, T., & Sugimoto, S. (2020). Metadata Application Profile Provenance with Extensible Authoring Format and PAV Ontology. In X. Wang, F. A. Lisi, G. Xiao, & E. Botoeva (Eds.), Semantic Technology (pp. 353–368). Lecture Notes in Computer Science. Springer International Publishing. https://doi.org/10.1007/978-3-030-41407-8_23

4. Thalhath, N., Nagamori, M., & Sakaguchi, T. (2022). YAMAML: An Application Profile Based Lightweight RDF Mapping Language. In Y.-H. Tseng, M. Katsurai, & H. N. Nguyen (Eds.), From Born-Physical to Born-Virtual: Augmenting Intelligence in Digital Libraries (pp. 412–420). Lecture Notes in Computer Science. Springer International Publishing. https://doi.org/10.1007/978-3-031-21756-2_32

5. Thalhath, N., Nagamori, M., & Sakaguchi, T. (2025). Metadata Application Profile as a Mechanism for Semantic Interoperability in FAIR and Open Data Publishing. Data and Information Management, 9(1), 100068. https://doi.org/10.1016/j.dim.2024.100068

License

This specification is licensed under Attribution-ShareAlike 4.0 International (CC BY-SA 4.0).