Define catalog specifications

A catalog specification defines the structure, validation rules, and tagging behavior for metadata you want to associate with a nullplatform entity. This is where you decide what “custom attributes” an entity can support—and how that data should look, behave, and integrate with the platform.

When to create a specification

Use a catalog specification when you want to:

• Enforce consistent structure for entity attributes.
• Validate metadata input using JSON Schema.
• Enable dynamic features like autogenerated forms or searchable tags.
• Standardize information across builds, applications, namespaces, or other entities.

Breakdown of a specification

A specification includes:

Field	Description
entity	The entity type the specification applies to (e.g., build, application)
metadata	A unique key for the metadata entry (e.g., coverage, aliases)
schema	A JSON Schema that defines structure and validation
nrn	Scope of the specification (e.g., organization, namespace, etc.)
name	A human-readable name for the catalog entry
description	An optional description for UI and documentation

Example: build coverage metadata

Here’s a schema for tracking code coverage in builds:

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

This enforces that:

• Coverage percent must be a number between 0–100.
• A report URL must be included.
• No extra properties are allowed.

tip

Lower levels in your NRN hierarchy override higher-level definitions.
For example, you can apply a global coverage spec at the organization level, but override it at a namespace or app level if needed.

Tagging fields for search and integrations

Tags help you make catalog data more actionable across the platform. When you mark a field as a tag, nullplatform can:

• Display that value prominently in dashboards
• Enable filtering/searching by that field
• Sync tags with external systems (e.g., cloud provider labels, FinOps dashboards, or custom search engines)

How tagging works

Tags can be applied in two ways:

1. At the root level of the metadata schema — useful for simple string or numeric values.
2. Inside object properties — useful for structured schemas where you want to selectively expose certain fields.

You apply a tag using the "tag" keyword inside your JSON Schema field definition. You can also provide a custom tag alias if you want the tag to appear under a different name in the UI or integrations.

Examples

Example 1: Tagging a simple string field

Let’s say you want to tag each application with a short name or alias. You can define your schema like this:

{
  "type": "string",
  "tag": true
}

This will:

• Use the field’s value as both the metadata and the tag.
• Automatically make this field show up in dashboards or tag filters.

If a user saves:

"aliases": "frontend-api"

Then "frontend-api" will be used as a tag associated with that entity.

Example 2: Using a custom tag name (alias)

You might want the metadata key and tag key to differ. In this case, use a string instead of true:

{
  "type": "string",
  "tag": "team_alias"
}

Now if the field has a value "sre-core", it will appear as the tag:

"team_alias": "sre-core"

This is helpful when:

• You want to unify tag naming across different schemas.
• You want to surface metadata under more recognizable labels for the UI or third-party tools.

Example 3: Tagging fields inside an object

You can tag individual fields in an object schema too. Here’s a real-world example for an application entity:

{
  "type": "object",
  "properties": {
    "platform_type": {
      "type": "string",
      "enum": ["mobile", "web", "iot"],
      "tag": "platform"
    },
    "aliases": {
      "type": "array",
      "items": { "type": "string" },
      "tag": true
    }
  },
  "required": ["platform_type"]
}

What this does:

• Adds a tag called platform with values like "web" or "mobile".
• Adds each value in aliases as an additional tag.

Then the system generates these tags:

{
  "platform": "web",
  "aliases": ["frontend-api", "public-facing"]
}

These tags:

• Show up visually in dashboards
• Can be used for filtering, grouping, or reporting
• Can be exported or synced via integrations

Things to keep in mind about tagging

• Tags are optional — not every field needs them.
• tag: true uses the field name as the tag key.
• tag: "custom_name" lets you define your own key.
• You can tag multiple fields in the same schema.

Create a catalog specification

To define a new specification, send a POST request to the to the catalog API:

curl -L -X POST 'https://api.nullplatform.com/metadata/metadata_specification' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{
  "name": "<your-catalog-spec-name>",
  "description": "<your-description-for-the-spec>",
  "nrn": "organization=1", 
  "entity": "namespace",    // parent entity that holds metadata information
  "metadata": "<an-entity-metadata-key>",
  "schema": {
    "type": "object",
    "properties": {
      "my_string_property": {    // string property sample
        "type": "string",
        "tag": true
      },
      "my_number_property": {    // number property sample
        "type": "number",
        "default": 0,
        "tag": "my_custom_tag_name"
      },
      "my_object_property": {    // object property sample
        "type": "object",
        "properties": {
          "my_nested_property": {
            "type": "string"
          }
        }
      }
    },
    "required": [
      "my_string_property"  // defines which properties from the schema are required
    ],
    "additionalProperties": false
  }
}'

This is an example for creating a catalog specification for the application entity. This specification defines a schema for metadata with two fields:

• aliases: a list of strings (used as tags)
• platform_type: a string with controlled values (mobile, web, or iot), also used as a tag under a custom name platform

{ 
  "name": "App Platform Info",
  "description": "Platform type and aliases",
  "nrn": "organization=1",
  "entity": "application",
  "metadata": "platform_info",
  "schema": {
    "type": "object",
    "properties": {
      "aliases": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "tag": true
      },
      "platform_type": {
        "type": "string",
        "enum": ["mobile", "web", "iot"],
        "tag": "platform"
      }
    },
    "required": ["platform_type"],
    "additionalProperties": false
  }
}'

Note: For a full breakdown of the request parameters, see the API reference.

Next steps

Once you’ve defined a specification, continue to:

• Add metadata to catalog entities
• Use metadata to power UI components
• Autogenerate forms from schema