Metadata

Overview

Metadata is a powerful tool that allows users to extend nullplatform entities by associating additional metadata with them. This metadata is validated against defined schemas, ensuring data integrity and consistency. By using our metadata tool, you can customize and enhance the functionality of nullplatform entities to meet your specific needs.

Purpose

The metadata API serves several key purposes:

Extend nullplatform entities: By adding metadata to nullplatform entities, you can use this data to evaluate actions and approvals. For example, you can add coverage data to a build entity to assess the quality and completeness of a build.
Customize frontend display: Use metadata to display custom data in the nullplatform frontend. For instance, you can add tags to a namespace entity to better categorize and manage namespaces within your organization.
Service provisioning: Metadata can be used to configure and manage services dynamically. For example, you can use metadata to define the configuration parameters for deploying an application, ensuring that each deployment is tailored to specific requirements.

How to use the metadata API

Note

For detailed information about all defined endpoints and examples, please refer to this section.

Managing metadata specifications

Metadata specifications define the schemas against which metadata is validated. You can create, read, update, and delete metadata specifications. Each specification applies to a particular hierarchy within a NRN (Nullplatform Resource Name). You can override a metadata definition by redefining it at a lower level in the hierarchy.

Creating metadata specification

Let's create a coverage metadata specification associated with the build entity. This specification will have the properties percent, to measure the amount of code coverage, and report, to specify a URL where the full coverage report is located, the schema is defined by providing a valid JSON Schema. For more details, check the documentation here.

This metadata can be used to display coverage information in our frontend and to evaluate automatic deployment actions and approvals.

{
  "name": "Coverage",
  "description": "Build coverage report",
  "nrn": "organization=1",
  "entity": "build",
  "metadata": "coverage",
  "schema": {
    "type": "object",
    "properties": {
      "percent": {
        "type": "number",
        "default": 0,
        "minimum": 0,
        "maximum": 100
      },
      "report": {
        "type": "string",
        "format": "uri"
      }
    },
    "required": [
      "percent",
      "report"
    ],
    "additionalProperties": false
  }
}

You can also configure tags for your metadata, which is especially useful when you want to integrate those tags with your cloud provider, FinOps platform, search engine, or any other system where tags are beneficial. For example, let's define an alias metadata with tagging support:

{
  "name": "Aliases",
  "description": "Application aliases",
  "entity": "application",
  "metadata": "aliases",
  "schema": {
    "type": "string",
    "tag": true,
    "additionalProperties": false
  }
}

This will add "aliases" metadata as a tag key with its metadata value as the tag value.

You can also customize your tag key using a tag alias by specifying tag: 'my_tag_name'.

Tags are also supported at the schema properties level. For example:

{
  "name": "Additional information",
  "description": "Application additional information",
  "nrn": "organization=1",
  "entity": "application",
  "metadata": "additional_information",
  "schema": {
    "type": "object",
    "properties": {
      "aliases": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "tag": true
      },
      "platform_type": {
        "type": "string",
        "enum": [
          "mobile",
          "web",
          "iot"
        ],
        "tag": "platform"
      }
    },
    "additionalProperties": false
  }
}

Once the metadata specification is created, you can start saving metadata associated with the entity. You have the option to send multiple metadata entries in a single request, or you can use dedicated endpoints for each metadata specification. This is particularly useful when dealing with complex metadata specifications.

Creating metadata for multiple specification entries

To create metadata for multiple specification entries in a single request for a nullplatform entity, specify the entity name and entity ID in the request, and include all the metadata entries as a JSON object in the request body. Each metadata entry will be validated against a predefined schema specific to the metadata key. This schema ensures that the metadata adheres to the required format and constraints, maintaining data integrity and consistency.

Example request:

{
  "coverage": {
    "percent": "95",
    "report": "https://reports.my-organization.com/coverage/build-f1b4be69-1147-4870-a35b-6e718b029f80.html"
  },
  "vulnerabilities": {
    "high": 0,
    "medium": 0,
    "low": 2,
    "report": "https://reports.my-organization.com/vulnerabilities/build-f1b4be69-1147-4870-a35b-6e718b029f80.html"
  }
}

In this example, coverage and vulnerabilities are metadata specifications for the build entity.

Reading all entity metadata

To read all metadata from a nullplatform entity, specify the entity name and entity ID in your request. This will enable you to retrieve all the metadata associated with the specified entity.

Example response:

{
  "coverage": {
    "percent": "95",
    "report": "https://reports.my-organization.com/coverage/build-f1b4be69-1147-4870-a35b-6e718b029f80.html"
  },
  "vulnerabilities": {
    "high": 0,
    "medium": 0,
    "low": 2,
    "report": "https://reports.my-organization.com/vulnerabilities/build-f1b4be69-1147-4870-a35b-6e718b029f80.html"
  },
  "additional_properties": {
    "entity": "build",
    "id": "1",
    "nrn": "organization=1:account=1:namespace=1:application=1:build=1"
  }
}

Note

You can also include extra fields, such as specification schemas and tags values, by using the include directive in the query parameters: include=tags,schemas.

Creating a particular metadata

To create a particular metadata for a nullplatform entity, specify the entity name, entity ID, and metadata key in the request, and include the metadata as a JSON object in the request body. The metadata will be validated against a defined schema specific to the metadata key. This schema ensures that the metadata adheres to the required format and constraints, maintaining data integrity and consistency.

Example request:

{
  "percent": "95",
  "report": "https://reports.my-organization.com/coverage/build-f1b4be69-1147-4870-a35b-6e718b029f80.html"
}

Reading metadata

To read a particular metadata from a nullplatform entity, specify the entity name, entity ID, and metadata key in your request. This will enable you to retrieve the metadata associated with the specified entity.

Example response:

{
  "percent": "95",
  "report": "https://reports.my-organization.com/coverage/build-f1b4be69-1147-4870-a35b-6e718b029f80.html"
}

Overview​

Purpose​

How to use the metadata API​

Managing metadata specifications​

Creating metadata specification​

Creating metadata for multiple specification entries​

Reading all entity metadata​

Creating a particular metadata​

Reading metadata​