YAMA: Yet Another Metadata Application Profile

1. YAMA Specification

This document defines textual syntax and specifications for writing YAMA documents in a natural text form. YAMA syntax is based on [YAML 1.2 specification](https://yaml.org/spec/1.2/spec.html). YAMA is parsable with any YAML 1.2 parser, but processing capabilities of YAMA documents are limited to YAMA specific implementations.

2. Status of This Document

This document is a part of the YAMA documentation. This document defines textual syntax and specifications. This is a working draft.

3. Introduction

3.1. Philosophy of YAMA

Yet Another Metadata Application Profile (YAMA) is not defined as a new standard of metadata application profiles; but YAMA is defined as an easy to use preprocessor to create standard metadata application profile formats. YAMA intended to be simple enough that it can be used by domain experts without extensive knowledge on metadata application profiles.

3.2. Syntax Compatibility

Instead of introducing its own syntax, YAMA adapts popular YAML format to avoid reinventing the wheel. Being a well proven data serialization format, YAML is widely accepted and various implementations are available for different programming languages. YAMA intended to get benefited from YAML’s readability and human friendliness. As a superset of JSON, YAML is a comfortable choice to express complex structures in a human readable yet machine friendly way.

3.3. Extendability

YAMA is extendable with custom elements and structure. The only restriction is custom elements cannot be from reserved element sets. This will help to extend the capabilities of YAMA without any large-scale implementation changes. Any such extension is possible within the scope of YAML specification.

There is also a user variables section which is a straightforward approach to add any user defined variables without altering the structure of a YAMA document.

3.4. Specification Versioning

YAMA specifications adhere to [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html), where are the MAJOR.MINOR stands for specification versions and PATCH for corrections and changes of the documentation, which doesn’t break any implementations.

MAJOR version changes will affect the core specification, and MINOR version changes will be backward compatible and does not affect any previously implemented specifications.

4. Document Structure

A YAMA document should strictly follow YAML specifications. document should start with a valid YAML declaration and YAMA version should be mentioned before starting the structure of the document. if a valid YAMA specification version is not declared, then the last available version is assumed to be used.

%YAML 1.2
---  
YAMA : 1.0

4.1. Metadata of the Application Profile

Metadata section is intended to express basic information of the specific metadata application profile. generally administrative metadata of the MAP is expressed as a key value pair. Important property from this section is the version and creator. This information is used in generating publishable formats and creating provenance information as well as change-log of the metadata application profile.

YAMA documents MUST be versioned. [Semantic versioning (SemVer)](https://semver.org/) is highly recommended optionally [calendar versioning (CalVer)](https://calver.org/) can be considered if it fits the requirements. With the proper version number, YAMA processors can automate various versioning related tasks as well as can generate publishable versioned output formats.

description_set :
  ID                 :           # (R) A unique ID for the Description Set. eg : MyBookCaseDS.
  title              :           # Name of the AP. eg : My Book Case Application Profile.
  version            :           # Version following semver.org Semantic Versioning eg. X.Y.Z or X.Y or X.
  date               :           # Release date of AP. Any valid ISO-8601 string.
  subject            :           # Subject or topic.
  creator            :           # Person, URL or more contact information. Can also be {name: Person, email: Email, org: Org}
  open               : true      # Open or closed DSP, will be respected in Application Profile curation services. Default true.
  license            :           # License of the DSP default CC ?
  descriptions       : [a,b]     # If given as a list, only those descriptions will be included, else all descriptions with this DSP-ID will be used

4.2. Name Spaces

Name spaces are key value pair of prefix and URI. YAMA follows XML specification for prefixes and URI. URI should be as recommended in RFC3986 (https://tools.ietf.org/html/rfc3986). during the document processing, YAMA can generate Qnames from this namespace key values.

namespaces     : 
  prefix_1           : uri_1
  prefix_2           : uri_2  

4.3. Descriptions

descriptions   :
  example_description_01:
    label            :          # (R) Label of the Element
    name             :          # Human Friendly Name
    min              :          # 
    max              :          # 
    standalone       : true     # Default, true
    X class            :          # 
    X subclass         :          # 
    description      :          # Short Description
    long_description :          # Detailed Description
    statements       : [a,b]    # 

4.4. Statements

A statement is a single data element used to describe a resource that is defined as a description. The statement defines the possible values, and any other constraints.

statements     : 
  example_statement_01 :
    label            :          # (R) Label of the Element
    name             :          # Human Friendly Name
    min              :          # 
    max              :          # 
    type             :          # 
    description      :          # Short Description
    long_description :          # Detailed Description
    constraint       : x or [x,y]   # IDs of constraints

4.5. License

[Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)] (https://creativecommons.org/licenses/by-sa/4.0/)