Skip to content

Extending the specification⚓︎

The Data Product Descriptor Specification (DPDS) can be customized to your needs in different ways. This page describes the key extension points provided by DPDS.

Use an external specification⚓︎

For all components of a data product descriptor documents that can be better defined by a dedicated specification or an existing standard, DPDS does not try to reinvent the wheel. It allows you to define the specific component using the external specification you prefer, even a custom one.

Through the Standard Definition Object it is possible to describe a component in a data product descriptor document, using an external specification or standard. These are the mandatory fields of the Standard Definition Object:

  • specification (string): The unique name of the specification used (ex. OpenAPI, AsyncAPI, DatastoreAPI, etc....)
  • definition (string or [Reference Object] or [External Resource Object]): The definition of the given component compliant with the specification defined in the specification field.

Even if not mandatory it is RECOMMENDED to specify also the used specification version through the version field. If this field is not specified the specification version MUST be included in the definition itself.

The Standard Definition Object can be extended with other fields with "x-" prefix as needed.

Note

In the current release of DPDS the Standard Definition Object is used to define API of services exposed by the data product.

The following example shows an output port component that exposes streaming services and uses version 2.5.0 of AsyncAPI specification to define them.

JSON
{
    "fullyQualifiedName": "urn:dpds:com.company-xyz:dataproducts:tripExecution:1:outputports:tripEvents",
    "name": "tripEvents",
    "displayName": "Trip Events",
    "description": "This port exposes a *stream of events* related to the `Trip` entity",
    "version": "1.2.0",
    "promises": {
        "platform": "westeurope.azure:confluent",
        "serviceType": "streaming-services",
        "api": {
            "specification": "asyncapi",
            "version": "2.5.0",
            "definition": {
                "mediaType": "text/json",
                "$href": "https://github.com/opendatamesh-initiative/odm-specification-dpdescriptor/blob/main/examples/tripexecution/ports/trip-events-oport-api.json"
            },
            "externalDocs": {
                "description": "The AsyncAPI v2.5.0 specification used to define the API of this port",
                "mediaType": "text/html",
                "$href": "https://www.asyncapi.com/docs/reference/specification/v2.5.0"
            }
        },
        ...
    },
    ...
}

Adding custom fields⚓︎

Almost all components of a data product descriptor document can be extended with other fields with "x-" prefix as needed. The prefix is required to avoid possible conflict with future versions of the specification. Tools compliant with the specification CAN or CANNOT properly manage a custom field.

Extending a specification extension point⚓︎

A Specification Extension Point (../resources/specifications/last.md#standard-definition-object) marks specific parts of the Data Product Descriptor Specification (DPDS) that are left open to extensions or further evolution of the standard.

While a Standard Definition Object it's a formal declaration that the description of a part of the DPDS will be demanded to an external standard in this version of the specification and also in future ones, the same assumption it's not true for Specification Extension Points.

Even if a Specification Extension Point can be extended at will it is RECOMMENDED to use for all added properties a field name prefixed by "x-" to avoid potential conflicts with future versions of the DPDS.

Last update: November 26, 2022
Created: November 26, 2022