JSON Schemas

semrel veröffentlicht versionierte JSON Schema-Dokumente sowohl für die zentrale .semrel.yaml-Konfiguration als auch für jedes registrierte Plugin. Jeder Editor, der yaml-language-server unterstützt, kann diese Schemas für Inline-Validierung und Autovervollständigung verwenden — ganz ohne zusätzliche Erweiterungen.

Füge deiner .semrel.yaml einen einzigen Kommentar hinzu:

# yaml-language-server: $schema=https://registry.semrel.io/schemas/core/v1.json
schemaVersion: 1
tagPrefix: "v"

plugins:
  - uses: @semrel/analyzer-conventional
  - uses: @semrel/provider-github
    args:
      token: ${{ env.GITHUB_TOKEN }}

Das ist alles. Dein Editor wird jetzt:

• Unbekannte Top-Level-Schlüssel markieren
• Vor fehlenden Pflichtfeldern warnen
• Autovervollständigung für tagPrefix, branch, plugins usw. anbieten

{
  "yaml.schemas": {
    "https://registry.semrel.io/schemas/core/v1.json": [
      ".semrel.yaml",
      ".semrel.yml"
    ]
  }
}

require('lspconfig').yamlls.setup({
  settings = {
    yaml = {
      schemas = {
        ["https://registry.semrel.io/schemas/core/v1.json"] = ".semrel.yaml",
      },
    },
  },
})

Jedes offizielle Plugin hat ein veröffentlichtes JSON-Schema, das den args:-Block beschreibt. Einen yaml-language-server-Kommentar an der args:-Zeile ergänzen, um Inline-Validierung und Autovervollständigung zu aktivieren:

# yaml-language-server: $schema=https://registry.semrel.io/schemas/core/v1.json
plugins:
  - uses: @semrel/provider-github
    # yaml-language-server: $schema=https://registry.semrel.io/schemas/plugins/github/latest.json
    args:
      token: ${{ env.GITHUB_TOKEN }}
      owner: MyOrg
      repo: my-repo
      assets: dist/*.tar.gz

  - uses: @semrel/hook-slack
    # yaml-language-server: $schema=https://registry.semrel.io/schemas/plugins/slack/latest.json
    args:
      webhook_url: ${{ env.SLACK_WEBHOOK }}
      channel: "#releases"

Alle Schema-Endpunkte werden von GitHub Pages ohne HTTP-Redirect ausgeliefert. latest.json ist eine Kopie der aktuellen Version und wird bei neuen Plugin-Releases aktualisiert.

Wenn du eine private semrel-registry-Instanz betreibst, ersetze die Basis-URL:

# yaml-language-server: $schema=https://my-registry.example.com/schemas/core/v1.json

Die Registry liefert Schemas über den Pfad /schemas/ auf demselben Host wie die API aus.

semrel kann deine Konfigurationsdatei gegen das veröffentlichte Schema validieren, ohne ein Release auszuführen:

semrel config validate
# ✓ Config is valid (schema version 1)

semrel config validate --config path/to/.semrel.yaml

Wenn die Validierung fehlschlägt, wird ein Exit-Code ungleich null zurückgegeben. Das macht den Befehl gut geeignet für CI-Pre-Checks:

- name: Validate semrel config
  run: semrel config validate

Schemas folgen der SemVer-Major des semrel-Konfigurationsformats:

Wenn eine Breaking-Change an der Konfiguration eingeführt wird, wird ein neues v2.json zusätzlich zu v1.json veröffentlicht. Der Redirect latest.json wird erst aktualisiert, wenn die neue Version stabil ist.

Verwende semrel migrate, um deine Konfigurationsdatei auf die aktuelle Schema-Version zu aktualisieren:

semrel migrate --dry-run   # preview changes
semrel migrate             # apply in-place (creates .semrel.yaml.bak backup)

Wenn du ein semrel-Plugin pflegst, füge deinem Repository eine Datei schema/v1.json hinzu, die die SEMREL_PLUGIN_*-Umgebungsvariablen beschreibt, die dein Plugin akzeptiert:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://registry.semrel.io/schemas/plugins/my-provider/v1.json",
  "title": "my-provider plugin schema",
  "type": "object",
  "properties": {
    "SEMREL_PLUGIN_TOKEN": {
      "type": "string",
      "description": "API token for the target platform."
    },
    "SEMREL_PLUGIN_OWNER": {
      "type": "string",
      "description": "Repository owner / organisation."
    }
  },
  "required": ["SEMREL_PLUGIN_TOKEN"]
}

Wenn dein Plugin in der semrel-registry registriert ist, wird das Schema automatisch unter /schemas/plugins/{name}/v1.json ausgeliefert.

Sieh im plugin development guide nach, wenn du eine vollständige Schritt-für-Schritt-Anleitung möchtest.