odm-specification-dpdescriptor-parser

Java utilities for reading and writing Open Data Mesh's Data Product Descriptor Specification.

Table of Contents

1. Overview
2. Usage
3. Examples
4. Prerequisites
5. Installation
6. Releases

Overview

This library is used for reading, writing, and validating Data Product Descriptors as defined by the Open Data Mesh initiative. It provides tools to deserialize data descriptors into Java objects, validate their schemas, and manage descriptor locations, supporting URI and GIT navigation. The library is structured into several packages, each with a specific focus, such as model, parser, location, exceptions, and API.

Usage

Model

The /model package contains the structure of the Data Product Descriptor. The root object is DataProductVersionDPDS.

Parser

The /parser package contains all the code that is used to deserialize a Data Product Descriptor and map it into a DataProductVersionDPDS object. Inside the package, the DPDSParser can be used to:

• parse: Given a DescriptorLocation and ParseOptions, this method returns a DataProductVersionDPDS, which can be easily navigated.
• validateSchema: Given a data product descriptor, it checks that the schema is valid.

Location

The /location package contains code that is used to compose the descriptor into a single piece, resolving all references. This is done using navigation via URI or GIT.

Exceptions

All exceptions that can be thrown from the library code are found in this package.

Api

The /api package contains the code to analyze the api fields that are present inside the Data Product Descriptor. These can be written following AsyncAPI, OpenAPI, or DataStoreAPI specifications.

Examples

Parsing textual descriptor into DataProductVersionDPDS object

        String descriptorContent = "...";
        DescriptorLocation descriptorLocation = new UriLocation(descriptorContent);
        DPDSParser descriptorParser = new DPDSParser(
                "https://raw.githubusercontent.com/opendatamesh-initiative/odm-specification-dpdescriptor/main/schemas/",
                "1.0.0",
                null
        );
        IdentifierStrategy identifierStrategy = IdentifierStrategyFactory.getDefault("org.opendatamesh");
        ParseOptions options = new ParseOptions();
        options.setServerUrl(serverUrl);
        options.setIdentifierStrategy(identifierStrategy);
        
        ParseResult result = descriptorParser.parse(descriptorLocation, options);
        DataProductVersionDPDS descriptor = result.getDescriptorDocument();

Parsing textual descriptor into DataProductVersionDPDS object

Prerequisites

The project requires the following dependencies:

• Java 11
• Maven 3.8.6

Installation

To install the library in your Maven project, you must:

1. Add the dependency to the pom.xml file.

<dependency>
    <groupId>org.opendatamesh</groupId>
    <artifactId>odm-specification-dpdescriptor-parser</artifactId>
    <version>SELECTED VERSION</version>
</dependency>

2. Add the repository to the pom.xml file.

<repositories>
    <repository>
        <id>github</id>
        <name>GitHub Packages</name>
        <url>https://maven.pkg.github.com/opendatamesh-initiative/odm-specification-dpdescriptor-parser</url>
    </repository>
</repositories>

If the mvn install command is executed outside of a GitHub action (e.g. locally), you need to configure the Maven settings.xml file with your GitHub credentials. The GITHUB TOKEN must have read:packages permissions.

<settings>
    <servers>
        <server>
            <id>github</id>
            <username>GITHUB USERNAME</username>
            <password>GITHUB TOKEN</password>
        </server>
    </servers>
</settings>

The settings.xml file is in the ~/.m2 directory.

For additional information, see "How to install an Apache Maven package from GitHub Packages".

Releases

To publish a new release, navigate to the main page of the repository and go to Releases -> Draft a new release. Select a tag for the release. Note: This tag must match the Maven version specified in the repository's .pom file. Upon publishing the new release, the GitHub Action will automatically publish the corresponding Maven package to GitHub Packages.