Skill catalogue API

Available now Two routes for scripts and tooling that work with the

SOM skill library: read the library as data, and check configured instances before you register them. Neither needs a sign-in or credentials, and neither stores anything.

They're served by the portal, not the bus API: the base URL is the portal's (https://sombus.rnd-solutions.net on the Sandbox, the Preview's from Environments).

Method and path	Auth	Purpose
GET /api/skills/library	None	The library the bus implements: the versions it carries, and one version's pinned source and every skill with its topics, authority scale and config fields
POST /api/skills/validate	None	Check one configured instance, a list of them or a whole skills file, exactly as a registration is checked. Nothing is stored

Both are rate limited per route, for everyone together: GET /api/skills/library 10 requests a second (bursts of 20), POST /api/skills/validate 5 a second (bursts of 10). Over the limit: 429. Retry after a pause.

Read the library

curl -s https://sombus.rnd-solutions.net/api/skills/library

{
  "library": { "version": "0.2.2", "status": "current", "suite": "som-1.0.0+lib-0.2.2", "som_version": "1.0.0",
               "source": "https://github.com/storyobjectmodel/som/tree/7297fef9adc6d14a74bdd7550c78decaa099a1ad/skills/skills",
               "source_commit": "7297fef9adc6d14a74bdd7550c78decaa099a1ad" },
  "versions": [ { "version": "0.2.2", "status": "current", "suite": "som-1.0.0+lib-0.2.2" } ],
  "skills": [
    { "skill_id": "smart-stories/raise-flag-on-match", "name": "raise-flag-on-match", "skill_version": "0.2.2",
      "category": "compliance", "severity_range": ["flag", "inform"], "authority_scale": "required",
      "recall_on": [ { "message_type": "story.context", "spec": "schema", "schema": "story-context" },
                     { "message_type": "asset.ingested", "spec": "pending-spec" } ],
      "fields": [ { "name": "match_field", "kind": "path", "required": true, "about": "The dot path of the field watched, …" },
                  { "name": "severity", "kind": "enum", "required": false, "options": ["flag", "inform"], "about": "…" },
                  … ] },
    …
  ],
  "topics": [ { "message_type": "asset.context", "spec": "pending-spec" }, … ],
  "field_kinds": { "path": "A dot path on story.context …", … }
}

Field	Meaning
library	The library version this answer describes, its status, its suite id, the SOM version and the library commit the bus pins
versions	Every library version the bus carries, newest first, each current (new configured instances use it), supported or retired. See Library versions and upgrades. Today the bus carries 0.2.2 only
skills[].recall_on[].spec	schema: SOM 1.0 defines the message type, and schema names the schema that checks it. pending-spec: it has no 1.0 schema. See Topics without a 1.0 schema
skills[].authority_scale	required: the skill compares authorities, so a configured instance carries the house's scale. optional: it doesn't
skills[].fields	The values a configured instance sets: kind says how each is checked (see field_kinds), options lists an enum's values or a row's keys
topics	Every message type any skill recalls on, once

Without a query it describes the current version. Add ?version= to read another version the bus carries, for example /api/skills/library?version=0.2.2; a version it doesn't carry is 404 with code: skills.version_unknown.

The answer changes only when the bus's library does. It carries an ETag and may be cached for five minutes; send If-None-Match to get a 304 when it hasn't changed. The same data, as pages: Skill library catalogue.

Check configured instances

Send a configured instance, a list of them, or a whole skills file. Each instance is checked exactly as a house registration is (Run skills in your house): the skill and its version (left out: the current one; another version the bus carries is checked against that version), the instance_label, every value against the skill's fields, every story path against SOM 1.0's story.context, and each authority against the instance's scale. In a list, each instance_label must be unique.

A skills file, as YAML: a file with a skills: section (a house export has one), or a bare list.

curl -s https://sombus.rnd-solutions.net/api/skills/validate \
  -H 'content-type: application/yaml' --data-binary @skills.yaml

skills:
  - skill_id: smart-stories/raise-flag-on-match
    skill_version: 0.2.2
    instance_label: house-breaking-indicative-category
    values: { match_field: lifecycle.phase, match_value: BREAKING, flag_name: BREAKING, clearing_authority: duty-editor }
    authority_scale: [editor-in-chief, duty-editor, producer]

Or as JSON, one of:

Body	Checks
{ "instance": { … } }	One configured instance
{ "skills": [ … ] }, or a bare [ … ]	A list of them
{ "yaml": "skills:\n - …" }	A skills file's text

{
  "valid": false,
  "library_version": "0.2.2",
  "checked": "list",
  "instances": [
    { "index": 0, "instance_label": "house-breaking-indicative-category", "skill_id": "smart-stories/raise-flag-on-match",
      "valid": false, "problems": ["values.match_field: lifecycle.stage is not a field of SOM 1.0 story.context."] }
  ],
  "problems": []
}

• library_version is the current version.
• 200 whether or not the instances are valid: valid is true only if every instance is. Each instance's problems say what to fix, one line each.
• problems at the top level are about the input as a whole, such as more than 200 instances.
• A skills file's consumer on an instance (the executor that runs it, in a bus config) is accepted but not checked here: that needs the bus config it belongs to.
• 400 with code: skills.unreadable if the body can't be read: empty, over 256 KB, not JSON or YAML, or a file with no skills: section.

The body is checked and forgotten: it is never stored or logged.