Manifest Validation

Shoehorn validates manifests against a JSON Schema and custom rules before applying them to the catalog. This document describes all validation checks.

Schema Validation

Required Fields

Field	Rule
`schemaVersion`	Must be `1` (integer)
`service.id`	Must match `^[a-z0-9]+(-[a-z0-9]+)*$` (kebab-case)
`service.name`	Non-empty string
`service.type`	Must be a valid entity type
`owner`	At least one entry required (except `catalog-source` type)

Field Constraints

Field	Constraint
`service.id`	Lowercase, hyphens only, no underscores or spaces
`service.type`	One of: `service`, `api`, `frontend`, `database`, `library`, `team`, `system`, `resource`, `domain`, `extras`, `catalog-source`
`service.tier`	One of: `platinum`, `gold`, `silver`, `bronze`, `critical`, `high`, `medium`, `low`
`lifecycle`	One of: `production`, `staging`, `development`, `deprecated`, `experimental`
`tags`	Array of lowercase strings
`links[].url`	Must start with `http://` or `https://`
`links[].name`	Required, non-empty
`relations[].type`	Must be a valid relation type
`relations[].target`	Must match format `<type>:<identifier>`
`integrations.licenses[].seats`	Minimum 1 (if present)
`integrations.runbooks[].severity`	One of: `critical`, `high`, `medium`, `low`

Custom Validation Rules

Beyond schema validation, these additional checks are applied:

Service ID

Must not contain uppercase letters
Must not contain underscores (use hyphens)
Must not start or end with a hyphen
Must be unique within the tenant

Owner Validation

At least one owner must be specified (unless type is catalog-source)
Owner type must be one of: team, user, productOwner, designer, stakeholder, support, manager
Owner id must be non-empty

Link Validation

URL must be a valid HTTP or HTTPS URL
Icon (if specified) must be a recognized icon name

Relation Validation

Target format must be <type>:<identifier>
Valid target types: service, database, topic, team, channel, link, oncall, system, resource
Self-referencing relations produce a warning

Interface Validation

http.baseUrl must be a valid URL if present
http.openapi can be a file path or URL
graphql.endpoint must be a valid URL or path if present
grpc.package must be non-empty if present

Validation Response

The validation endpoint returns:

{
  "valid": true,
  "errors": [],
  "warnings": [
    {
      "field": "tags",
      "message": "Tag 'MyTag' should be lowercase",
      "severity": "warning"
    }
  ]
}

Field	Description
`valid`	`true` if no errors (warnings are allowed)
`errors`	Array of validation errors (blocks import)
`warnings`	Array of warnings (does not block import)

Common Validation Errors

Error	Cause	Fix
`service.id is required`	Missing service ID	Add `service.id` field
`service.id must match pattern`	Invalid characters in ID	Use lowercase kebab-case only
`service.type must be one of`	Invalid entity type	Use a supported type
`owner is required`	No owner specified	Add at least one owner entry
`links[0].url must be a valid URL`	Invalid link URL	Use `http://` or `https://` prefix
`relations[0].target must match format`	Bad relation target	Use `type:identifier` format

Quality Analysis

The analyze endpoint (POST /api/v1/manifest/analyze) provides additional scoring:

Quality Score (0-100)

Category	Weight	What It Checks
Documentation	25%	README, description, runbooks, changelog
Metadata	35%	Name, type, tier, lifecycle, tags, links
Relationships	20%	Relations, owner assignments
Interfaces	20%	HTTP, gRPC, GraphQL definitions

Recommendations

The analyzer provides prioritized recommendations:

High: Missing owner, no lifecycle set, no description
Medium: No tags, no links, no relations
Low: Missing interfaces, no runbooks, no changelog