---
name: servicetypes-validator
description: Validate a Metavshn connector serviceTypes.json file against the official schema and consistency rules. Use when a user asks to lint, check, or fix a serviceTypes document, or when working on a Metavshn provisioning connector.
---

# Metavshn serviceTypes validator

Local-only, deterministic validator for the JSON files used by Metavshn provisioning connectors. No network calls except optionally fetching the input JSON. Same engine that powers https://metavshn.com/en/tools/serviceTypesAnalyzer.

## When to use

- The user references a `serviceTypes.json`, `resourcesSpec`, or a Metavshn connector definition.
- The user pastes JSON and asks "is this valid?", "lint this", or "what's wrong with this".
- You are generating or modifying a serviceTypes document and want to self-check before returning it.

## Two ways to use it

### A. MCP (recommended for repeated use)

Download the single-file stdio MCP server:

```
curl -L -o servicetypes-mcp.mjs https://metavshn.com/mcp/servicetypes-mcp.mjs
```

Add to your agent's MCP config (Claude Desktop, Cursor, Cline, Continue, …):

```json
{
  "mcpServers": {
    "servicetypes": {
      "command": "node",
      "args": ["/absolute/path/to/servicetypes-mcp.mjs"]
    }
  }
}
```

Requires Node.js ≥ 18. Zero dependencies, no install step, no auth.

Then call the tool:

```
tool: validate_service_types
args: { "json": "<raw JSON text>" }
   or { "url":  "https://example.com/serviceTypes.json" }
```

### B. One-shot fallback (no MCP)

Open the hosted UI and paste the JSON: https://metavshn.com/en/tools/serviceTypesAnalyzer

Or fetch the schema and validate locally with any JSON-Schema validator (ajv, etc.):

```
https://metavshn.com/mcp/service-types.schema.json
```

Note: the schema covers structural rules. The MCP tool *also* runs consistency checks (duplicate ids/keys, missing locales, unknown categories, cross-container key reuse, etc.) that schema validation alone cannot express. Prefer the MCP tool when available.

## Output contract

The tool returns a single text content block whose body is JSON of shape:

```ts
{
  ok: boolean,                           // true iff counts.error === 0
  counts: { error: number, warning: number, info: number },
  findings: Array<{
    severity: "error" | "warning" | "info",
    code: string,                        // e.g. DUPLICATE_PROPERTY_KEY
    message: string,
    path: string,                        // JSONPath-ish, e.g. $[0].properties[3].key
    context?: Record<string, unknown>
  }>,
  stats: {
    serviceTypes: number, properties: number, options: number,
    resources: number, actions: number, qualificationTypes: number,
    resourceInstances: number, unknownPropertyKeys: number
  }
}
```

When surfacing results to the user, group findings by `path` prefix (`$[i]` → service type *i*) and lead with errors. `isError` on the MCP response mirrors `!report.ok`.

## Common finding codes

- `ROOT_NOT_ARRAY`, `EMPTY_ROOT` — top-level shape problems.
- `DUPLICATE_SERVICE_TYPE_ID`, `DUPLICATE_PROPERTY_KEY`, `DUPLICATE_OPTION_ID`, `DUPLICATE_RESOURCE_ID`, `DUPLICATE_RESOURCE_KEY`, `DUPLICATE_ACTION_ID`, `DUPLICATE_ACTION_KEY`, `DUPLICATE_QUALIFICATION_ID` — uniqueness violations; fix by renaming or removing the duplicate.
- `MISSING_LOCALE`, `UNKNOWN_LANG_CODE`, `DUPLICATE_LOCALE`, `EMPTY_SHORT_NAME` — localization issues. Required locales: `en`, `de`, `it`.
- `UNKNOWN_CATEGORY`, `UNKNOWN_RESOURCE_TYPE`, `UNKNOWN_DATATYPE`, `UNKNOWN_SCOPE` — value not in the allowed enum; check the schema for valid values.
- `SAME_NAME_DIFFERENT_KEY` — likely typo: same English name reused with different keys.
- `KEY_REUSED_ACROSS_CONTAINERS` (info) — same key used in multiple containers (properties/options/resources/actions); usually intentional but worth confirming.

## Sample

A tiny valid example for sanity-checking your setup:

```
https://metavshn.com/mcp/example.serviceTypes.json
```

## Source & manifest

- Manifest: https://metavshn.com/mcp/manifest.json
- Schema:   https://metavshn.com/mcp/service-types.schema.json
- Server:   https://metavshn.com/mcp/servicetypes-mcp.mjs
- UI:       https://metavshn.com/en/tools/serviceTypesAnalyzer